or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdclient-management.mddatabase-operations.mdedge-functions.mdindex.mdrealtime-subscriptions.mdstorage-operations.md
tile.json

tessl/pypi-supabase

Supabase client for Python providing database operations, authentication, storage, real-time subscriptions, and edge functions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/supabase@2.18.x

To install, run

npx @tessl/cli install tessl/pypi-supabase@2.18.0

index.mddocs/

Supabase Python Client

A comprehensive Python client for Supabase that enables developers to interact with the complete Supabase ecosystem including PostgreSQL database operations, real-time subscriptions, authentication services, file storage, and edge functions. Provides both synchronous and asynchronous interfaces with built-in error handling, connection management, and comprehensive type support.

Package Information

  • Package Name: supabase
  • Language: Python
  • Installation: pip install supabase
  • Python Version: >= 3.9

Core Imports

from supabase import create_client, Client

Async support:

from supabase import create_async_client, AsyncClient

Import client options:

from supabase import ClientOptions, AsyncClientOptions

Basic Usage

import os
from supabase import create_client, Client

# Initialize the client
url = os.environ.get("SUPABASE_URL")
key = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)

# Database operations
data = supabase.table("countries").insert({"name": "Germany"}).execute()
countries = supabase.table("countries").select("*").execute()

# Authentication
user = supabase.auth.sign_up({"email": "user@example.com", "password": "password123"})
session = supabase.auth.sign_in_with_password({"email": "user@example.com", "password": "password123"})

# Storage operations  
supabase.storage.from_("bucket").upload("file.txt", b"file content")

# Real-time subscriptions
channel = supabase.channel("my-channel")
channel.on("postgres_changes", {"event": "*", "schema": "public", "table": "countries"}, callback)
channel.subscribe()

# Edge functions
response = supabase.functions.invoke("hello-world", {"name": "Functions"})

Architecture

Supabase Python provides a unified interface to multiple backend services:

  • Client Classes: SyncClient/AsyncClient serve as the main entry points, providing access to all Supabase services
  • Service Integration: Direct integration with PostgREST (database), GoTrue (auth), Storage3 (files), Realtime (WebSocket), and Functions (edge functions)
  • Dual Implementation: Complete synchronous and asynchronous APIs for all operations
  • Type Safety: Full type definitions and error handling for reliable production use

Capabilities

Client Management

Client creation, configuration, and lifecycle management for both synchronous and asynchronous operations.

def create_client(supabase_url: str, supabase_key: str, options: Optional[ClientOptions] = None) -> SyncClient
async def create_async_client(supabase_url: str, supabase_key: str, options: Optional[AsyncClientOptions] = None) -> AsyncClient

Client Management

Database Operations

Complete PostgreSQL database operations including CRUD operations, stored procedures, schema management, and query building through PostgREST integration.

def table(self, table_name: str)  # Query builder for table operations
def from_(self, table_name: str)  # Alternative table method
def schema(self, schema: str)     # Schema selection
def rpc(self, fn: str, params: Optional[Dict[Any, Any]] = None, count: Optional[CountMethod] = None, head: bool = False, get: bool = False)  # Stored procedures

Database Operations

Authentication

User registration, login, session management, OAuth integration, and authentication state handling with support for various auth flows.

# Auth client accessed via client.auth property
# Inherits complete GoTrue API including:
# - sign_up, sign_in_with_password, sign_out
# - OAuth providers, magic links, phone auth
# - Session management and token refresh
# - User profile and metadata management

Authentication

Storage Operations

File upload, download, and management operations including bucket management, file metadata, and access control.

# Storage client accessed via client.storage property  
# Returns SupabaseStorageClient (sync) or AsyncSupabaseStorageClient (async)
# Provides complete file storage operations including:
# - File upload, download, update, delete
# - Bucket creation and management
# - Access control and signed URLs
# - File metadata and transformations

Storage Operations

Real-time Subscriptions

WebSocket-based real-time functionality including database change subscriptions, presence tracking, and message broadcasting.

def channel(self, topic: str, params: RealtimeChannelOptions = {}) -> SyncRealtimeChannel | AsyncRealtimeChannel
def get_channels(self)  # Get all active channels
def remove_channel(self, channel)  # Remove specific channel
def remove_all_channels(self)  # Remove all channels

Real-time Subscriptions

Edge Functions

Serverless function invocation and management for running custom server-side logic at the edge.

# Functions client accessed via client.functions property
# Provides edge function invocation with:
# - Function execution with custom headers and data
# - Response handling and error management
# - Integration with auth context

Edge Functions

Exception Handling

# Core exceptions
class SupabaseException(Exception)
class SyncSupabaseException(SupabaseException)  
class AsyncSupabaseException(SupabaseException)

# Auth exceptions (from supabase_auth)
class AuthApiError(Exception)
class AuthError(Exception)
class AuthInvalidCredentialsError(Exception)
class AuthSessionMissingError(Exception)
class AuthWeakPasswordError(Exception)
class AuthImplicitGrantRedirectError(Exception)

# Database exceptions (from postgrest)
class PostgrestAPIError(Exception)

# Storage exceptions (from storage3)
class StorageException(Exception)

# Functions exceptions (from supabase_functions)
class FunctionsError(Exception)
class FunctionsHttpError(Exception)

# Realtime exceptions (from realtime)
class AuthorizationError(Exception)
class NotConnectedError(Exception)

Type Definitions

# Client option types
@dataclass
class ClientOptions:
    schema: str = "public"
    headers: Dict[str, str] = field(default_factory=dict)
    auto_refresh_token: bool = True
    persist_session: bool = True
    storage: SyncSupportedStorage = field(default_factory=SyncMemoryStorage)
    realtime: Optional[RealtimeClientOptions] = None
    httpx_client: Optional[SyncHttpxClient] = None
    postgrest_client_timeout: Union[int, float, Timeout] = DEFAULT_POSTGREST_CLIENT_TIMEOUT
    storage_client_timeout: Union[int, float, Timeout] = DEFAULT_STORAGE_CLIENT_TIMEOUT
    function_client_timeout: Union[int, float, Timeout] = DEFAULT_FUNCTION_CLIENT_TIMEOUT
    flow_type: AuthFlowType = "pkce"

@dataclass  
class AsyncClientOptions(ClientOptions):
    storage: AsyncSupportedStorage = field(default_factory=AsyncMemoryStorage)
    httpx_client: Optional[AsyncHttpxClient] = None

# Realtime options
class RealtimeClientOptions(TypedDict, total=False):
    auto_reconnect: bool
    hb_interval: int
    max_retries: int
    initial_backoff: float