SESSION Basics

The SESSION object handles all data exchange between Python and LabGuru. It will be configured and run any time you import it:

from LabGuruAPI import SESSION

It is also used by a number of search and convenience functions in the LabGuruItem and Collections classes.

Logging in

The first time you import SESSION or run a method that interacts with the LabGuru API, you will be asked to log in with your LabGuru name and password. You can also force a login with the login() method.

>>> from LabGuruAPI import SESSION
>>> SESSION.login()
Please Login to LabGuru
Username: first.last@grobio.com
Password: DontUseThis4Real

Caution

Your password will be visible on the screen!

The SESSION object will then send your credentials to LabGuru and get a token that can be used for 1 month.

If you have previously logged in, the SESSION object will check if your token is still valid. If it is not, you will be asked to provide your credentials again. (We may reduce the output to only the first line at some point in the future.)

>>> from LabGuruAPI import SESSION
>>> SESSION.login()
Trying token abcdefghijklmnopqrstuvwxyz123456789ABCDE
200
'abcdefghijklmnopqrstuvwxyz123456789ABCDE'

Config Management

SESSION can also be used to interact with a local configuration file. This will allow you to store simple strings (like the auth token) and reuse them between scripts.

Storing a value

You can store a value for later using the SESSION.set_config_value() method.

Session.set_config_value(section: str, key: str, value: Any)[source]

Writes a key-value pair to the configuration file.

Parameters:

  • section – Config file section

  • key – Config key to set

  • value – Value of the config key. Will be converted to a string before writing

Retrieving a value

You can retrieve a previously stored value using the SESSION.get_config_value() method.

Session.get_config_value(section: str, key: str, ask=False) → str[source]

Retrieves a configuration value from the config file.

Parameters:

  • section – Config file section

  • key – Config key to retrieve

  • ask – If true, prompts the user for a value if the key is not found. Will store and return the value.

Returns:

The configuration value string

Raises:

KeyError – The configuration Section or Key does not exist if the ask parameter is False

Example Usage

In the Plasmid class, config values are used for setting the origin property. Our LIMS structure limits the value of origin to a specific list of options. If a user attempts to set origin to a different value, it needs to be substituted for one of the valid options. The setter method presents the user with the list of options, and prompts them to choose the correct one. This is useful, but would get tedious if you had a long list of plasmids with the same incorrect origin name. You can expect to see the name again in future projects, as well. So the setter method uses the config file to map the incorrect origin names to allowed ones.

Let’s say you’re adding a plasmid with the 'p15A' origin. On the input spreadsheet, though, the plasmid is listed as 'pA15'.

>>> plasmid.origin = 'pA15'

This is not a valid option, but before asking the user what they meant, we check to see if we’ve seen this typo before.

>>> SESSION.get_config_value('ORIGINS', 'pA15', ask=False)
'p15A'

Great! We’ve seen this before and can set it to the correct value. But if we hadn’t…

>>> SESSION.get_config_value('ORIGINS', 'pA15', ask=False)
KeyError: 'pA15'

In this case, the method would prompt the user to choose the correct value from a list. We’ll then store it for next time.

>>> good_val = prompt(...)  # user selects p15A
>>> SESSION.set_config_value('ORIGINS', 'pA15', good_val)

Generic API Interactions

HTTP Request Methods

SESSION provides the get(), post(), put(), and del_request() methods to interact with any API endpoints that are not built into a corresponding LabGuruItem object.

Session.get(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends a GET request to a specified API endpoint using given data and returns the response as a JSON object if the request is successful.

The method appends the authentication token to the request data and sends a GET request to the constructed API path using the input endpoint and additional data. If the response status is successful, it returns the response content as a JSON object. Otherwise, it returns None.

Parameters:

  • endpoint – The API endpoint to send the GET request to.

  • **data – Additional data to be included in the request. This data will be sent as a JSON object in the GET request.

Returns:

A dictionary containing the JSON response data if the request is successful. Returns None if the request fails.

Example Usage

This package does not provide a class for interacting with LabGuru’s Equipment collection, but the API does. If, for some reason, you wanted to list all of the equipment in company, you could make a HTTP GET call to the api/v1/instruments endpoint. You will need to add the endpoint as the full string, or the part after api/v1/.

>>> SESSION.get('instruments')
{'items':[{... instrument 1 ...}, {... instrument 2 ...}, ...]}

If the call is successful, it will return a dictionary corresponding to the parsed JSON result. If the call is unsuccessful, it will return None.

You can also pass arguments to the methods, which will be included as JSON in the request body. Say you wanted to add a new type of experiment flag. Looking at the API documentation, you will need to provide a JSON string with the 'item' key, which is a dictionary of the new flag’s properties.

>>> new_flag = dict(title='Needs Review', icon='question', color='orange-light', description='Please review this!')
>>> SESSION.post('flags', item=new_flag)
{'flag': {'id': 3, 'title': 'Needs Review', ...}}

For all of the request types, your current active authorization token will be added in the appropriate location.