No project description provided
Project description
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
isws://localhost:4000/socket
when developing locally andwss://<project_ref>.supabase.co/realtime/v1
when connecting to your Supabase project.API_KEY
is a JWT whose claims must containexp
androle
(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
totrue
means that thechannel.send
promise will resolve once server replies with acknowledgement that it received the broadcast message request. - Setting
self
totrue
means that the client will receive the broadcast message it sent out. - Setting
private
totrue
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
Release history Release notifications | RSS feed
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.1.tar.gz
(25.1 kB
view hashes)
Built Distribution
realtime-2.0.1-py3-none-any.whl
(29.0 kB
view hashes)