# PyEnsign
PyEnsign is the official Python SDK for [Ensign](https://rotational.io/ensign), a distributed event store and stream-processing platform. This library allows you to interact with the Ensign API directly from Python in order to create [publishers](https://ensign.rotational.dev/eventing/glossary/#publisher) and [subscribers](https://ensign.rotational.dev/eventing/glossary/#subscriber).
## Installation
```
pip install pyensign
```
## Usage
Create a client from a client ID and client secret. If not provided, these will be obtained from the `ENSIGN_CLIENT_ID` and `ENSIGN_CLIENT_SECRET` variables.
```python
from pyensign.ensign import Ensign
client = Ensign(client_id=<your client ID>, client_secret=<your client secret>)
```
The `Event` class can be used to create events from the raw data and mimetype.
```python
from pyensign.events import Event
event = Event(b'{"temp": 72, "units": "fahrenheit"}', "application/json")
```
Publish events to a topic. This coroutine accepts one or more events, so the following uses are all valid.
```python
await client.publish("weather", event)
await client.publish("weather", event1, event2)
await client.publish("weather", [event1, event2])
```
Publish is asynchronous. You should generally call `flush()` before your program exits to ensure that all events are published to the server.
```python
# Wait for events to be published with a default timeout of 2 seconds.
await client.flush()
```
For more precision, you can wait for individual events to be acked by the server.
```python
ack = await event.wait_for_ack()
print(ack)
```
Subscribe to one or more topics by providing the topic name(s) or ID(s).
```python
async for event in client.subscribe("weather"):
print("Received event with data: {}".format(event.data))
await event.ack()
```
## Advanced Usage
The `publish` coroutine accepts asynchronous callbacks so the client can distinguish between committed and uncommitted events. Callbacks are invoked when acks and nacks are received from the server and the first argument passed to the callback is the `Ack` or `Nack` itself. An `Ack` contains a committed timestamp. A `Nack` is returned if the event couldn't be committed and contains the ID of the event along with an error describing what went wrong.
```python
async def handle_ack(self, ack):
ts = datetime.fromtimestamp(ack.committed.seconds + ack.committed.nanos / 1e9)
print(f"Event committed at {ts}")
async def handle_nack(self, nack):
print(f"Could not commit event {nack.id} with error {nack.code}: {nack.error}")
await client.publish("weather", event, on_ack=handle_ack, on_nack=handle_nack)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rotationalio/pyensign",
"name": "pyensign",
"maintainer": "Patrick Deziel",
"docs_url": null,
"requires_python": "",
"maintainer_email": "deziel.patrick@gmail.com",
"keywords": "python,setup,pypi",
"author": "Patrick Deziel",
"author_email": "deziel.patrick@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/35/11/859f10623101eae214436cbd5b5b6b4575f248feb8e9670763e0c4469663/pyensign-0.12b0.tar.gz",
"platform": null,
"description": "# PyEnsign\n\nPyEnsign is the official Python SDK for [Ensign](https://rotational.io/ensign), a distributed event store and stream-processing platform. This library allows you to interact with the Ensign API directly from Python in order to create [publishers](https://ensign.rotational.dev/eventing/glossary/#publisher) and [subscribers](https://ensign.rotational.dev/eventing/glossary/#subscriber).\n\n## Installation\n\n```\npip install pyensign\n```\n\n## Usage\n\nCreate a client from a client ID and client secret. If not provided, these will be obtained from the `ENSIGN_CLIENT_ID` and `ENSIGN_CLIENT_SECRET` variables.\n\n```python\nfrom pyensign.ensign import Ensign\n\nclient = Ensign(client_id=<your client ID>, client_secret=<your client secret>)\n```\n\nThe `Event` class can be used to create events from the raw data and mimetype.\n\n```python\nfrom pyensign.events import Event\n\nevent = Event(b'{\"temp\": 72, \"units\": \"fahrenheit\"}', \"application/json\")\n```\n\nPublish events to a topic. This coroutine accepts one or more events, so the following uses are all valid.\n\n```python\nawait client.publish(\"weather\", event)\nawait client.publish(\"weather\", event1, event2)\nawait client.publish(\"weather\", [event1, event2])\n```\n\nPublish is asynchronous. You should generally call `flush()` before your program exits to ensure that all events are published to the server.\n\n```python\n# Wait for events to be published with a default timeout of 2 seconds.\nawait client.flush()\n```\n\nFor more precision, you can wait for individual events to be acked by the server.\n\n```python\nack = await event.wait_for_ack()\nprint(ack)\n```\n\nSubscribe to one or more topics by providing the topic name(s) or ID(s).\n\n```python\nasync for event in client.subscribe(\"weather\"):\n print(\"Received event with data: {}\".format(event.data))\n await event.ack()\n```\n\n## Advanced Usage\n\nThe `publish` coroutine accepts asynchronous callbacks so the client can distinguish between committed and uncommitted events. Callbacks are invoked when acks and nacks are received from the server and the first argument passed to the callback is the `Ack` or `Nack` itself. An `Ack` contains a committed timestamp. A `Nack` is returned if the event couldn't be committed and contains the ID of the event along with an error describing what went wrong.\n\n```python\nasync def handle_ack(self, ack):\n ts = datetime.fromtimestamp(ack.committed.seconds + ack.committed.nanos / 1e9)\n print(f\"Event committed at {ts}\")\n\nasync def handle_nack(self, nack):\n print(f\"Could not commit event {nack.id} with error {nack.code}: {nack.error}\")\n\nawait client.publish(\"weather\", event, on_ack=handle_ack, on_nack=handle_nack)\n```\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Ensign driver, SDK, and helpers for Python",
"version": "0.12b0",
"project_urls": {
"Download": "https://github.com/rotationalio/pyensign/tarball/v0.12b0",
"Homepage": "https://github.com/rotationalio/pyensign"
},
"split_keywords": [
"python",
"setup",
"pypi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "466df2236eddb159f3f08fa4c854e9807ea12b84662e6f11362b93aed216e508",
"md5": "83c3bbe8118fe7f08b9d1a29209bea7c",
"sha256": "5985b8793b5d45cf4a95964771bbc10c4cf2188ad8544b00e8c0024663898983"
},
"downloads": -1,
"filename": "pyensign-0.12b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83c3bbe8118fe7f08b9d1a29209bea7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 61290,
"upload_time": "2023-10-23T20:55:06",
"upload_time_iso_8601": "2023-10-23T20:55:06.004531Z",
"url": "https://files.pythonhosted.org/packages/46/6d/f2236eddb159f3f08fa4c854e9807ea12b84662e6f11362b93aed216e508/pyensign-0.12b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3511859f10623101eae214436cbd5b5b6b4575f248feb8e9670763e0c4469663",
"md5": "c540a1bcdc5b953006b4629d7f035d25",
"sha256": "ff28f07cd62260da0f27b094184627da3c02675577dfe0623ceb3a1542324d76"
},
"downloads": -1,
"filename": "pyensign-0.12b0.tar.gz",
"has_sig": false,
"md5_digest": "c540a1bcdc5b953006b4629d7f035d25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 57872,
"upload_time": "2023-10-23T20:55:08",
"upload_time_iso_8601": "2023-10-23T20:55:08.167414Z",
"url": "https://files.pythonhosted.org/packages/35/11/859f10623101eae214436cbd5b5b6b4575f248feb8e9670763e0c4469663/pyensign-0.12b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-23 20:55:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rotationalio",
"github_project": "pyensign",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyensign"
}
JSON
