Skip to main content

WebSocket SDK for Centrifugo (and any Centrifuge-based server) on top of Python asyncio library

Project description

centrifuge-python

CI pypi versions license

This is a WebSocket real-time SDK for Centrifugo server (and any Centrifuge-based server) on top of Python asyncio library.

[!TIP] If you are looking for Centrifugo server API client – check out pycent instead.

Before starting to work with this library check out Centrifugo client SDK API specification as it contains common information about Centrifugal real-time SDK behavior. This SDK supports all major features of Centrifugo client protocol - see SDK feature matrix.

Install

pip install centrifuge-python

Then in your code:

from centrifuge import Client

See example code and how to run it locally.

JSON vs Protobuf protocols

By default, SDK uses JSON protocol. If you want to use Protobuf protocol instead then pass use_protobuf=True option to Client constructor.

When using JSON protocol:

  • all payloads (data to publish, connect/subscribe data) you pass to the library are encoded to JSON internally using json.dumps before sending to server. So make sure you pass only JSON-serializable data to the library.
  • all payloads received from server are decoded to Python objects using json.loads internally before passing to your code.

When using Protobuf protocol:

  • all payloads you pass to the library must be bytes or None if optional. If you pass non-bytes data – exception will be raised.
  • all payloads received from the library will be bytes or None if not present.
  • don't forget that when using Protobuf protocol you can still have JSON payloads - just encode them to bytes before passing to the library.

Callbacks should not block

Event callbacks are called by SDK using await internally, the websocket connection read loop is blocked for the time SDK waits for the callback to be executed. This means that if you need to perform long operations in callbacks consider moving the work to a separate coroutine/task to return fast and continue reading data from the websocket.

The fact WebSocket read is blocked for the time we execute callbacks means that you can not call awaitable SDK APIs from callback – because SDK does not have a chance to read the reply. You will get OperationTimeoutError exception. The rule is the same - do the work asynchronously, for example use asyncio.ensure_future.

Run example

To run example, first start Centrifugo with config like this:

{
  "client": {
    "token": {
      "hmac_secret_key": "secret"
    }
  },
  "channel": {
    "namespaces": [
      {
        "name": "example",
        "presence": true,
        "history_size": 300,
        "history_ttl": "300s",
        "join_leave": true,
        "force_push_join_leave": true,
        "allow_publish_for_subscriber": true,
        "allow_presence_for_subscriber": true,
        "allow_history_for_subscriber": true
      }
    ]
  }
}

And then:

python -m venv env
. env/bin/activate
make dev
python example.py

Run tests

To run tests, first start Centrifugo server:

docker pull centrifugo/centrifugo:v5
docker run -d -p 8000:8000 \
-e CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY="secret" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOWED_DELTA_TYPES="fossil" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_DELTA_PUBLISH="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_PRESENCE="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_JOIN_LEAVE="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_FORCE_PUSH_JOIN_LEAVE="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_HISTORY_SIZE="100" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_HISTORY_TTL="300s" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_FORCE_RECOVERY="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_PUBLISH_FOR_SUBSCRIBER="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_PRESENCE_FOR_SUBSCRIBER="true" \
-e CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_HISTORY_FOR_SUBSCRIBER="true" \
-e CENTRIFUGO_CLIENT_SUBSCRIBE_TO_USER_PERSONAL_CHANNEL_ENABLED="true" \
-e CENTRIFUGO_LOG_LEVEL="trace" \
centrifugo/centrifugo:v6 centrifugo

And then (from cloned repo root):

python -m venv env
. env/bin/activate
make dev
make test

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

centrifuge_python-0.4.1.tar.gz (38.2 kB view details)

Uploaded Source

Built Distribution

centrifuge_python-0.4.1-py3-none-any.whl (25.8 kB view details)

Uploaded Python 3

File details

Details for the file centrifuge_python-0.4.1.tar.gz.

File metadata

  • Download URL: centrifuge_python-0.4.1.tar.gz
  • Upload date:
  • Size: 38.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for centrifuge_python-0.4.1.tar.gz
Algorithm Hash digest
SHA256 39375f72c665e157d97eb4f20a7c01205e4db105544daefbbb43500e4f3c4b07
MD5 f1e5b45e71a84f57334356ee849f6bca
BLAKE2b-256 8bd96266f0f3fc99b78ebdeea2621bc5a23fc20c71bfe262080a12725b111ee9

See more details on using hashes here.

File details

Details for the file centrifuge_python-0.4.1-py3-none-any.whl.

File metadata

File hashes

Hashes for centrifuge_python-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 81ae240080c1f2934d4dcf07e12c01b6b1e0f7b954b0cac3f1af38da00fa9483
MD5 508282d7644b0cf87088c75e2e6e3c01
BLAKE2b-256 0824abc2b512e84a7b0439c7878143317b7913a3795b8181630808a5516a8b05

See more details on using hashes here.

Supported by

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