README.md

django-temporalio

---

A small Django app that provides helpers for integrating 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:

$ pip install django-temporalio

Add django_temporalio to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'django_temporalio.apps.DjangoTemporalioConfig',
    ...
]

Add the following settings to your settings.py:

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 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.

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.

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:

$ ./manage.py show_temporalio_queue_registry

To start a worker defined in the settings (for production):

$ ./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):

$ ./manage.py start_temporalio_worker --all

To sync schedules with Temporal.io:

$ ./manage.py sync_temporalio_schedules

To see what sync operation would do without actually syncing:

$ ./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