0
# Supabase Python Client
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: supabase
7
- **Language**: Python
8
- **Installation**: `pip install supabase`
9
- **Python Version**: >= 3.9
10

11
## Core Imports
12

13
```python
14
from supabase import create_client, Client
15
```
16

17
Async support:
18

19
```python
20
from supabase import create_async_client, AsyncClient
21
```
22

23
Import client options:
24

25
```python
26
from supabase import ClientOptions, AsyncClientOptions
27
```
28

29
## Basic Usage
30

31
```python
32
import os
33
from supabase import create_client, Client
34

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

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

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

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

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

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

60
## Architecture
61

62
Supabase Python provides a unified interface to multiple backend services:
63

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

69
## Capabilities
70

71
### Client Management
72

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

75
```python { .api }
76
def create_client(supabase_url: str, supabase_key: str, options: Optional[ClientOptions] = None) -> SyncClient
77
async def create_async_client(supabase_url: str, supabase_key: str, options: Optional[AsyncClientOptions] = None) -> AsyncClient
78
```
79

80
[Client Management](./client-management.md)
81

82
### Database Operations
83

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

86
```python { .api }
87
def table(self, table_name: str)  # Query builder for table operations
88
def from_(self, table_name: str)  # Alternative table method
89
def schema(self, schema: str)     # Schema selection
90
def rpc(self, fn: str, params: Optional[Dict[Any, Any]] = None, count: Optional[CountMethod] = None, head: bool = False, get: bool = False)  # Stored procedures
91
```
92

93
[Database Operations](./database-operations.md)
94

95
### Authentication
96

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

99
```python { .api }
100
# Auth client accessed via client.auth property
101
# Inherits complete GoTrue API including:
102
# - sign_up, sign_in_with_password, sign_out
103
# - OAuth providers, magic links, phone auth
104
# - Session management and token refresh
105
# - User profile and metadata management
106
```
107

108
[Authentication](./authentication.md)
109

110
### Storage Operations
111

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

114
```python { .api }
115
# Storage client accessed via client.storage property  
116
# Returns SupabaseStorageClient (sync) or AsyncSupabaseStorageClient (async)
117
# Provides complete file storage operations including:
118
# - File upload, download, update, delete
119
# - Bucket creation and management
120
# - Access control and signed URLs
121
# - File metadata and transformations
122
```
123

124
[Storage Operations](./storage-operations.md)
125

126
### Real-time Subscriptions
127

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

130
```python { .api }
131
def channel(self, topic: str, params: RealtimeChannelOptions = {}) -> SyncRealtimeChannel | AsyncRealtimeChannel
132
def get_channels(self)  # Get all active channels
133
def remove_channel(self, channel)  # Remove specific channel
134
def remove_all_channels(self)  # Remove all channels
135
```
136

137
[Real-time Subscriptions](./realtime-subscriptions.md)
138

139
### Edge Functions
140

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

143
```python { .api }
144
# Functions client accessed via client.functions property
145
# Provides edge function invocation with:
146
# - Function execution with custom headers and data
147
# - Response handling and error management
148
# - Integration with auth context
149
```
150

151
[Edge Functions](./edge-functions.md)
152

153
## Exception Handling
154

155
```python { .api }
156
# Core exceptions
157
class SupabaseException(Exception)
158
class SyncSupabaseException(SupabaseException)  
159
class AsyncSupabaseException(SupabaseException)
160

161
# Auth exceptions (from supabase_auth)
162
class AuthApiError(Exception)
163
class AuthError(Exception)
164
class AuthInvalidCredentialsError(Exception)
165
class AuthSessionMissingError(Exception)
166
class AuthWeakPasswordError(Exception)
167
class AuthImplicitGrantRedirectError(Exception)
168

169
# Database exceptions (from postgrest)
170
class PostgrestAPIError(Exception)
171

172
# Storage exceptions (from storage3)
173
class StorageException(Exception)
174

175
# Functions exceptions (from supabase_functions)
176
class FunctionsError(Exception)
177
class FunctionsHttpError(Exception)
178

179
# Realtime exceptions (from realtime)
180
class AuthorizationError(Exception)
181
class NotConnectedError(Exception)
182
```
183

184
## Type Definitions
185

186
```python { .api }
187
# Client option types
188
@dataclass
189
class ClientOptions:
190
    schema: str = "public"
191
    headers: Dict[str, str] = field(default_factory=dict)
192
    auto_refresh_token: bool = True
193
    persist_session: bool = True
194
    storage: SyncSupportedStorage = field(default_factory=SyncMemoryStorage)
195
    realtime: Optional[RealtimeClientOptions] = None
196
    httpx_client: Optional[SyncHttpxClient] = None
197
    postgrest_client_timeout: Union[int, float, Timeout] = DEFAULT_POSTGREST_CLIENT_TIMEOUT
198
    storage_client_timeout: Union[int, float, Timeout] = DEFAULT_STORAGE_CLIENT_TIMEOUT
199
    function_client_timeout: Union[int, float, Timeout] = DEFAULT_FUNCTION_CLIENT_TIMEOUT
200
    flow_type: AuthFlowType = "pkce"
201

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

207
# Realtime options
208
class RealtimeClientOptions(TypedDict, total=False):
209
    auto_reconnect: bool
210
    hb_interval: int
211
    max_retries: int
212
    initial_backoff: float
213
```