# centrifuge-python
[](https://github.com/centrifugal/centrifuge-python/actions/workflows/test.yml?query=event%3Apush+branch%3Amaster+workflow%3ATest)
[](https://pypi.python.org/pypi/centrifuge-python)
[](https://github.com/centrifugal/centrifuge-python)
[](https://github.com/centrifugal/centrifuge-python/blob/master/LICENSE)
This is a WebSocket real-time SDK for [Centrifugo](https://github.com/centrifugal/centrifugo) server (and any [Centrifuge-based](https://github.com/centrifugal/centrifuge) server) on top of Python asyncio library.
> [!TIP]
> If you are looking for Centrifugo [server API](https://centrifugal.dev/docs/server/server_api) client – check out [pycent](https://github.com/centrifugal/pycent) instead.
Before starting to work with this library check out Centrifugo [client SDK API specification](https://centrifugal.dev/docs/transports/client_api) 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](https://centrifugal.dev/docs/transports/client_sdk#sdk-feature-matrix).
## Install
```
pip install centrifuge-python
```
Then in your code:
```
from centrifuge import Client
```
See [example code](https://github.com/centrifugal/centrifuge-python/blob/master/example.py) and [how to run it](#run-example) 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](https://github.com/centrifugal/centrifuge-python/blob/master/example.py), first start Centrifugo with config like this:
```json
{
"token_hmac_secret_key": "secret",
"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:
```bash
python -m venv env
. env/bin/activate
make dev
python example.py
```
## Run tests
To run tests, first start Centrifugo server:
```bash
docker pull centrifugo/centrifugo:v5
docker run -d -p 8000:8000 -e CENTRIFUGO_LOG_LEVEL=trace \
-e CENTRIFUGO_TOKEN_HMAC_SECRET_KEY="secret" -e CENTRIFUGO_PRESENCE=true \
-e CENTRIFUGO_JOIN_LEAVE=true -e CENTRIFUGO_FORCE_PUSH_JOIN_LEAVE=true \
-e CENTRIFUGO_HISTORY_TTL=300s -e CENTRIFUGO_HISTORY_SIZE=100 \
-e CENTRIFUGO_DELTA_PUBLISH=true -e CENTRIFUGO_ALLOWED_DELTA_TYPES="fossil" \
-e CENTRIFUGO_FORCE_RECOVERY=true -e CENTRIFUGO_USER_SUBSCRIBE_TO_PERSONAL=true \
-e CENTRIFUGO_ALLOW_PUBLISH_FOR_SUBSCRIBER=true -e CENTRIFUGO_ALLOW_PRESENCE_FOR_SUBSCRIBER=true \
-e CENTRIFUGO_ALLOW_HISTORY_FOR_SUBSCRIBER=true centrifugo/centrifugo:v5 centrifugo
```
And then (from cloned repo root):
```bash
python -m venv env
. env/bin/activate
make dev
make test
```
Raw data
{
"_id": null,
"home_page": null,
"name": "centrifuge-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Centrifuge, Centrifugo, Pub/Sub, Realtime, WebSocket",
"author": "Alexander Emelin (Centrifugal Labs LTD), Katant Savelev",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/68/16/ff1c8751d5a266e4a713d4ae5396a0271d540b6189879bd77dfb4ca1d7d1/centrifuge_python-0.3.1.tar.gz",
"platform": null,
"description": "# centrifuge-python\n\n[](https://github.com/centrifugal/centrifuge-python/actions/workflows/test.yml?query=event%3Apush+branch%3Amaster+workflow%3ATest)\n[](https://pypi.python.org/pypi/centrifuge-python)\n[](https://github.com/centrifugal/centrifuge-python)\n[](https://github.com/centrifugal/centrifuge-python/blob/master/LICENSE)\n\nThis is a WebSocket real-time SDK for [Centrifugo](https://github.com/centrifugal/centrifugo) server (and any [Centrifuge-based](https://github.com/centrifugal/centrifuge) server) on top of Python asyncio library.\n\n> [!TIP]\n> If you are looking for Centrifugo [server API](https://centrifugal.dev/docs/server/server_api) client \u2013 check out [pycent](https://github.com/centrifugal/pycent) instead.\n\nBefore starting to work with this library check out Centrifugo [client SDK API specification](https://centrifugal.dev/docs/transports/client_api) 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](https://centrifugal.dev/docs/transports/client_sdk#sdk-feature-matrix).\n\n## Install\n\n```\npip install centrifuge-python\n```\n\nThen in your code:\n\n```\nfrom centrifuge import Client\n```\n\nSee [example code](https://github.com/centrifugal/centrifuge-python/blob/master/example.py) and [how to run it](#run-example) locally.\n\n## JSON vs Protobuf protocols\n\nBy default, SDK uses JSON protocol. If you want to use Protobuf protocol instead then pass `use_protobuf=True` option to `Client` constructor.\n\nWhen using JSON protocol:\n\n* 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.\n* all payloads received from server are decoded to Python objects using `json.loads` internally before passing to your code.\n\nWhen using Protobuf protocol:\n\n* all payloads you pass to the library must be `bytes` or `None` if optional. If you pass non-`bytes` data \u2013 exception will be raised.\n* all payloads received from the library will be `bytes` or `None` if not present.\n* don't forget that when using Protobuf protocol you can still have JSON payloads - just encode them to `bytes` before passing to the library.\n\n## Callbacks should not block\n\nEvent 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.\n\nThe fact WebSocket read is blocked for the time we execute callbacks means that you can not call awaitable SDK APIs from callback \u2013 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`.\n\n## Run example\n\nTo run [example](https://github.com/centrifugal/centrifuge-python/blob/master/example.py), first start Centrifugo with config like this:\n\n```json\n{\n \"token_hmac_secret_key\": \"secret\",\n \"namespaces\": [\n {\n \"name\": \"example\",\n \"presence\": true,\n \"history_size\": 300,\n \"history_ttl\": \"300s\",\n \"join_leave\": true,\n \"force_push_join_leave\": true,\n \"allow_publish_for_subscriber\": true,\n \"allow_presence_for_subscriber\": true,\n \"allow_history_for_subscriber\": true\n }\n ]\n}\n```\n\nAnd then:\n\n```bash\npython -m venv env\n. env/bin/activate\nmake dev\npython example.py\n```\n\n## Run tests\n\nTo run tests, first start Centrifugo server:\n\n```bash\ndocker pull centrifugo/centrifugo:v5\ndocker run -d -p 8000:8000 -e CENTRIFUGO_LOG_LEVEL=trace \\\n-e CENTRIFUGO_TOKEN_HMAC_SECRET_KEY=\"secret\" -e CENTRIFUGO_PRESENCE=true \\\n-e CENTRIFUGO_JOIN_LEAVE=true -e CENTRIFUGO_FORCE_PUSH_JOIN_LEAVE=true \\\n-e CENTRIFUGO_HISTORY_TTL=300s -e CENTRIFUGO_HISTORY_SIZE=100 \\\n-e CENTRIFUGO_DELTA_PUBLISH=true -e CENTRIFUGO_ALLOWED_DELTA_TYPES=\"fossil\" \\\n-e CENTRIFUGO_FORCE_RECOVERY=true -e CENTRIFUGO_USER_SUBSCRIBE_TO_PERSONAL=true \\\n-e CENTRIFUGO_ALLOW_PUBLISH_FOR_SUBSCRIBER=true -e CENTRIFUGO_ALLOW_PRESENCE_FOR_SUBSCRIBER=true \\\n-e CENTRIFUGO_ALLOW_HISTORY_FOR_SUBSCRIBER=true centrifugo/centrifugo:v5 centrifugo\n```\n\nAnd then (from cloned repo root):\n\n```bash\npython -m venv env\n. env/bin/activate\nmake dev\nmake test\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "WebSocket SDK for Centrifugo (and any Centrifuge-based server) on top of Python asyncio library",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [
"centrifuge",
" centrifugo",
" pub/sub",
" realtime",
" websocket"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5891ca52c9ef7a353b0a60799091c46152b90acd104b6b27257d3d001a32a49f",
"md5": "5e4b9d488225aca86dfdd466c34bd0bc",
"sha256": "e414be7f49df76c782839775c36e746c5b1fda7b27eccb66296390ae079cfff1"
},
"downloads": -1,
"filename": "centrifuge_python-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e4b9d488225aca86dfdd466c34bd0bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25557,
"upload_time": "2024-10-10T19:32:18",
"upload_time_iso_8601": "2024-10-10T19:32:18.720571Z",
"url": "https://files.pythonhosted.org/packages/58/91/ca52c9ef7a353b0a60799091c46152b90acd104b6b27257d3d001a32a49f/centrifuge_python-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6816ff1c8751d5a266e4a713d4ae5396a0271d540b6189879bd77dfb4ca1d7d1",
"md5": "b8684775aad7f1354642180ed4d1b252",
"sha256": "5ee6a98b471a23a9df2479ecc63e56cf64a3f9fdae7df5b9be5b834d5a07b34f"
},
"downloads": -1,
"filename": "centrifuge_python-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "b8684775aad7f1354642180ed4d1b252",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37695,
"upload_time": "2024-10-10T19:32:20",
"upload_time_iso_8601": "2024-10-10T19:32:20.277749Z",
"url": "https://files.pythonhosted.org/packages/68/16/ff1c8751d5a266e4a713d4ae5396a0271d540b6189879bd77dfb4ca1d7d1/centrifuge_python-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 19:32:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "centrifuge-python"
}
JSON