Xata SDK for Python

The Python SDK is available as a PyPI package. It uses type annotations and requires Python 3.8 or higher. The API reference is located at https://xata-py.readthedocs.io.

To install the library enter the following command:

pip install xata

The xata package is a standalone SDK library that features XataClient. By installing the package, you can import the SDK into your Python project and start building on top of Xata.

The Python SDK is different from the Xata CLI which can be used to manage your Xata databases from the command line or import the Typescript and Javascript client.

To bootstrap the SDK we recommend you use the workspace URL. In the Web UI, navigate to Workspaces then Configuration. You will be directed to the workspace API base URL. Copy the URL and use it to configure routing.

The URL can be passed to the client as a parameter:

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.

There are multiple options to pass your Xata credentials to the client. Xata will check the following using 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.

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"

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

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

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

from xata.client import XataClient
 
client = XataClient()

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

from xata.client import XataClient
 
client = XataClient(api_key="REDACTED_API_KEY", db_url="REDACTED_DB_URL")

There are multiple options to point the SDK to a specific branch, if none is selected, the SDK elects main as current branch name.

The environment variable XATA_BRANCH can specify a branch, the SDK will look for the variable and initialize the SDK with that value.

You can also, set the branch with the database URL (db_url) on SDK init, we want to use the branch feature-042 on the database Planes, we can initialize the SDK with:

xata = XataClient(db_url="https://test-12345.us-east-1.xata.sh/db/Planes:feature-042")

Another options is to specify the branch_name in the SDK. If you specify db_url and branch_name, the latter will be ignored.

If you want to change the branch for a single request, you can do so with all workspace endpoints, by setting the branch_name:

xata.records().insert("Planes", record, branch_name="feature-042")

The SDK builds on the requests package and includes built-in logging support. By configuring the log level to debug, you can view the URL and status code by default.

The API surface of the Python SDK is organized into namespaces, with each namespace associated with a specific set of APIs. For instance, the databases namespace provides access to all the available Xata endpoints for managing databases.

Alternatively, you can directly instantiate a namespace, as demonstrated in this example.

The endpoints and namespaces are generated from the OpenAPI specification.