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 Poetry, conda, or venv. All packages are provided in a private artifactory that requires configuration and authentication.

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.

If you have not used poetry before, you can follow any of the options in the official Poetry installation instructions.

1. Prepare Poetry

When poetry is available (try poetry -V in your terminal), you need to provide the UniteLabs Artifactory Access for poetry to be able to install the required dependencies. Optionally, we suggest to configure poetry to create the Python virtual environment within your project folder.

Terminal

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

Security note:
Depending on your system configuration, credentials might be saved in your command line history. Many shells do not save commands to history when they are prefixed by a space character. For more information, please refer to your shell’s documentation.

2. Setup Project

Terminal

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

3. Install UniteLabs

Terminal

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

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.

.env

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

src/my_app/__main__.py

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:

Terminal

poetry run 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.

pyproject.toml

[tool.poetry.dependencies]
python = "^3.9"
unitelabs-sdk = {version = "^0.2.7", source = "unitelabs"}
unitelabs-lib = {version = "^0.1.22", source = "unitelabs"}
python-dotenv = "^1.0.1"

The installed version can be checked using __version__:

__main__.py

import unitelabs.sdk as sdk

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

Run the file as explained above

IDE integration

VSCode

.vscode/extensions.json

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

.vscode/settings.json

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

PyCharm

Details coming soon!

Overview

Everything you need to know to automate your workflows, our Python SDK, and the REST API.

Importing a connector

Importing a connector with the SDK in Python.