# Python Novu SDK
[](https://pypi.org/project/novu/)
[](https://codecov.io/gh/novuhq/novu-python)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/psf/black)
[](http://mypy-lang.org/)
[](https://github.com/semantic-release/semantic-release)
---
The [Python Novu](https://novu.co) SDK and package provides a fluent and expressive interface for interacting with [Novu's API](https://api.novu.co/api) and managing notifications.
## Install
To install this package
```shell
# Via pip
pip install novu
# Via poetry
poetry add novu
```
## Contents
- [Install](#install)
- [Quick start](#quick-start)
- [Code Snippet Examples](#code-snippet-examples)
- [Events](#events)
- [Subscribers](#subscribers)
- [Topics](#topics)
- [Feeds](#feeds)
- [Environments](#environments)
- [Go further](#go-further)
- [Development](#development)
## Quick start
This package is a wrapper of all the resources offered by Novu, we will just start by triggering an event on Novu.
To do this, you will need to:
1. Create your first notification workflow and keep in mind the identifier to trigger the workflow: https://docs.novu.co/overview/quickstart/general-quickstart#create-a-workflow
2. Retrieve your API key from the Novu dashboard directly in the settings section: https://web.novu.co/settings
3. Write code to trigger your first event:
```python
from novu.api import EventApi
event_api = EventApi("https://api.novu.co", "<NOVU_API_KEY>")
event_api.trigger(
name="<YOUR_WORKFLOW_ID>", # The workflow ID is the slug of the workflow name. It can be found on the workflow page.
recipients="<YOUR_SUBSCRIBER_ID>",
payload={}, # Your Novu payload goes here
)
```
This will trigger a notification to the subscribers.
## Code Snippet Examples
### Events
Firstly, make imports and declare the needed variables this way:
```python
from novu.api import EventApi
url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"
# You can sign up on https://web.novu.co to get your API key from https://web.novu.co/settings
```
**Trigger an event** - Send notification to subscribers:
```python
from novu.api import EventApi
novu = EventApi(url, api_key).trigger(
name="digest-workflow-example", # This is the Workflow ID. It can be found on the workflow page.
recipients="<SUBSCRIBER_IDENTIFIER>", # The subscriber ID can be gotten from the dashboard.
payload={}, # Your custom Novu payload goes here
)
```
**Bulk Trigger events** - Trigger multiple events at once:
```python
from novu.dto.event import InputEventDto
from novu.api import EventApi
url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"
event_1 = InputEventDto(
name="digest-workflow-example", # The workflow ID is the slug of the workflow name. It can be found on the workflow page.
recipients="<SUBSCRIBER_IDENTIFIER>",
payload={}, # Your custom Novu payload goes here
)
event_2 = InputEventDto(
name="digest-workflow-example",
recipients="<SUBSCRIBER_IDENTIFIER>",
payload={},
)
novu = EventApi("https://api.novu.co", api_key).trigger_bulk(events=[event1, event2])
```
**Include actor field:**
```python
from novu.api import EventApi
novu = EventApi(url, api_key).trigger(
name="workflow_trigger_identifier",
recipients="subscriber_id",
actor={
"subscriberId": "subscriber_id_actor"
},
payload={
"key":"value"
},
)
```
**Broadcast to all current subscribers:**
```python
novu = EventApi(url, api_key).broadcast(
name="digest-workflow-example",
payload={"customVariable": "value"}, # Optional
)
```
### Subscribers
```python
from novu.dto.subscriber import SubscriberDto
from novu.api.subscriber import SubscriberApi
url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"
# Define a subscriber instance
subscriber = SubscriberDto(
email="novu_user@mail.com",
subscriber_id="82a48af6ac82b3cc2157b57f", #This is what the subscriber_id looks like
first_name="", # Optional
last_name="", # Optional
phone="", # Optional
avatar="", # Optional
)
# Create a subscriber
novu = SubscriberApi(url, api_key).create(subscriber)
# Get a subscriber
novu = SubscriberApi(url, api_key).get(subscriber_id)
# Get list of subscribers
novu = SubscriberApi(url, api_key).list()
```
### Topics
```python
from novu.api import TopicApi
url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"
# Create a topic
novu = TopicApi(url, api_key).create(
key="new-customers", name="New business customers"
)
# Get a topic
novu = TopicApi(url, api_key).get(key="new-customers")
# List topics
novu = TopicApi(url, api_key).list()
# Rename a topic
novu = TopicApi(url, api_key).rename(key="new-customers", name="New business customers")
# Subscribe a list of subscribers to a topic
novu = TopicApi(url, api_key).subscribe(key="old-customers", subscribers="<LIST_OF_SUBSCRIBER_IDs>")
# Unsubscribe a list of subscribers from a topic
novu = TopicApi(url, api_key).unsubscribe(key="old-customers", subscribers="<LIST_OF_SUBSCRIBER_IDs>")
```
### Feeds
```python
from novu.api.feed import FeedApi
url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"
# Create a Feed
novu = FeedApi(url, api_key).create(name="<SUPPLY_NAME_FOR_FEED>")
# Delete a Feed
FeedApi(url, api_key).delete(feed_id="<FEED_NOVU_INTERNAL_ID>")
# List feeds
novu = FeedApi(url, api_key).list()
```
### Environments
```python
from novu.api.environment import EnvironmentApi
url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"
# Create an Environment
novu = EnvironmentApi(url, api_key).create(
name="<INSERT_NAME>",
parent_id="<INSERT_PARENT_ID>" # Optional. Defaults to None
)
# # List existing environments
novu = EnvironmentApi(url, api_key).list()
# # Get the current environment
novu = EnvironmentApi(url, api_key).current()
# # Retrieve an environment's API_KEY
novu = EnvironmentApi(url, api_key).api_keys()
```
### Tenants
```python
from novu.api.tenant import TenantApi
url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"
# Create an Environment
tenant = TenantApi(url, api_key).create(
identifier="<INSERT_UNIQUE_TENANT_ID>",
name="<INSERT_NAME>",
data={} # Optional. Defaults to {}
)
# List existing tenants
tenants = TenantApi(url, api_key).list()
tenants = TenantApi(url, api_key).list(page=1, limit=10)
# Get a tenant
tenant = TenantApi(url, api_key).get("<TENANT-IDENTIFIER>")
# Patch some field of a tenant
tenant = TenantApi(url, api_key).patch(
"<CURRENT-TENANT-IDENTIFIER>",
identifier="<NEW-IDENTIFIER>",
name="<NEW-NAME>",
data="<NEW-DATA>"
)
# Delete a tenant
TenantApi(url, api_key).delete("<TENANT-IDENTIFIER>")
```
## Go further
After a quick start with the SDK, you'll quickly get to grips with the advanced use of the SDK and the other APIs available.
For this purpose, documentation is available here: https://novu-python.readthedocs.io/
## Development
```bash
# install deps
poetry install
# pre-commit
poetry run pre-commit install --install-hook
poetry run pre-commit install --install-hooks --hook-type commit-msg
```
## Contributing
Feature requests, bug reports and pull requests are welcome. Please create an [issue](https://github.com/novuhq/novu-python/issues).
## Support and Feedback
Be sure to visit the Novu official [documentation website](https://docs.novu.co/docs) for additional information about our SDK.
If you need additional assistance, join our Discord server [here](https://discord.novu.co).
## License
Novu Python SDK is licensed under the MIT License - see the [LICENSE](https://github.com/novuhq/novu-python/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://novu-python.readthedocs.io/en/latest",
"name": "novu",
"maintainer": "oscar.marie-taillefer",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "oscar.marie-taillefer@spikeelabs.fr",
"keywords": "novu,python,sdk,api,wrapper",
"author": "oscar.marie-taillefer",
"author_email": "oscar.marie-taillefer@spikeelabs.fr",
"download_url": "https://files.pythonhosted.org/packages/c3/9b/0a8d648b91eba349a3454f907f5b0156f8e9767cfddef5edc3cab1f85f9c/novu-1.14.0.tar.gz",
"platform": null,
"description": "# Python Novu SDK\n\n[](https://pypi.org/project/novu/)\n\n[](https://codecov.io/gh/novuhq/novu-python)\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/psf/black)\n[](http://mypy-lang.org/)\n\n\n[](https://github.com/semantic-release/semantic-release)\n\n---\n\nThe [Python Novu](https://novu.co) SDK and package provides a fluent and expressive interface for interacting with [Novu's API](https://api.novu.co/api) and managing notifications.\n\n## Install\n\nTo install this package\n\n```shell\n# Via pip\npip install novu\n\n# Via poetry\npoetry add novu\n```\n\n## Contents\n\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Code Snippet Examples](#code-snippet-examples)\n - [Events](#events)\n - [Subscribers](#subscribers)\n - [Topics](#topics)\n - [Feeds](#feeds)\n - [Environments](#environments)\n- [Go further](#go-further)\n- [Development](#development)\n\n## Quick start\n\nThis package is a wrapper of all the resources offered by Novu, we will just start by triggering an event on Novu.\n\nTo do this, you will need to:\n\n1. Create your first notification workflow and keep in mind the identifier to trigger the workflow: https://docs.novu.co/overview/quickstart/general-quickstart#create-a-workflow\n2. Retrieve your API key from the Novu dashboard directly in the settings section: https://web.novu.co/settings\n3. Write code to trigger your first event:\n\n```python\nfrom novu.api import EventApi\n\nevent_api = EventApi(\"https://api.novu.co\", \"<NOVU_API_KEY>\")\nevent_api.trigger(\n name=\"<YOUR_WORKFLOW_ID>\", # The workflow ID is the slug of the workflow name. It can be found on the workflow page.\n recipients=\"<YOUR_SUBSCRIBER_ID>\",\n payload={}, # Your Novu payload goes here\n)\n```\n\nThis will trigger a notification to the subscribers.\n\n## Code Snippet Examples\n\n### Events\n\nFirstly, make imports and declare the needed variables this way:\n\n```python\nfrom novu.api import EventApi\n\nurl = \"https://api.novu.co\"\napi_key = \"<NOVU_API_KEY>\"\n\n# You can sign up on https://web.novu.co to get your API key from https://web.novu.co/settings\n```\n\n**Trigger an event** - Send notification to subscribers:\n\n```python\nfrom novu.api import EventApi\n\nnovu = EventApi(url, api_key).trigger(\n name=\"digest-workflow-example\", # This is the Workflow ID. It can be found on the workflow page.\n recipients=\"<SUBSCRIBER_IDENTIFIER>\", # The subscriber ID can be gotten from the dashboard.\n payload={}, # Your custom Novu payload goes here\n)\n```\n\n**Bulk Trigger events** - Trigger multiple events at once:\n\n```python\nfrom novu.dto.event import InputEventDto\nfrom novu.api import EventApi\n\nurl = \"https://api.novu.co\"\napi_key = \"<NOVU_API_KEY>\"\n\nevent_1 = InputEventDto(\n name=\"digest-workflow-example\", # The workflow ID is the slug of the workflow name. It can be found on the workflow page.\n recipients=\"<SUBSCRIBER_IDENTIFIER>\",\n payload={}, # Your custom Novu payload goes here\n)\nevent_2 = InputEventDto(\n name=\"digest-workflow-example\",\n recipients=\"<SUBSCRIBER_IDENTIFIER>\",\n payload={},\n)\n\nnovu = EventApi(\"https://api.novu.co\", api_key).trigger_bulk(events=[event1, event2])\n```\n\n**Include actor field:**\n\n```python\nfrom novu.api import EventApi\n\nnovu = EventApi(url, api_key).trigger(\n name=\"workflow_trigger_identifier\",\n recipients=\"subscriber_id\",\n actor={\n \"subscriberId\": \"subscriber_id_actor\"\n },\n payload={\n \"key\":\"value\"\n },\n)\n```\n\n**Broadcast to all current subscribers:**\n\n```python\nnovu = EventApi(url, api_key).broadcast(\n name=\"digest-workflow-example\",\n payload={\"customVariable\": \"value\"}, # Optional\n)\n```\n\n### Subscribers\n\n```python\nfrom novu.dto.subscriber import SubscriberDto\nfrom novu.api.subscriber import SubscriberApi\n\nurl = \"https://api.novu.co\"\napi_key = \"<NOVU_API_KEY>\"\n\n# Define a subscriber instance\nsubscriber = SubscriberDto(\n email=\"novu_user@mail.com\",\n subscriber_id=\"82a48af6ac82b3cc2157b57f\", #This is what the subscriber_id looks like\n first_name=\"\", # Optional\n last_name=\"\", # Optional\n phone=\"\", # Optional\n avatar=\"\", # Optional\n)\n\n# Create a subscriber\nnovu = SubscriberApi(url, api_key).create(subscriber)\n\n# Get a subscriber\nnovu = SubscriberApi(url, api_key).get(subscriber_id)\n\n# Get list of subscribers\nnovu = SubscriberApi(url, api_key).list()\n```\n\n### Topics\n\n```python\nfrom novu.api import TopicApi\n\nurl = \"<NOVU_URL>\"\napi_key = \"<NOVU_API_KEY>\"\n\n# Create a topic\nnovu = TopicApi(url, api_key).create(\n key=\"new-customers\", name=\"New business customers\"\n)\n\n# Get a topic\nnovu = TopicApi(url, api_key).get(key=\"new-customers\")\n\n# List topics\nnovu = TopicApi(url, api_key).list()\n\n# Rename a topic\nnovu = TopicApi(url, api_key).rename(key=\"new-customers\", name=\"New business customers\")\n\n# Subscribe a list of subscribers to a topic\nnovu = TopicApi(url, api_key).subscribe(key=\"old-customers\", subscribers=\"<LIST_OF_SUBSCRIBER_IDs>\")\n\n# Unsubscribe a list of subscribers from a topic\nnovu = TopicApi(url, api_key).unsubscribe(key=\"old-customers\", subscribers=\"<LIST_OF_SUBSCRIBER_IDs>\")\n\n```\n\n### Feeds\n\n```python\nfrom novu.api.feed import FeedApi\n\nurl = \"<NOVU_URL>\"\napi_key = \"<NOVU_API_KEY>\"\n\n# Create a Feed\nnovu = FeedApi(url, api_key).create(name=\"<SUPPLY_NAME_FOR_FEED>\")\n\n# Delete a Feed\nFeedApi(url, api_key).delete(feed_id=\"<FEED_NOVU_INTERNAL_ID>\")\n\n# List feeds\nnovu = FeedApi(url, api_key).list()\n```\n\n### Environments\n\n```python\nfrom novu.api.environment import EnvironmentApi\n\nurl = \"<NOVU_URL>\"\napi_key = \"<NOVU_API_KEY>\"\n\n# Create an Environment\nnovu = EnvironmentApi(url, api_key).create(\n name=\"<INSERT_NAME>\",\n parent_id=\"<INSERT_PARENT_ID>\" # Optional. Defaults to None\n)\n\n# # List existing environments\nnovu = EnvironmentApi(url, api_key).list()\n\n# # Get the current environment\nnovu = EnvironmentApi(url, api_key).current()\n\n# # Retrieve an environment's API_KEY\nnovu = EnvironmentApi(url, api_key).api_keys()\n\n```\n\n### Tenants\n\n```python\nfrom novu.api.tenant import TenantApi\n\nurl = \"<NOVU_URL>\"\napi_key = \"<NOVU_API_KEY>\"\n\n# Create an Environment\ntenant = TenantApi(url, api_key).create(\n identifier=\"<INSERT_UNIQUE_TENANT_ID>\",\n name=\"<INSERT_NAME>\",\n data={} # Optional. Defaults to {}\n)\n\n# List existing tenants\ntenants = TenantApi(url, api_key).list()\ntenants = TenantApi(url, api_key).list(page=1, limit=10)\n\n# Get a tenant\ntenant = TenantApi(url, api_key).get(\"<TENANT-IDENTIFIER>\")\n\n# Patch some field of a tenant\ntenant = TenantApi(url, api_key).patch(\n \"<CURRENT-TENANT-IDENTIFIER>\",\n identifier=\"<NEW-IDENTIFIER>\",\n name=\"<NEW-NAME>\",\n data=\"<NEW-DATA>\"\n)\n\n# Delete a tenant\nTenantApi(url, api_key).delete(\"<TENANT-IDENTIFIER>\")\n```\n\n## Go further\n\nAfter a quick start with the SDK, you'll quickly get to grips with the advanced use of the SDK and the other APIs available.\n\nFor this purpose, documentation is available here: https://novu-python.readthedocs.io/\n\n## Development\n\n```bash\n# install deps\npoetry install\n\n# pre-commit\npoetry run pre-commit install --install-hook\npoetry run pre-commit install --install-hooks --hook-type commit-msg\n```\n\n## Contributing\n\nFeature requests, bug reports and pull requests are welcome. Please create an [issue](https://github.com/novuhq/novu-python/issues).\n\n## Support and Feedback\n\nBe sure to visit the Novu official [documentation website](https://docs.novu.co/docs) for additional information about our SDK.\nIf you need additional assistance, join our Discord server [here](https://discord.novu.co).\n\n## License\n\nNovu Python SDK is licensed under the MIT License - see the [LICENSE](https://github.com/novuhq/novu-python/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This project aims to provide a wrapper for the Novu API.",
"version": "1.14.0",
"project_urls": {
"Changelog": "https://github.com/novuhq/novu-python/blob/main/CHANGELOG.md",
"Documentation": "https://novu-python.readthedocs.io/en/latest",
"Homepage": "https://novu-python.readthedocs.io/en/latest",
"Repository": "https://github.com/novuhq/novu-python",
"Tracker": "https://github.com/novuhq/novu-python/issues"
},
"split_keywords": [
"novu",
"python",
"sdk",
"api",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3742a7ec733c40011a2674dad06d9931d211b27875709fe38b9b305a2e931a2a",
"md5": "57ba83b828e6cce38199f468672624ed",
"sha256": "fc152604257f7b7de7bcd818b98191eda6fddfd48d264a2d2ec22c5d70dfc78f"
},
"downloads": -1,
"filename": "novu-1.14.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "57ba83b828e6cce38199f468672624ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 59264,
"upload_time": "2024-02-26T10:57:43",
"upload_time_iso_8601": "2024-02-26T10:57:43.977213Z",
"url": "https://files.pythonhosted.org/packages/37/42/a7ec733c40011a2674dad06d9931d211b27875709fe38b9b305a2e931a2a/novu-1.14.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c39b0a8d648b91eba349a3454f907f5b0156f8e9767cfddef5edc3cab1f85f9c",
"md5": "8d640d7215be85fb71a9bcc8d6b12678",
"sha256": "51b175b2c692382e751cbb483fcd2289f4ed8345a78befa78a2730fe69ecd31d"
},
"downloads": -1,
"filename": "novu-1.14.0.tar.gz",
"has_sig": false,
"md5_digest": "8d640d7215be85fb71a9bcc8d6b12678",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 37166,
"upload_time": "2024-02-26T10:57:45",
"upload_time_iso_8601": "2024-02-26T10:57:45.442946Z",
"url": "https://files.pythonhosted.org/packages/c3/9b/0a8d648b91eba349a3454f907f5b0156f8e9767cfddef5edc3cab1f85f9c/novu-1.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 10:57:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "novuhq",
"github_project": "novu-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "novu"
}
JSON
