# django-temporalio
___
A small Django app that provides helpers for integrating [Temporal.io](https://temporal.io/) with Django.
## Features
- Registry: Provides a registry that holds mappings between queue names and registered activities and workflows.
- Management Commands: Includes management commands to manage Temporal.io workers and sync schedules.
## Installation
You can install `django_temporalio` using pip:
```bash
$ pip install django-temporalio
```
Add `django_temporalio` to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...
'django_temporalio.apps.DjangoTemporalioConfig',
...
]
```
Add the following settings to your `settings.py`:
```python
from temporalio.worker import WorkerConfig
DJANGO_TEMPORALIO = {
"CLIENT_CONFIG": {
"target_host": "localhost:7233",
},
"BASE_MODULE": "path.to.module",
"WORKER_CONFIGS": {
"main": WorkerConfig(
task_queue="MAIN_TASK_QUEUE",
...
),
...
},
}
```
## Usage
Activities, workflows and schedules should be placed inside the base module defined by the `BASE_MODULE` setting,
preferably outside of any Django application, in order to keep the uses of
the [imports_passed_through](https://python.temporal.io/temporalio.workflow.unsafe.html) context manager encapsulated
inside the module, along with Temporal.io related code.
### Workflow and Activity Registry
The registry is a singleton that holds mappings between queue names and registered activities and workflows.
You can register activities and workflows using the `register` method.
Activities and workflows should be declared in modules matching the following patterns `*workflows*.py` and
`*activities*.py` respectively.
```python
from temporalio import activity, workflow
from django_temporalio.registry import queue_activities, queue_workflows
@queue_activities.register("HIGH_PRIORITY_TASK_QUEUE", "MAIN_TASK_QUEUE")
@activity.defn
def my_activity():
pass
@queue_workflows.register("HIGH_PRIORITY_TASK_QUEUE", "MAIN_TASK_QUEUE")
@workflow.defn
class MyWorkflow:
pass
```
### Schedule Registry
You can register schedules using the `register` method.
Schedules should be declared in `schedules.py` module.
```python
from django_temporalio.registry import schedules
from temporalio.client import Schedule
schedules.register("do-cool-stuff-every-hour", Schedule(...))
```
### Management Commands
To see a queue's registered activities and workflows:
```bash
$ ./manage.py show_temporalio_queue_registry
```
To start a worker defined in the settings (for production):
```bash
$ ./manage.py start_temporalio_worker <worker_name>
```
To start a worker for development (starts a worker for each registered queue, WORKER_CONFIGS setting is ignored):
```bash
$ ./manage.py start_temporalio_worker --all
```
To sync schedules with Temporal.io:
```bash
$ ./manage.py sync_temporalio_schedules
```
To see what sync operation would do without actually syncing:
```bash
$ ./manage.py sync_temporal_schedules --dry-run
```
## Configuration
You can configure the app using the following settings:
DJANGO_TEMPORALIO: A dictionary containing the following keys:
- CLIENT_CONFIG: A dictionary of kwargs that are passed to the `temporalio.client.Client.connect`
method on the client initialization, defaults to `{}`
- WORKER_CONFIGS: A dictionary containing worker configurations.
The key is the worker name and the value is a `temporalio.worker.WorkerConfig` instance.
- BASE_MODULE: A python module that holds workflows, activities and schedules, defaults to `None`
## 1.0.0 (2024-05-16)
* Initial release
## 1.1.0 (2024-05-30)
* add Temporal.io related code encapsulation
## 1.2.0 (2024-10-17)
* replaced `NAMESPACE` and `URL` settings with `CLIENT_CONFIG` setting
Raw data
{
"_id": null,
"home_page": "https://github.com/RegioHelden/django-temporalio",
"name": "django-temporalio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "django, temporal.io, temporal",
"author": "RegioHelden GmbH",
"author_email": "opensource@regiohelden.de",
"download_url": "https://files.pythonhosted.org/packages/91/e5/a6fc0b2900542c514a2b55d588a9e8cb6472b3a4cbe8103c2abb8e8f1add/django_temporalio-1.2.0.tar.gz",
"platform": null,
"description": "# django-temporalio\n___\n\nA small Django app that provides helpers for integrating [Temporal.io](https://temporal.io/) with Django.\n\n## Features\n\n- Registry: Provides a registry that holds mappings between queue names and registered activities and workflows.\n- Management Commands: Includes management commands to manage Temporal.io workers and sync schedules.\n\n## Installation\n\nYou can install `django_temporalio` using pip:\n\n```bash\n$ pip install django-temporalio\n```\n\nAdd `django_temporalio` to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n ...\n 'django_temporalio.apps.DjangoTemporalioConfig',\n ...\n]\n```\n\nAdd the following settings to your `settings.py`:\n\n```python\nfrom temporalio.worker import WorkerConfig\n\nDJANGO_TEMPORALIO = {\n \"CLIENT_CONFIG\": {\n \"target_host\": \"localhost:7233\",\n },\n \"BASE_MODULE\": \"path.to.module\",\n \"WORKER_CONFIGS\": {\n \"main\": WorkerConfig(\n task_queue=\"MAIN_TASK_QUEUE\",\n ...\n ),\n ...\n },\n}\n```\n\n## Usage\n\nActivities, workflows and schedules should be placed inside the base module defined by the `BASE_MODULE` setting, \npreferably outside of any Django application, in order to keep the uses of \nthe [imports_passed_through](https://python.temporal.io/temporalio.workflow.unsafe.html) context manager encapsulated \ninside the module, along with Temporal.io related code.\n\n### Workflow and Activity Registry\n\nThe registry is a singleton that holds mappings between queue names and registered activities and workflows.\nYou can register activities and workflows using the `register` method. \n\nActivities and workflows should be declared in modules matching the following patterns `*workflows*.py` and \n`*activities*.py` respectively. \n\n```python\nfrom temporalio import activity, workflow\nfrom django_temporalio.registry import queue_activities, queue_workflows\n\n@queue_activities.register(\"HIGH_PRIORITY_TASK_QUEUE\", \"MAIN_TASK_QUEUE\")\n@activity.defn\ndef my_activity():\n pass\n\n@queue_workflows.register(\"HIGH_PRIORITY_TASK_QUEUE\", \"MAIN_TASK_QUEUE\")\n@workflow.defn\nclass MyWorkflow:\n pass\n```\n\n### Schedule Registry\n\nYou can register schedules using the `register` method. \n\nSchedules should be declared in `schedules.py` module.\n\n```python\nfrom django_temporalio.registry import schedules\nfrom temporalio.client import Schedule\n\n\nschedules.register(\"do-cool-stuff-every-hour\", Schedule(...))\n```\n\n### Management Commands\n\nTo see a queue's registered activities and workflows:\n\n```bash\n$ ./manage.py show_temporalio_queue_registry\n```\n\nTo start a worker defined in the settings (for production):\n\n```bash\n$ ./manage.py start_temporalio_worker <worker_name>\n```\n\nTo start a worker for development (starts a worker for each registered queue, WORKER_CONFIGS setting is ignored):\n\n```bash\n$ ./manage.py start_temporalio_worker --all\n```\n\nTo sync schedules with Temporal.io:\n\n```bash\n$ ./manage.py sync_temporalio_schedules\n```\n\nTo see what sync operation would do without actually syncing:\n\n```bash\n$ ./manage.py sync_temporal_schedules --dry-run\n```\n\n## Configuration\n\nYou can configure the app using the following settings:\n\nDJANGO_TEMPORALIO: A dictionary containing the following keys:\n\n- CLIENT_CONFIG: A dictionary of kwargs that are passed to the `temporalio.client.Client.connect` \n method on the client initialization, defaults to `{}`\n- WORKER_CONFIGS: A dictionary containing worker configurations. \n The key is the worker name and the value is a `temporalio.worker.WorkerConfig` instance.\n- BASE_MODULE: A python module that holds workflows, activities and schedules, defaults to `None`\n\n\n## 1.0.0 (2024-05-16)\n\n* Initial release\n\n## 1.1.0 (2024-05-30)\n\n* add Temporal.io related code encapsulation \n\n## 1.2.0 (2024-10-17)\n\n* replaced `NAMESPACE` and `URL` settings with `CLIENT_CONFIG` setting\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Temporal.io integration for Django",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/RegioHelden/django-temporalio"
},
"split_keywords": [
"django",
" temporal.io",
" temporal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3ef9b5ac0b83b11cc8de60f495ff9f4cd92ce455cc71cf37ed10923deb8b43df",
"md5": "d80bfb524f4714986ff17a5bac509192",
"sha256": "5aa4e3dd92d30e11b4d58666f99e66df0f46c72559a0b50ba97aec37e2104f16"
},
"downloads": -1,
"filename": "django_temporalio-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d80bfb524f4714986ff17a5bac509192",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10547,
"upload_time": "2024-10-17T16:05:09",
"upload_time_iso_8601": "2024-10-17T16:05:09.524194Z",
"url": "https://files.pythonhosted.org/packages/3e/f9/b5ac0b83b11cc8de60f495ff9f4cd92ce455cc71cf37ed10923deb8b43df/django_temporalio-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91e5a6fc0b2900542c514a2b55d588a9e8cb6472b3a4cbe8103c2abb8e8f1add",
"md5": "190e58b01b353b3a0bb651641c6fcb07",
"sha256": "35b36f1a37fd4cd0a79016e57682e54a1efbb485b398002a28b3c14ad5091cfe"
},
"downloads": -1,
"filename": "django_temporalio-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "190e58b01b353b3a0bb651641c6fcb07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9429,
"upload_time": "2024-10-17T16:05:10",
"upload_time_iso_8601": "2024-10-17T16:05:10.906984Z",
"url": "https://files.pythonhosted.org/packages/91/e5/a6fc0b2900542c514a2b55d588a9e8cb6472b3a4cbe8103c2abb8e8f1add/django_temporalio-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 16:05:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RegioHelden",
"github_project": "django-temporalio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-temporalio"
}
JSON
