Local installation of the SDK

The UniteLabs SDK provides a simple interface for developers to integrate devices in their applications.

This guide is designed to help with the setup of your local development environment and send your first API request. If you are an experienced developer or want to dive right into using the UniteLabs API, the Reference is a great place to start. Throughout this guide, you will learn:

• How to setup your development environment
• How to install the latest SDK
• How to send your first API request
• How to improve the developer experience in your IDE

Prerequisites

UniteLabs requires Python 3.9 or newer. It is platform independent and works equally on Linux, macOS and Windows.

Some steps in this guide require authentication, therefore you need:

• UniteLabs Artifactory Access A username and password to install UniteLabs Python packages. Packages are not hosted publicly and need to be downloaded by a package manager like poetry from the UniteLabs GitLab Artifactory.
  • Username: 32 characters separated by dashes.
    Example: 56ae938f-484c-41cc-ae54-e4f9b8814fb7
  • Password: 22 characters separated by dashes.
    Example: ahjt-Lk-e1swOPZcWYYGh-mKJ
• UniteLabs Client Credentials Client ID and secret to authenticate connections made from your local SDK installation (your code/client) to the UniteLabs API (the platform).
  • Client ID: A custom username with variable length.
  • Client Secret: 32 characters without separators.
    Example: YT1a2HFEoi8tiAwl6bv127Tqp0ZXDSru
  • Tenant ID: 32 characters separated by dashes.
    Example: ad2a8e12-2bf2-45d7-9fb1-84bdf7102a8c

If you are missing one of them, please reach out to your UniteLabs contact.

Install packages

We recommend installing the UniteLabs SDK using a Python virtual environment manager such as uv, Poetry or venv. All packages are provided in a private artifactory that requires configuration and authentication.

machine gitlab.com
login <username>
password <password>

uv init --package my-app
cd my-app

uv add unitelabs-liquid-handling \
  --index unitelabs=https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

poetry config http-basic.unitelabs <username> <password>
poetry config virtualenvs.in-project true

poetry new my-app --src
cd my-app

poetry source add --priority=supplemental unitelabs \
  https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple
poetry add --source unitelabs unitelabs-liquid-handling

machine gitlab.com
login <username>
password <password>

mkdir my-app
cd my-app
python -m venv .venv
.venv/bin/pip install -U pip

.venv/bin/pip install unitelabs-liquid-handling \
  --index-url https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

Authenticate client

You need to authenticate your UniteLabs client to access the UniteLabs API on your behalf. We suggest to use python-dotenv to load the UniteLabs Client Credentials from a .env file in the root of your project.

BASE_URL=https://api.unitelabs.io/<tenantID>
AUTH_URL=https://auth.unitelabs.io/realms/<tenantID>/protocol/openid-connect/
CLIENT_ID=<clientID>
CLIENT_SECRET=<clientSecret>

Security note:
When using version control, make sure to exclude the .env file by e.g. adding it to the .gitignore file.

Send your first request

import asyncio

from unitelabs.sdk import Client

from dotenv import load_dotenv


async def main():
    async with Client() as client:
        connectors = await client.list_services()
        for connector in connectors:
            print(connector.name)


if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())

Run the package's __main__.py file with:

uv run python -m my_app

poetry run python -m my_app

.venv/bin/python -m my_app

Versions

The installation defaults to the latest version. If a defined version is required or needs to be locked, it must be explicitly defined using the PEP 440 Version Specifier(==, !=, <, >, <=, >, >=) in the pyproject.toml.

[project]
requires-python = ">=3.9,<4.0"
dependencies = [
    "unitelabs-liquid-handling~=0.2.0",
    "python-dotenv",
]

The installed version can be checked using __version__:

from unitelabs import labware, liquid_handling, sdk

if __name__ == "__main__":
    print(sdk.__version__)
    print(labware.__version__)
    print(liquid_handling.__version__)

Run the file as explained above.

IDE integration

VSCode

{
  "recommendations": ["ms-python.python"]
}

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.terminal.activateEnvironment": false
}

PyCharm

Details coming soon!