Set Up the Python Client#

This how-to explains how to initialize the Dioptra Python Client in a Python file or a Jupyter notebook.

Prerequisites#

Client Setup Workflow#

Step 1: Configure the Client (Optional)#

Optionally set the environment variable for the Dioptra REST API address. This will allow you to configure the client once across multiple instantiations.

The REST API is configured as part of the Dioptra deployment. By default it will be http://localhost:80.

Initialize Client

export DIOPTRA_API="<host>:<port>"

Step 2: Initialize Client#

There are two Dioptra clients to choose from: the JSON client with returns dictionaries and will raise an exception if a non-200 response is recived, and the Response client which returns Response objects and does not raise exceptions.

Choose your preferred client, then in your python interpreter, run the following code:

Initialize Client

from dioptra.client import connect_json_dioptra_client

# the client will use the DIOPTRA_API environment variable by default
client = connect_json_dioptra_client()
# otherwise you can pass address manually:
# client = connect_json_dioptra_client(address="<host>:<port>")

Full Client Method Documentation:

client.connect_json_dioptra_client() → dioptra.client.client.DioptraClient[dict[str, Any]]#

Connect a client to the Dioptra API that returns JSON-like Python dictionaries.

In contrast to the client that returns response objects, this client will raise an exception for any non-2xx response status code.

Parameters

address – The Dioptra web address. This is the same address used to access the web GUI, e.g. “https://dioptra.example.org”. Note that the “/api/<apiVersion>” suffix is omitted. If None, then the DIOPTRA_API environment variable will be checked and used.

Returns

A Dioptra client.

Raises

ValueError – If address is None and the DIOPTRA_API environment variable is not set.

Step 3: Register User#

In your python interpreter, set the username, email, and password, then use the client to register a new user:

Register User

username = "user"
email = "user@localhost"
password = "pass"
response = client.users.create(username, email=email, password=password)
print(response)

You should see a successful response similar to the below:

{'username': 'user',
 'email': 'user@localhost',
 'id': 1,
 'groups': [{'id': 1, 'name': 'public', 'url': '/api/v1/groups/1'}],
 'createdOn': '2026-02-02T18:47:44.794278+00:00',
 'lastModifiedOn': '2026-02-02T18:47:44.794278+00:00',
 'lastLoginOn': None,
 'passwordExpiresOn': '2027-02-02T18:47:44.794278+00:00'
 }

Full Client Method Documentation:

UsersCollectionClient.create(username: str, email: str, password: str) → dioptra.client.users.T[source]#

Creates a Dioptra user.

Parameters

  • username – The username of the new user.

  • email – The email address of the new user.

  • password – The password to set for the new user.

Returns

The response from the Dioptra API.

Step 4: Log In#

In your python interpreter, run the following code:

Log In

response = client.auth.login(username, password)
print(response)

You should see a successful response similar to the below:

{'username': 'user', 'status': 'Login successful'}

Full Client Method Documentation:

AuthCollectionClient.login(username: str, password: str) → dioptra.client.auth.T[source]#

Send a login request to the Dioptra API.

Parameters

  • username – The username of the user.

  • password – The password of the user.

Returns

The response from the Dioptra API.

Step 5: Retrieve the IDs of Resources (optional)#

There are many resource IDs you will need for access to downstream methods in the client.

Some of these include:

  • Group ID: The ID for the user group in Dioptra

  • User ID: The IDs for users, useful for searching for resources

  • Queue IDs: Queues are attached to entrypoints, and by extension also experiments and jobs

  • Plugin Parameter Type IDs: These IDs are used for task registration and entrypoint parameters

Get Group IDs

client.groups.get()

Full Client Method Documentation:

GroupsCollectionClient.get(index: int = 0, page_length: int = 10, search: str | None = None) → dioptra.client.groups.T[source]#

Get a list of groups.

Parameters

  • index – The paging index. Optional, defaults to 0.

  • page_length – The maximum number of groups to return in the paged response. Optional, defaults to 10.

  • search – Search for groups using the Dioptra API’s query language. Optional, defaults to None.

Returns

The response from the Dioptra API.