supabase-py

The supabase-py repository is a Python monorepo containing the following libraries:

• supabase: The main client library (src/supabase/README.md)
• realtime-py: Realtime capabilities (src/realtime/README.md)
• supabase_functions: Edge Functions support (src/functions/README.md)
• storage3: Storage services (src/storage/README.md)
• postgrest: Postgrest client (src/postgrest/README.md)
• supabase_auth: Auth services (src/auth/README.md)

The gotrue package (Auth-py) is organized into several submodules that handle different aspects of authentication logic. When working with the library, you may need to interact with these specific modules:

• gotrue.constants: Contains constant values used throughout the authentication process.
• gotrue.exceptions: Defines the specific error types and exceptions raised by the auth client.
• gotrue.helpers: Provides utility functions to assist with auth operations.
• gotrue.http_clients: Manages the underlying HTTP communication with the Supabase Auth service.
• gotrue.types: Contains type definitions for better IDE support and type checking.
• gotrue: The main entry point for authentication functionality.

While supabase_auth is a port of the Supabase JS gotrue client, there are several key differences in implementation:

1. Error Handling: Unlike the JS client which returns errors as part of an object ({ data, error }), supabase_auth raises exceptions directly. This follows Pythonic idioms.
2. Naming Convention: The library uses snake_case for variables and method names instead of the pascalCase or camelCase used in JavaScript.
3. Date-time Handling: The Python library automatically parses date-time strings into Python datetime objects, whereas the JS client keeps them as strings.
4. Browser Code: Some browser-specific logic from the JS client was not ported as it is not applicable to Python environments.

Request Builders are used to construct queries for the Postgrest API. The library provides two sets of builder classes: one for synchronous operations (SyncRequestBuilder, SyncSelectRequestBuilder, SyncQueryRequestBuilder) and one for asynchronous operations (AsyncRequestBuilder, AsyncSelectRequestBuilder, AsyncQueryRequestBuilder).

Important: You should not instantiate these classes directly. They are intended to be used via the high-level client interface provided by the library. The synchronous and asynchronous versions share the same interface and methods.

The supabase-py library provides both synchronous and asynchronous clients. Both versions offer the exact same interface, allowing you to switch between them based on your application's requirements.

Note that the documentation provided in the API reference focuses exclusively on the asynchronous client and its methods. If you are using the synchronous client, the method names and parameters will be identical, but you should follow standard synchronous Python patterns (i.e., no await keywords).

The Filter Builder is a request builder used to apply filters to your queries. It provides a fluent interface where all filter methods return a modified instance of the builder, allowing you to chain multiple filters together in a single statement.

Note that while the underlying implementation distinguishes between AsyncFilterRequestBuilder and SyncFilterRequestBuilder, they provide the exact same interface. You should not construct these classes directly; instead, use them via the main client API.

For a complete list of supported operators, refer to the PostgREST documentation.

For local development, you can use a preconfigured PostgREST instance via Docker Compose. Once started, the server is accessible at http://localhost:3000.

docker-compose up

You can install the supabase_auth package using pip, uv, or poetry.

Pip

pip install supabase_auth

Uv

uv add supabase_auth

Poetry

poetry add supabase_auth

To use the client, you must provide your Supabase project URL and API key. It is recommended to set these as environment variables (SUPABASE_URL and SUPABASE_KEY). Use create_client to instantiate the Client object.

import os
from supabase import create_client, Client

url: str = os.environ.get("SUPABASE_URL")
key: str = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)

To interact with Supabase Storage, you can use the storage3 library. While you can use AsyncStorageClient directly, it is recommended to use the storage functionality through the main Supabase Python Client to simplify header management.

To use AsyncStorageClient directly, you must provide the storage URL and a headers dictionary containing both the apiKey and the Authorization bearer token.

from storage3 import AsyncStorageClient

url = "https://<your_supabase_id>.supabase.co/storage/v1"
key = "<your api key>"
headers = {"apiKey": key, "Authorization": f"Bearer {key}"}

storage_client = AsyncStorageClient(url, headers)

async def get_buckets():
  await storage_client.list_buckets()