Basic Usage

Warning

Before proceeding, be sure that you want to connect to a XFSessionServer type. This library just works with that kind of server.

Installation

You can install the required libraries to use a remote session server with pip:

$ pip install xfss

As simple as that!

Note

Currently, the library is stored only on PyPi. Be sure to use that repository.

Initial Configuration

To get started, import the RemoteSession and Auth classes.

1 from xfss.Auth import Auth
2 from xfss.RemoteSession import RemoteSession

Then, you have to indicate a couple of values, and you’re off to the races!

Don’t worry, we’ll explain each line.

3 Auth.set_user_origin(User)
4 Auth.set_user_keys(["email", "password"])
5 Auth.set_role_attribute("role")
6
7 RemoteSession.set_address("192.168.1.100")
8 RemoteSession.set_port("42100")

On line 3, we indicate the user class that we want to create remote sessions for. If you have multiple types of users, just set it to the user base class. You do remember those inheritance and polymorphisms lectures, right?

On line 4, we supply a list with the names of the required user attributes to create a session. At least two attributes are required, and there’s no upper limit. The example shows the recommended attributes.

The 5th line is optional. If your application has user roles, such as admin, moderator, seller, content creator or anything else, you can set the attribute name of the user class where you store that value.

For example, if the user class is something like this:

class User:
    def __init__(self):
        self.email = None
        self.password = None
        self.role = "client"

Then we need to indicate the role attribute. The role attribute can be of any primitive type.

In the 7th line, we supply the address for the remote session server. It can be any type of URl, IPv4 or IPv6 address.

Lastly, the 8th line is optional. If you need to specify a port, you set it here. It can be a string or an integer.

The port number could be set in along with the address like this:

RemoteSession.set_address("192.168.1.100:42100")

Creating a new session

After the initial config, we are ready to go!

Create a new session in the remote server with the following code.

payload = {
    "email": "user1@mail.com",
    "password": "aG00dP4sw00rD",
    "role": "client",
    "birthday": "07/19/1999",
    "is_admin": False
}
response = RemoteSession.init_session(payload)

The payload is the information that will be sent to the server. The only required fields are the ones you set in the configuration section. Besides that, you can put anything you want to store in the remote server.

Keep in mind that all the info you send will only be stored while the session is alive.

The response variable holds the server response (duh!). It is a dictionary that holds two values, an HTTP STATUS and (possibly) a TOKEN.

If the request was successful and a new session was created, the STATUS key holds an HTTP status code of 201, and the TOKEN key a string. This string is the session token. Keep it in a safe place, cause you will need it for every future request regarding the session you just created.

This token is like a session ID of sorts. Yeah! That’s it!

If the request was not successful, you can find the corresponding HTTP status code in the first position of the tuple.

In code would look something like this:

response = RemoteSession.init_session(payload)
status_code = response["STATUS"]

if status_code == 201:
    # Yay! We got a token
    token = response["TOKEN"]
else:
    # The request failed. Let's see why
    # Proceed to handle the HTTP status code as you see fit

Note

This new session implementation will definitely change in the future. I hope to make it easier to handle.

Getting stored information

You created a remote session? Great! Now let’s see how to check the information we stored.

data = RemoteSession.get_session_info(token)
print(data["birthday"])

Remember the token? Now it’s time to use it. Pass it to the function shown above and it will take your information back.

Easy, right?

Update session data

You have sent the wrong information? Don’t worry. We can change it easily.

new_data = {
    "birthday": "10/19/1999",
    "is_admin": True
}
RemoteSession.update_data(token, new_data)

Just like that we can send the new_data to replace the old one in the server.

It’s like magic!

Is the session alive?

How much time have passed since you created the session? Surely it has been destroyed.

To check if the session is alive in the remote server, do something like this:

is_alive = RemoteSession.is_session_alive(token)
if is_alive:
    print("Yay! It is still alive")
else:
    print("Well, it was good while it lasted")

Just one line can tell you if the session is still alive on the other end. You can thank me later. ; )

Destroy the session

Like everything in life, it must end.

It seems that the time to destroy the session has come. Don’t cry. It will be quick, and painless.

RemoteSession.close_session(token)

Just like that, it’s gone.

Be sure to retrieve all your data before destroying a session. Once a session has been destroyed, the information cannot be recovered. It’s gone. Forever.

Note

Even if you don’t purposely destroy a session, it will be removed after some inactivity time.

The default session lifetime is 10 minutes since the last operation. If you have not performed an operation in the las 10 minutes, you can say goodbye.

To keep a session from being destroyed, you can use RemoteSession.is_session_alive to restart the 10 minute timer.