Home

Python Client Library

@supabase-community/supabase-py

This reference documents every object and method available in the supabase-py library from the Supabase community. You can use supabase-py to interact with your Postgres database, listen to database changes, invoke Deno Edge Functions, build login and user management functionality, and manage large files.

The Python client library is created and maintained by the Supabase community, and is not an official library. Please be tolerant of areas where the library is still being developed, and — as with all the libraries — feel free to contribute wherever you find issues.

Huge thanks to official maintainers, anand2312, dreinon, J0, and Leynier.

Shoutout to timkpaine for maintaining our Conda libraries as well.

Initializing

You can initialize a new Supabase client using the create_client() method.

The Supabase client is your entrypoint to the rest of the Supabase functionality and is the easiest way to interact with everything we offer within the Supabase ecosystem.


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)

Fetch data

  • By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's API settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests.
  • apikey is a reserved keyword if you're using the Supabase Platform and should be avoided as a column name.

response = supabase.table('countries').select("*").execute()

Insert data

Perform an INSERT into the table or view.

Parameters
  • values
    REQUIRED
    object

    The values to insert. Pass an object to insert a single row or an array to insert multiple rows.

  • options
    Optional
    object

    Named parameters 


data, count = supabase
.table('countries')
.insert({"id": 1, "name": "Denmark"})
.execute()

Create a new user

  • By default, the user needs to verify their email address before logging in. To turn this off, disable Confirm email in your project.
  • Confirm email determines if users need to confirm their email address after signing up.
    • If Confirm email is enabled, a user is returned but session is null.
    • If Confirm email is disabled, both a user and a session are returned.
  • By default, when the user confirms their email address, they are redirected to the SITE_URL. You can modify your SITE_URL or add additional redirect URLs in your project.
  • If sign_up() is called for an existing confirmed user:
    • If Confirm email is enabled in your project, an obfuscated/fake user object is returned.
    • If Confirm email is disabled, the error message, User already registered is returned.
  • To fetch the currently logged-in user, refer to getUser().

res = supabase.auth.sign_up({
  "email": 'example@email.com',
  "password": 'example-password',
})

Sign in a user

  • Requires either an email and password or a phone number and password.

data = supabase.auth.sign_in_with_password({"email": "j0@supabase.io", "password": "tesupabasenow"})

Sign in a user through OTP

  • Requires either an email or phone number.
  • This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
  • If the user doesn't exist, sign_in_with_otp() will signup the user instead. To restrict this behavior, you can set should_create_user in SignInWithPasswordlessCredentials.options to false.
  • If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
  • If you're using phone, you can configure whether you want the user to receive a OTP.
  • The magic link's destination URL is determined by the SITE_URL.
  • See redirect URLs and wildcards to add additional redirect URLs to your project.
  • Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, modify the magic link email template to include {{ .Token }} instead of {{ .ConfirmationURL }}.

data = supabase.auth.sign_in_with_otp({
  "email": 'example@email.com',
  "options": {
    "email_redirect_to": 'https://example.com/welcome'
  }
})

Sign in a user through OAuth

  • This method is used for signing in using a third-party provider.
  • Supabase supports many different third-party providers.

data = supabase.auth.sign_in_with_oauth({
  "provider": 'github'
})

Sign out a user

  • In order to use the signOut() method, the user needs to be signed in first.

res = supabase.auth.sign_out()

Verify and log in through OTP

  • The verify_otp method takes in different verification types. If a phone number is used, the type can either be sms or phone_change. If an email address is used, the type can be one of the following: signup, magiclink, recovery, invite or email_change.
  • The verification type used should be determined based on the corresponding auth method called before verify_otp to sign up / sign-in a user.

res = supabase.auth.verify_otp(phone, token)

Retrieve a session


res = supabase.auth.get_session()

Retrieve a new session

  • This method will refresh the session whether the current one is expired or not.
  • Both examples destructure user and session from data. This is not required; so const { data, error } = is also valid.

res = supabase.auth.refresh_session()

Retrieve a user

  • This method gets the user object from the current session.
  • Fetches the user object from the database instead of local session.

data = supabase.auth.get_user()

Set the session data

  • setSession() takes in a refresh token and uses it to get a new session.
  • The refresh token can only be used once to obtain a new session.
  • Refresh token rotation is enabled by default on all projects to guard against replay attacks.
  • You can configure the REFRESH_TOKEN_REUSE_INTERVAL which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.
  • If you are using React Native, you will need to install a Buffer polyfill via a library such as rn-nodeify to properly use the library.

res = supabase.auth.set_session({"access_token": access_token, "refresh_token": refresh_token)

Invoke a function

Invoke a Supabase Function.

  • Requires an Authorization header.
  • When you pass in a body to your function, we automatically attach the Content-Type header for Blob, ArrayBuffer, File, FormData and String. If it doesn't match any of these types we assume the payload is json, serialise it and attach the Content-Type header as application/json. You can override this behaviour by passing in a Content-Type header of your own.

func = supabase.functions()
@asyncio.coroutine
async def test_func(loop):
  resp = await func.invoke("hello-world",invoke_options={'body':{}})
  return resp

loop = asyncio.get_event_loop()
resp = loop.run_until_complete(test_func(loop))
loop.close()

Subscribe to channel

  • We are implementing this feature at the moment. If you have queries feel free to open an issue on the realtime-py repository.

Create a bucket

  • RLS policy permissions required:
    • buckets table permissions: insert
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage().create_bucket(name)

Retrieve a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage().get_bucket(name)

List all buckets

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage().list_bucke()

Delete a bucket

  • RLS policy permissions required:
    • buckets table permissions: select and delete
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage().delete_bucket(name)

Empty a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: select and delete
  • Refer to the Storage guide on how access control works

res = supabase.storage().empty_bucket(name)

Upload a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: insert
  • Refer to the Storage guide on how access control works

with open(source, 'rb+') as f:
  res = supabase.storage().from_('bucket').upload(destination, os.path.abspath(source))

Download a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

with open(destination, 'wb+') as f:
  res = supabase.storage().from_(bucket_name).download(source)
  f.write(res)

List all files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

res = supabase.storage().from_('test').list()

Move an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works

res = supabase.storage().from_(bucket).move('public/avatar1.png', 'private/avatar2.png')

Delete files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: delete and select
  • Refer to the Storage guide on how access control works

res = supabase.storage().from_('test').remove('test.jpg')

Create a signed URL

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

res = supabase.storage().from_(bucket_name).create_signed_url(filepath, expiry_duration)

Retrieve public URL

  • The bucket needs to be set to public, either via updateBucket() or by going to Storage on app.supabase.com, clicking the overflow menu on a bucket and choosing "Make public"
  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage().from_(bucket_name).get_public_url('test/avatar1.jpg')

Release Notes

The community is actively working on the library and we will be upgrading the Authentication library, gotrue-py, to mirror the Supabase-js v2 lib.

Storage Transformations#

We currently support image transformations in our storage library.