Python SDK

The Python SDK is available as a PyPI package

The Python SDK uses type annotations and requires Python 3.8 or higher. You can read more about the Python SDK in its API reference.

Installation

To install the library:

pip install xata

The xata package is a standalone SDK library that features the XataClient. By installing the package, you can import the SDK into your Python project and start building on top of Xata. Please note, that the Python SDK is different from the Xata CLI which can be used to manage your Xata databases from the command line or to import the Typescript and Javascript client.

Configuration

Workspace URL

To bootstrap the SDK we advise to use the workspace URL. In the Web UI, please navigate to Workspaces then Configuration and you will see the workspace API base URL. Please copy the URL and use it to setup routing.

The URL can be passed to the client as parameter:

1
xata = XataClient(db_url="REDACTED_DB_URL")

Or you can set the environment variable: XATA_DATABASE_URL. The parameter value will take precedence over the environment variable.

The format of the database URL (db_url) parameter must follow the format of: https://test-123456.us-east-1.xata.sh/db/mydb. The branch name is not mandatory, it can be either appended to the URL, with a : as the separator, like this https://test-123456.us-east-1.xata.sh/db/mydb:my-feature-branch. Alternatively, you can specify the branch_name with the parameter in XataClient.

Authorization

There are multiple options to pass your Xata credentials to the client. Xata will check following this order of precedence:

1. Parameters passed to the constructor
2. Environment variables
3. The .env file
4. Via .xatarc configuration file

The .xatarc file is generated by the Xata CLI in the current directory when running the command xata init.

Parameters

Inject the API key and workspace id directly into the constructor as parameters:

1
2
3
from xata.client import XataClient

client = XataClient(api_key="REDACTED_API_KEY", db_url="REDACTED_DB_URL")

Environment Variables

If no parameters were passed, the client probes the following environment variables for authentication.

export XATA_API_KEY="REDACTED_API_KEY"
export XATA_DATABASE_URL="REDACTED_DB_URL"

1
2
3
from xata.client import XataClient

client = XataClient()

dotenv

If the previous options were empty, the client looks for a .env file in the project root directory. Visit the authentication page to read more about best practices.

XATA_API_KEY="REDACTED_API_KEY"
XATA_DATABASE_URL="REDACTED_DB_URL"

xatarc configuration file

The .xatarc configuration file is the final source to retrieve the API key and the workspace. Please refer to the authentication page to learn more about the .xatarc file and best practices.

Logging

The SDK build on top of the requests package has support for logging baked in. Out of the box you can see the URL and status code by setting the log level to DEBUG.