Session¶

Introduction¶

The Session object is central to the apteco package. It is the ‘key’ for connecting to the Apteco API, so performs a similar role to an API Client object in other API wrapper packages (see py-trello, PyGitHub). But as well as handling API requests it also holds a copy of the core data for the FastStats system it is connected to, similar to the System tab within the Apteco FastStats desktop application. This lets you easily access FastStats tables and variables to perform data analysis quickly.

As you carry out your analysis, fetching different FastStats objects, creating selections and producing other results, each object is passed a reference to the current active Session object, so you can use any of these as the starting point for further analysis without having to reconnect to the Apteco API.

Basic use¶

Logging in by entering your password in the terminal (it won’t be echoed):

>>> from apteco import login
>>> my_session = login("https://orbit.my-site.com/OrbitAPI", "my_data_view", "my_system", "jdoe")
Enter your password:

Logging in by giving your password in the function call:

>>> from apteco import login_with_password
>>> my_session = login_with_password(
...     "https://orbit.my-site.com/OrbitAPI",
...     "my_data_view",
...     "my_system",
...     "jdoe",
...     "P@ssw0rd123!",  # Beware - password is visible in the code!
... )

Accessing tables and variables:

>>> people = my_session.tables["People"]
>>> cost = my_session.variables["Cost"]

Serializing and deserializing the session:

>>> s = my_session.serialize()
>>> from apteco import Session
>>> my_restored_session = Session.deserialize(s)

API reference¶

Login functions¶

These functions can be imported directly from apteco, and can be called to log in to the Apteco API and return a Session object.

apteco.login(base_url: str, data_view: str, system: str, user: str)¶

Return a Session object connected to the given FastStats system.

Parameters

base_url (str) – API base URL, normally ending ‘/OrbitAPI’
data_view (str) – DataView being logged into
system (str) – FastStats system to connect to
user (str) – username of API user

You will be asked to enter your password in the terminal. If you are not using a terminal, or Python is not able to prevent your password from being echoed, a pop-up box will be opened where you can enter your password instead.

apteco.login_with_password(base_url: str, data_view: str, system: str, user: str, password: str)¶

Return a Session object connected to the given FastStats system.

Parameters

base_url (str) – API base URL, normally ending ‘/OrbitAPI’
data_view (str) – DataView being logged into
system (str) – FastStats system to connect to
user (str) – username of API user
password (str) – password for this user

This function is identical to the previous login function, but with an additional fifth argument in the function call for you to enter your password directly.

Warning

Be mindful of security when using this function and avoid storing passwords in plain text in code files.

Apteco API session properties¶

These attributes on the Session object are the core pieces of data that identify the Apteco API instance which it’s connected to.

Session.base_url¶: URL for your Apteco API (Orbit API) installation

Session.data_view¶: name of the DataView you’re connected to

Session.system¶: name of the system you’re using within the DataView

Session.access_token¶: token used to authenticate with the API (this is a JWT)

Session.session_id¶: traditional FastStats session ID

Session.api_client¶: apteco-api.ApiClient object which handles all the API requests, using the apteco-api package

FastStats system metadata¶

These attributes on the Session object contain metadata about the FastStats system the object is connected to.

Session.system_info¶

namedtuple representing the FastStats system, with the following attributes:

name (str): system name
description (str): system description
build_date (datetime.datetime): date the system was build
view_name (str): DataView the system belongs to

Session.user¶

namedtuple representing the user, with the following attributes:

username (str): username (used to log in)
first_name (str): user’s first name
surname (str): user’s surname
email_address (str): user’s email address

Tables and Variables¶

These attributes on the Session object provide access to the tables and variables data for the FastStats system the object is connected to.

Session.tables¶

An object providing both list-like and dict-like access to tables. Tables can be looked up by name to retrieve their corresponding Table object:

>>> my_session.tables["Communications"]
<apteco.tables.Table object at 0x0000020FC2E5A240>

You can also count the tables using the built-in len() function and iterate over them:

>>> len(my_session.tables)
9
>>> for table in holidays.tables:
...     print(f"{table.total_records:>9,} {table.plural}")
...
  742,565 Households
1,156,553 People
2,130,081 Bookings
  213,567 Policies
  279,538 WebVisits
   70,705 Communications
   55,653 Journeys
  153,041 Content
    1,549 Responses

Tip

You may find it helpful to allocate commonly-used tables to Python variables at the beginning your script or interactive session for easier use and reference:

>>> households = my_session.tables["Households"]
>>> people = my_session.tables["People"]
>>> bookings = my_session.tables["Bookings"]