Session Class

class rosteron.Session(url: str, browser: mechanicalsoup.StatefulBrowser = StatefulBrowser())

A Session object represents a connection to a RosterOn server, managing logging in, roster Snapshot retrieval, logging out, and optional file-based logging of RosterOn HTTP requests & responses.

Session objects are context managers, enabling automatic session log-out if used in a with block:

with Session(...) as session:
    session.log_in(...)
    snapshot = session.get_roster()

# session will always be logged out by this point
Parameters:
  • url – the base URL of the Mobile version of the RosterOn instance, e.g. https://rosteron.example.com.au/RosterOnProd/Mobile. The correct URL can be obtained for a RosterOn Mobile instance by visiting its “Log In” page in a browser and copying the portion of the URL prior to /Account/Login.
  • browser – if specified, a custom mechanicalsoup.StatefulBrowser instance. Not required in normal usage; primarily intended for testing & diagnostic purposes.

log_in() Method

Session.log_in(username: str, password: str)

Log in to RosterOn with the specified user credentials.

Parameters:
  • username – the RosterOn user whose shifts are to be retrieved.
  • password – the relevant RosterOn user’s password.
Raises:
Returns:

this Session object, such that a log_in() call can be used in a with block if desired:

with session.log_in(...):
    snapshot = session.get_roster()

# session will always be logged out by this point

get_roster() Method

Session.get_roster() → rosteron.Snapshot

Retrieve a snapshot of the logged-in user’s roster.

Return type:

Snapshot
Raises:

log_out() Method

Session.log_out() → None

If a user is logged in to RosterOn, log them out; otherwise, do nothing.

This method is called automatically if the Session is used in a with block:

with Session(...) as session:
    session.log_in(...)
    snapshot = session.get_roster()

# session will always be logged out by this point
Raises:BadResponseError – if a user is logged in and the RosterOn server returns an unexpected response while attempting to log out.

save_logs() Method

Session.save_logs(directory: str) → None

Log, to the specified directory, all RosterOn server requests & responses made over the life of the Session. Intended only for diagnostic purposes. Login credentials are not logged.

Each request/response will be saved to <yyyymmddThhmmss.microseconds>Z-<purpose>-<n>.txt in the specified directory, where:

  • <yyyymmddThhmmss.microseconds>Z is the date & time of the initial request in UTC;
  • <purpose> is the type of output expected for the operation triggering the initial request (login, home, roster, or logout); and
  • n is 0 for the initial request/response pair in one operation, and a higher number for each subsequent request/response pair in that operation.

The typical Session usage of logging in, retrieving the roster, and logging out triggers requests & responses that would be logged as such:

20190610T042837.160169Z-login-0.txt
20190610T042838.576616Z-home-0.txt
20190610T042838.576616Z-home-1.txt
20190610T042838.934080Z-roster-0.txt
20190610T042839.134057Z-logout-0.txt
20190610T042839.134057Z-logout-1.txt

Each file will contain the date & time of the request, the request method & URL (not login credentials), and the server response (including status and headers):

2019-06-10 04:28:37.160169+00:00
GET https://rosteron.xyz.com.au/RosterOnProd/Mobile/Account/Login
200 OK

Date: Mon, 10 Jun 2019 04:28:38 GMT
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
...
Parameters:directory – The directory where the requests & responses will be logged, which is assumed to exist and have appropriate write permissions.