pysll 0.3.8

No project description provided

PySLL

SDKs and example code for accessing the Constellation APIs that power Emerald Cloud Lab.

The constellation API

Detailed documentation about the Constellation API can be found at www.emeraldcloudlab.com/internal-developers-api.

Environment Variables

If you are setting these in your .bash_profile (or similar), make sure to export them or they won't be available to os.environ.

Standard Credentials

• CONSTELLATION_AUTH_TOKEN (Optional)
• CONSTELLATION_USERNAME (Required if no token)
• CONSTELLATION_PASSWORD (Required if no token)

Test Credentials

To run the test suite, use the PYTEST prefix. The login has to be [e-mail] since some tests expect this user ID.

• PYTEST_CONSTELLATION_AUTH_TOKEN (Optional)
• PYTEST_CONSTELLATION_USERNAME (Required if no token)
• PYTEST_CONSTELLATION_PASSWORD (Required if no token)

Example for tests:

export PYTEST_CONSTELLATION_USERNAME="your_username"
export PYTEST_CONSTELLATION_PASSWORD="your_password"

Development Setup

After cloning the repository, set up the development environment:

# Install dependencies
uv sync --dev

# Install git hooks for pre-commit and pre-push
uv run pre-commit install
uv run pre-commit install --hook-type pre-push

The pre-commit hooks will automatically:

• Run ruff formatting and linting on commit
• Run pyright type checking on commit
• Run the full test suite on push

Quick start

Install with pip:

pip install pysll

To use the SDK:

>>> from pysll import Constellation
>>> from pysll.models import Object
>>> client = Constellation()

To login:

>>> client.login("[e-mail]", "myAwesomePassword")

To get information about the current user once you are logged in:

>>> me = client.me()
>>> print(me)
{'Email': '[e-mail]', 'EmailAddress':'[e-mail]', 'Id': 'id:abc123', 'Type': 'Object.User', 'Username': 'scientist'}

To download information from an object:

>>> client.download(Object(me["Id"]), ["Name", "Email"])
["scientist", "[e-mail]"]

To search for objects of a specific type:

>>> client.search("Object.User.Emerald.Administrator", "")

Searching with conditions

You can perform more specific searches by providing an SLL query string:

>>> client.search(
...     "Object.SupportTicket.Operations",
...     'Status="Active" AND Priority="High"'
... )

You can also limit the number of results:

>>> client.search("Object.SupportTicket.Operations", "", max_results=5)

Downloading data

You may perform a simple single field download like:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "ColumnOrientation")
'Forward'

You may download multiple fields in a single download like:

>>> client.download(Object("id:BYDOjvG4l3Ol"), ["SeparationMode", "ColumnOrientation"])
['ReversePhase', 'Forward']

You may download from multiple objects in a single download like:

>>> client.download([Object("id:o1k9jAkRM794"), Object("id:L8kPEjkw47jw")], "ColumnOrientation")
['Forward', 'Forward']

And finally, you may download multiple fields from multiple objects in a single download like:

>>> client.download([Object("id:o1k9jAkRM794"), Object("id:L8kPEjkw47jw")], ["SeparationMode", "ColumnOrientation"])
[['ReversePhase', 'Forward'], ['ReversePhase', 'Forward']]

You may also traverse links within downloads, like:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "Instrument[Model[Name]]")
'Waters Acquity UPLC H-Class ELS with Pre-Column Heater'

You can also download all of the fields on an object by not specifying a field. For example:

>>> client.download(Object("id:Z1lqpMzvkGMV"))
{'type': 'Object.User.Emerald.Developer', 'id': 'id:Z1lqpMzvkGMV'....}

Or via the "All" implicit field:

>>> client.download(Object("id:Z1lqpMzvkGMV"), "All")
{'type': 'Object.User.Emerald.Developer', 'id': 'id:Z1lqpMzvkGMV'....}

Note that in this case, the results will be a dictionary mapping field name to field value

Dealing with types

There are a number of different ways to interpret field values based off the type of data stored in the object. String, integer, and real fields are mapped to their corresponding python types - for example:

>>> client.download(Object("id:BYDOjvG4l3Ol"), ["SeparationMode", "InjectionIndex"])
['ReversePhase', 28]

Link fields will return objects, which you can chain downloads off of (although note that traversals will be much faster):

>>> client.download(Object("id:BYDOjvG4l3Ol"), "Instrument")
Object[Instrument[HPLC, "id:wqW9BP4ARZVw"]
>>> client.download(client.download(Object("id:BYDOjvG4l3Ol"), "Instrument"), "Name")
'Galadriel'
>>> client.download(Object("id:BYDOjvG4l3Ol"), "Instrument[Name]")
'Galadriel'

Date fields will be converted to native python datetime objects:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "DateCreated")
datetime.datetime(2022, 1, 9, 23, 44, 31, 746154)

