Metadata-Version: 2.1
Name: django-dramatiq-pg
Version: 1.1.0
Summary: Integration of Django with dramatiq-pg
Home-page: https://github.com/uptick/django-dramatiq-pg
License: MIT
Author: Curtis Maloney
Author-email: curtis@tinbrain.net
Requires-Python: >=3.7,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: django (>=2.2)
Requires-Dist: dramatiq-pg (>=0.8.0)
Description-Content-Type: text/x-rst

==================
django_dramatiq_pg
==================

.. rubric:: ``dramatiq-pg`` integration for django

Installation
------------

1. Install with pip

   .. code-block:: sh

    $ pip install django-dramatiq-pg

2. Add to your ``INSTALLED_APPS`` list in settings.py

   .. code-block:: python

    INSTALLED_APPS = [
        ...
        'django_dramatiq_pg',
    ]

3. Create a Registry, and register your tasks

   .. code-block:: python

     from django_dramatiq_pg.registry import Registry

     tasks = Registry()


     @tasks.actor
     def mytask():
         ...

4. Configure

   .. code-block:: python

    DRAMATIQ_BROKER = {
        "OPTIONS": {
            "url": "postgres:///mydb",
        },
        "MIDDLEWARE": [
            "dramatiq.middleware.TimeLimit",
            "dramatiq.middleware.Callbacks",
            "dramatiq.middleware.Retries",
        ],
    }
    DRAMATIC_REGISTRY = 'myapp.registry.tasks'

5. Start the worker process:

   .. code-block:: sh

    $ dramatiq django_dramatiq_pg.worker

This worker module will auto-discover any module called 'actors' in
``INSTALLED_APPS``.

Registry
========

In a typical `dramatiq` application, the `Broker` is configured before any
tasks are registered. However, as `Django` is in control of the intialisation
sequence, there is an issue of ordering; the `actor` decorator assumes the
broker is already configured.

To resolve this, `django_dramatiq_pg` provides a `Registry` for your tasks,
which is then bound to the `Broker` when Django initialises.

In your code, declare a `Registry` instance, and use its `.actor` method to
decorate your task functions. Then tell `django_dramatiq_pg` to use your
registry with the `DRAMATIQ_REGISTRY` setting.

If you do not specify one, `django_dramatiq_pg` will create one on start.

The registry can be accessed as the `.registry` attribute on the
`django_dramatiq_pg` App instance.

Settings
--------

DRAMATIQ_BROKER
  A dict of options to pass when instantiating the broker.

DRAMATIC_BROKER['OPTIONS']
  Arguments to pass to the Broker.

DRAMATIC_BROKER['MIDDLEWARE']
  A list of middleware classes to be passed to the broker.

  These can either be import strings, or instances.

DRAMATIQ_ENCODER
  Default: None

  Import path for encoder class.

DRAMATIQ_ACTORS_MODULE
  Default: 'actors'

  Name of module use to auto-discover actors in INSTALLED_APPS.

DRAMATIQ_REGISTRY

  Import path for the task Registry instance.

  This should refer to an instance of `django_dramatiq_pg.registry.Registry`.

  This resolves the chicken/egg problem of declaring tasks before the broker is
  configured.

