1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
Metadata-Version: 2.1
Name: supabase
Version: 2.14.0
Summary: Supabase client for Python.
Home-page: https://github.com/supabase/supabase-py
License: MIT
Author: Joel Lee
Author-email: joel@joellee.org
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: gotrue (>=2.11.0,<3.0.0)
Requires-Dist: httpx (>=0.26,<0.29)
Requires-Dist: postgrest (>=0.19,<0.20)
Requires-Dist: realtime (>=2.4.0,<2.5.0)
Requires-Dist: storage3 (>=0.10,<0.12)
Requires-Dist: supafunc (>=0.9,<0.10)
Project-URL: Documentation, https://github.com/supabase/supabase-py
Project-URL: Repository, https://github.com/supabase/supabase-py
Description-Content-Type: text/markdown
# `supabase-py`
Python client for [Supabase](https://supabase.com)
- Documentation: [supabase.com/docs](https://supabase.com/docs/reference/python/introduction)
- Usage:
- [GitHub OAuth in your Python Flask app](https://supabase.com/blog/oauth2-login-python-flask-apps)
- [Python data loading with Supabase](https://supabase.com/blog/loading-data-supabase-python)
> [!NOTE]
> Do you want to help us shape the future of this library? [We're hiring](https://jobs.ashbyhq.com/supabase/85d07345-47c6-4980-82e2-57782f83ab4e).
## Set up a Local Development Environment
### Clone the Repository
```bash
git clone https://github.com/supabase/supabase-py.git
cd supabase-py
```
### Create and Activate a Virtual Environment
We recommend activating your virtual environment. For example, we like `poetry` and `conda`! Click [here](https://docs.python.org/3/library/venv.html) for more about Python virtual environments and working with [conda](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment) and [poetry](https://python-poetry.org/docs/basic-usage/).
Using venv (Python 3 built-in):
```bash
python3 -m venv env
source env/bin/activate # On Windows, use .\env\Scripts\activate
```
Using conda:
```bash
conda create --name supabase-py
conda activate supabase-py
```
### PyPi installation
Install the package (for Python >= 3.9):
```bash
# with pip
pip install supabase
# with conda
conda install -c conda-forge supabase
```
### Local installation
You can also install locally after cloning this repo. Install Development mode with `pip install -e`, which makes it editable, so when you edit the source code the changes will be reflected in your python module.
## Usage
Set your Supabase environment variables in a dotenv file, or using the shell:
```bash
export SUPABASE_URL="my-url-to-my-awesome-supabase-instance"
export SUPABASE_KEY="my-supa-dupa-secret-supabase-api-key"
```
Init client:
```python
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)
```
Use the supabase client to interface with your database.
### Sign-up
```python
user = supabase.auth.sign_up({ "email": users_email, "password": users_password })
```
### Sign-in
```python
user = supabase.auth.sign_in_with_password({ "email": users_email, "password": users_password })
```
### Insert Data
```python
data = supabase.table("countries").insert({"name":"Germany"}).execute()
# Assert we pulled real data.
assert len(data.data) > 0
```
### Select Data
```python
data = supabase.table("countries").select("*").eq("country", "IL").execute()
# Assert we pulled real data.
assert len(data.data) > 0
```
### Update Data
```python
data = supabase.table("countries").update({"country": "Indonesia", "capital_city": "Jakarta"}).eq("id", 1).execute()
```
### Update data with duplicate keys
```python
country = {
"country": "United Kingdom",
"capital_city": "London" # This was missing when it was added
}
data = supabase.table("countries").upsert(country).execute()
assert len(data.data) > 0
```
### Delete Data
```python
data = supabase.table("countries").delete().eq("id", 1).execute()
```
### Call Edge Functions
```python
def test_func():
try:
resp = supabase.functions.invoke("hello-world", invoke_options={'body':{}})
return resp
except (FunctionsRelayError, FunctionsHttpError) as exception:
err = exception.to_dict()
print(err.get("message"))
```
### Download a file from Storage
```python
bucket_name: str = "photos"
data = supabase.storage.from_(bucket_name).download("photo1.png")
```
### Upload a file
```python
bucket_name: str = "photos"
new_file = getUserFile()
data = supabase.storage.from_(bucket_name).upload("/user1/profile.png", new_file)
```
### Remove a file
```python
bucket_name: str = "photos"
data = supabase.storage.from_(bucket_name).remove(["old_photo.png", "image5.jpg"])
```
### List all files
```python
bucket_name: str = "charts"
data = supabase.storage.from_(bucket_name).list()
```
### Move and rename files
```python
bucket_name: str = "charts"
old_file_path: str = "generic/graph1.png"
new_file_path: str = "important/revenue.png"
data = supabase.storage.from_(bucket_name).move(old_file_path, new_file_path)
```
## Roadmap
- [x] Wrap [Postgrest-py](https://github.com/supabase/postgrest-py/)
- [x] Add remaining filters
- [x] Add support for EXPLAIN
- [ ] Add proper error handling
- [x] Use `sanitize_param()` to sanitize inputs.
- [x] Fix client-side timeouts for long running queries.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [ ] Wrap [Realtime-py](https://github.com/supabase/realtime-py)
- [ ] Integrate with Supabase-py
- [ ] Support WALRUS
- [ ] Support broadcast (to check if already supported)
- [x] Add `close()` method to close a socket.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Wrap [auth-py](https://github.com/supabase/auth-py)
- [x] Remove references to GoTrue-js v1 and do a proper release
- [ ] Test and document common flows (e.g. sign in with OAuth, sign in with OTP)
- [ ] Add MFA methods
- [x] Add SSO methods
- [x] Add Proof Key for Code Exchange (PKCE) methods. Unlike the JS library, we do not currently plan to support Magic Link (PKCE). Please use the [token hash](https://supabase.com/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr#create-api-endpoint-for-handling-tokenhash) in tandem with `verifyOTP` instead.
- [x] Add `is_anonymous` boolean property.
- [x] Add `sign_in_with_id_token()` method.
- [x] Add `sign_in_with_sso()` method.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Wrap [storage-py](https://github.com/supabase/storage-py)
- [ ] Support resumable uploads
- [x] Setup testing environment
- [x] Fix client-side timeouts for long running operations.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Document how to properly upload different file types (e.g. jpeg/png and download it)
- [x] Wrap [functions-py](https://github.com/supabase/functions-py)
- [x] Fix client-side timeouts for long running functions.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Regions support.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
### Overall Tasks
- [x] Add async support across the entire library
- [ ] Add FastAPI helper library (external to supabase-py)
- [ ] Add `django-supabase-postgrest` (external to supabase-py)
## Contributing
Contributing to the Python libraries are a great way to get involved with the Supabase community. Reach out to us on [Discord](https://discord.supabase.com) or on our [Github Discussions](https://github.com/orgs/supabase/discussions) page if you want to get involved.
### Running Tests
Currently, the test suites are in a state of flux. We are expanding our clients' tests to ensure things are working, and for now can connect to this test instance, which is populated with the following table:
<p align="center">
<img width="720" height="481" src="https://i.ibb.co/Bq7Kdty/db.png">
</p>
The above test database is a blank supabase instance that has populated the `countries` table with the built-in countries script that can be found in the supabase UI. You can launch the test scripts and point to the above test database by running
```bash
./test.sh
```
## Badges
[](https://opensource.org/licenses/MIT)
[](https://github.com/supabase/supabase-py/actions/workflows/ci.yml)
[](https://pypi.org/project/supabase)
[](https://pypi.org/project/supabase)
[](https://codecov.io/gh/supabase/supabase-py)
[](https://github.com/supabase/supabase-py/commits)
[](https://github.com/supabase/supabase-py/commits)
[](https://github.com/supabase/supabase-py/stargazers)
[](https://github.com/supabase/supabase-py/network/members)
[](https://github.com/supabase/supabase-py)
[](https://github.com/supabase/supabase-py/graphs/contributors)
|