Quantity arrays will be converted to python variable unit objects:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "Scattering")
[[0.0 Minutes, -87.528984 IndependentUnit[Lsus]], [0.016667 Minutes, -96.701614 IndependentUnit[Lsus]], [0.033333 Minutes, -43.93272 IndependentUnit[Lsus]], [0.05 Minutes, -132.207855 IndependentUnit[Lsus]]...

which you may manipulate to get their values and units:

>>> scattering_info = client.download(Object("id:BYDOjvG4l3Ol"), "Scattering")
>>> len(scattering_info)
361
>>> scattering_info[0]
[0.0 Minutes, -87.528984 IndependentUnit[Lsus]]
>>> scattering_info[0][0]
0.0 Minutes
>>> scattering_info[0][0].value
0.0
>>> scattering_info[0][0].unit
'Minutes'

Blob refs will be downloaded and automatically parsed in the same way:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "Absorbance")
[[0.0 'Minutes', 0.0 'Milli' 'AbsorbanceUnit'], [0.0008333333535119891 'Minutes', 0.0 'Milli' 'AbsorbanceUnit']...

Additionally, you can download multiple fields that have different units the same as you would download other fields. For example:

>>> client.download(Object("id:O81aEB16GlJ1"), "Composition")
[[4.977777777777776 Times[Power["Liters", -1], "Milligrams"], Object[Model[Molecule, "id:E8zoYvN6m61A"]], [75.11111111111111 IndependentUnit["VolumePercent"], Object[Model[Molecule, "id:vXl9j57PmP5D"]]]

Finally, you can download association fields and they will be automatically translated into python structures. For example:

>>> client.download(Object("id:XnlV5jKZwmp3"), "ResolvedOptions")['Instrument']
Object[Instrument[HPLC, "id:wqW9BP4ARZVw"]]

Download Files

Files are controlled via the auto_download_cloud_files flag to the download function. By default, they will be returned as objects and not downloaded.

For example:

>>> client.download(Object("id:BYDOjvG4l3Ol"), "DataFile")
Object[EmeraldCloudFile, "id:9RdZXv1jDAZ6"]

These may be manually downloaded via:

>>> client.download_cloud_file(client.download(Object("id:BYDOjvG4l3Ol"), "DataFile"))
'/var/folders/j_/ftdn14ms37s40j2z0h1wzxbw0000gn/T/tmp6krhb8lp/Absorbance Raw File.bin_absorbancefile'

or, it is possible to automatically download them by using the auto_download_cloud_files flag of download:

>>> data_file = client.download(Object("id:BYDOjvG4l3Ol"), "DataFile", auto_download_cloud_files=True)
>>> data_file.local_path
'/var/folders/j_/ftdn14ms37s40j2z0h1wzxbw0000gn/T/tmp6krhb8lp/Absorbance Raw File_1.bin_absorbancefile'

The format of these files can often change, but the sdk is pretty smart about interpreting them. Once you have downloaded the file, you can have the sdk attempt to parse it into python structs via the following:

>>> data_file = client.download(Object("id:BYDOjvG4l3Ol"), "DataFile", auto_download_cloud_files=True)
>>> from pysll.models import ConstellationFieldParser
>>> ConstellationFieldParser().parse_local_file(data_file.local_path)
[[0.0 'Minutes', 273.0 'Nanometers', 0.0 'Milli' 'AbsorbanceUnit'], [0.0008333333535119891 'Minutes', 273.0 'Nanometers', 0.0 'Milli' 'AbsorbanceUnit']...

If the field parser is unable to parse the file, it will return None.

Uploading data

The upload function allows you to create new objects or update existing ones.

Create a new object

To create a new object, pass None as the object_id:

>>> client.upload(
...     "Object.SupportTicket.Operations",
...     None,
...     {
...         "Name": "New Support Request",
...         "Description": "Calculated results are missing",
...         "Status": "Open"
...     }
... )

Update an existing object

To update an existing object, provide its ID:

>>> client.upload(
...     "Object.SupportTicket.Operations",
...     "id:ticket-123",
...     {"Status": "InProgress"}
... )

Advanced Upload Examples

Linking to other objects:

>>> from pysll.utils import create_one_way_link
>>> client.upload(
...     "Object.SupportTicket.Operations",
...     "id:ticket-123",
...     {
...         "Assignee": create_one_way_link("Object.User.Emerald.Developer", "id:user-456")
...     }
... )

Appending to a list field:

>>> client.upload(
...     "Object.Sample",
...     "id:sample-123",
...     {"Append[Tags]": ["tag1", "tag2"]}
... )

Setting a quantity field:

>>> client.upload(
...     "Object.Sample",
...     None,
...     {"Volume": 'Quantity[0.5, "Liters"]'}
... )

Uploading Files

You can upload local files to the cloud:

>>> client.upload_cloud_file("path/to/my_data.txt")

Notebook Context

You can specify a notebook context for your uploads:

>>> with client.notebook("id:notebook-123"):
...     client.upload("Object.Example.Data", None, {"Name": "Contextual Data"})