Metadata-Version: 2.1
Name: realtime
Version: 2.4.1
Summary:
Home-page: https://github.com/supabase/realtime-py
License: MIT
Author: Joel Lee
Author-email: joel@joellee.org
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
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: aiohttp (>=3.11.13,<4.0.0)
Requires-Dist: python-dateutil (>=2.8.1,<3.0.0)
Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
Requires-Dist: websockets (>=11,<15)
Project-URL: Repository, https://github.com/supabase/realtime-py
Description-Content-Type: text/markdown
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).
# 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
```bash
pip3 install realtime==2.0.0
```
## Creating a Channel
```python
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)
```
### Notes:
- `REALTIME_URL` is `ws://localhost:4000/socket` when developing locally and `wss://.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`.
```python
# 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.
```python
# 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.
```python
# 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.
```python
# 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
```python
# Setup...
channel = client.channel('some-channel-to-remove')
channel.subscribe()
await client.remove_channel(channel)
```
- Remove all channels
```python
# 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](https://github.com/phoenixframework/phoenix/tree/master/assets/js/phoenix).
## License
MIT.
