The Synnax Python Client

Use the Synnax Python client to interact with a Synnax cluster.

Synnax provides first-class support for Python. Our client delivers many capabilities, including

Direct integration with pandas and numpy.
Tooling to implement automated control of your hardware.
Change data capture (CDC) infrastructure to build automated analysis pipelines.

In this section, we’ll cover how to install the client and authenticate with a cluster.

Installation

The synnax library requires Python 3.10 or higher, and is available on PyPI. Install it directly using pip or define it as a requirement in your virtual environment of choice:

pip install synnax

Python can be difficult to get installed and running correctly, so we’ve put together a troubleshooting guide that you can reference.

Authenticating with a Cluster

There are two ways to authenticate with a Synnax cluster: using the CLI to permanently store your credentials, or passing your credentials directly to the client.

The easiest way to authenticate with a Synnax cluster is with the login command. This will permanently store your credentials in the operating system’s keychain, and allow you to use the client without passing credentials directly.

We highly recommend this method when using Synnax for data analysis, as it makes it easy to use the client in a Jupyter notebook and share scripts without accidentally revealing your credentials.

To authenticate, run the following command:

synnax login

If you get the error command not found, you might not have Python scripts in your PATH variable. See our troubleshooting guide for more information.

This command will prompt us for the following information:

Enter your Synnax connection parameters:
Host (localhost): # YOUR HOST
Port (9090): # YOUR PORT
Username (synnax): # YOUR USERNAME
Password: # YOUR PASSWORD
Secure connection? (y/n) (n):

For the last question, enter y if your cluster is running in secure mode, and n otherwise. If all goes well, you should see the following message:

Saved credentials. You can now use the Synnax Client
without having to log in. To connect the cluster in a Python shell, use the following:

from synnax import Synnax
client = Synnax()

Now that you’ve authenticated, you can instantiate the client as follows:

import synnax as sy

client = sy.Synnax()

Passing Credentials Directly

Passing authentication parameters directly is ideal in scenarios where you’d like to use configuration files or environment variables to store your credentials. We recommend this approach when connecting to Synnax in custom applications and/or automated analysis servers.

To authenticate directly, simply pass your connection parameters to the Synnax constructor:

import synnax as sy

client = sy.Synnax(
    host="demo.synnaxlabs.com",
    port=9090,
    username="synnax",
    password="seldon",
    secure=True
)

Here’s an example with environment variables:

import os
import synnax as sy

client = sy.Synnax(
    host=os.environ["SYNNAX_HOST"],
    port=int(os.environ["SYNNAX_PORT"]),
    username=os.environ["SYNNAX_USERNAME"],
    password=os.environ["SYNNAX_PASSWORD"],
    secure=bool(os.environ["SYNNAX_SECURE"])
)

Next Steps

Now that you’ve installed and authenticated the client, you’re ready to start using Synnax! Next, learn how to create channels for storing data.

Channels