Skip to main content

No project description provided

Project description


Supabase Logo

Supabase Realtime Client

Send ephemeral messages with Broadcast, track and synchronize state with Presence, and listen to database changes with Postgres Change Data Capture (CDC).

Guides · Reference Docs · Multiplayer Demo

Overview

This client enables you to use the following Supabase Realtime's features:

  • Broadcast: send ephemeral messages from client to clients with minimal latency. Use cases include sharing cursor positions between users.
  • Presence: track and synchronize shared state across clients with the help of CRDTs. Use cases include tracking which users are currently viewing a specific webpage.
  • Postgres Change Data Capture (CDC): listen for changes in your PostgreSQL database and send them to clients.

Usage

Installing the Package

pip3 install realtime==2.0.0

Creating a Channel

import asyncio
from typing import Optional
from realtime.client import RealtimeClient
from realtime.channel import RealtimeSubscribeStates

client = RealtimeClient(REALTIME_URL, API_KEY)
channel = client.channel('test-channel')

def _on_subscribe(status: RealtimeSubscribeStates, err: Optional[Exception]):
    if status == RealtimeSubscribeStates.SUBSCRIBED:
        print('Connected!')
    elif status == RealtimeSubscribeStates.CHANNEL_ERROR:
        print(f'There was an error subscribing to channel: {err.message}')
    elif status == RealtimeSubscribeStates.TIMED_OUT:
        print('Realtime server did not respond in time.')
    elif status == RealtimeSubscribeStates.CLOSED:
        print('Realtime channel was unexpectedly closed.')

await channel.subscribe(_on_subscribe)

# Listen for all incoming events, often the last thing you want to do.
await client.listen()

Notes:

  • REALTIME_URL is ws://localhost:4000/socket when developing locally and wss://<project_ref>.supabase.co/realtime/v1 when connecting to your Supabase project.
  • API_KEY is a JWT whose claims must contain exp and role (existing database role).
  • Channel name can be any string.

Broadcast

Your client can send and receive messages based on the event.

# Setup...

channel = client.channel(
    "broadcast-test", {"config": {"broadcast": {"ack": False, "self": False}}}
)

await channel.on_broadcast("some-event", lambda payload: print(payload)).subscribe()
await channel.send_broadcast("some-event", {"hello": "world"})

Notes:

  • Setting ack to true means that the channel.send promise will resolve once server replies with acknowledgement that it received the broadcast message request.
  • Setting self to true means that the client will receive the broadcast message it sent out.
  • Setting private to true means that the client will use RLS to determine if the user can connect or not to a given channel.

Presence

Your client can track and sync state that's stored in the channel.

# Setup...

channel = client.channel(
    "presence-test",
    {
        "config": {
            "presence": {
                "key": ""
            }
        }
    }
)

channel.on_presence_sync(lambda: print("Online users: ", channel.presence_state()))
channel.on_presence_join(lambda new_presences: print("New users have joined: ", new_presences))
channel.on_presence_leave(lambda left_presences: print("Users have left: ", left_presences))

await channel.track({ 'user_id': 1 })

Postgres CDC

Receive database changes on the client.

# Setup...

channel = client.channel("db-changes")

channel.on_postgres_changes(
    "*",
    schema="public",
    callback=lambda payload: print("All changes in public schema: ", payload),
)

channel.on_postgres_changes(
    "INSERT",
    schema="public",
    table="messages",
    callback=lambda payload: print("All inserts in messages table: ", payload),
)

channel.on_postgres_changes(
    "UPDATE",
    schema="public",
    table="users",
    filter="username=eq.Realtime",
    callback=lambda payload: print(
        "All updates on users table when username is Realtime: ", payload
    ),
)

channel.subscribe(
    lambda status, err: status == RealtimeSubscribeStates.SUBSCRIBED
    and print("Ready to receive database changes!")
)

Get All Channels

You can see all the channels that your client has instantiated.

# Setup...

client.get_channels()

Cleanup

It is highly recommended that you clean up your channels after you're done with them.

  • Remove a single channel
# Setup...

channel = client.channel('some-channel-to-remove')

channel.subscribe()

await client.remove_channel(channel)
  • Remove all channels
# Setup...

channel1 = client.channel('a-channel-to-remove')
channel2 = client.channel('another-channel-to-remove')

await channel1.subscribe()
await channel2.subscribe()

await client.remove_all_channels()

Credits

This repo draws heavily from phoenix-js.

License

MIT.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

realtime-2.0.6.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

realtime-2.0.6-py3-none-any.whl (20.6 kB view details)

Uploaded Python 3

File details

Details for the file realtime-2.0.6.tar.gz.

File metadata

  • Download URL: realtime-2.0.6.tar.gz
  • Upload date:
  • Size: 17.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for realtime-2.0.6.tar.gz
Algorithm Hash digest
SHA256 ced37686a77a546571029ecc74cfb31fff1404a5159d1198fa882af545843a6f
MD5 980244719889fca81536a5cb16f0c843
BLAKE2b-256 fe7d07f006df098c5fc9e00488e5268bcd7af0ee30a65fd6dfdbcee17ffeaa3b

See more details on using hashes here.

File details

Details for the file realtime-2.0.6-py3-none-any.whl.

File metadata

  • Download URL: realtime-2.0.6-py3-none-any.whl
  • Upload date:
  • Size: 20.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for realtime-2.0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 9aab6009c11883197386a0a9dc8c2b6939e62dddda734cfb77594727ac9ae0ce
MD5 5c21d845ed3d1a36fd01cc9bfb4376e7
BLAKE2b-256 7efc47a6615db976d5417ad982a15983cb3750910e0672d2e7e2d620433cdb2f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page