Skip to main content

Metroid - Metro for Django

Project description


Subscribe, act, publish.

Python version Django version Celery version ServiceBus version Django GUID version

Codecov Pre-commit Black mypy isort

Metroid - Metro for Django

This app is intended to streamline integration with Metro for all Django+Celery users by:

  • Asynchronous handling of subscriptions and messages with one command
  • Execute Celery tasks based on message topics, defined in
  • Retry failed tasks through your admin dashboard when using the MetroidTask base


  • python >= 3.10
  • django >= 4.2 - For asgiref, settings
  • django-guid >= 3.2.0 - Storing correlation IDs for failed tasks in the database, making debugging easy
  • Choose one:
    • celery >= 5.3.0 - Execute tasks based on a subject
    • django-rq >= 2.4.1 - Execute tasks based on a subject


The python metroid app is fully asynchronous, and has no blocking code. It utilizes Celery to execute tasks.

It works by:

  1. Going through all your configured subscriptions and start a new async connection for each one of them
  2. Metro sends messages on the subscriptions
  3. This app filters out messages matching subjects you have defined, and queues a celery task to execute the function as specified for that subject
    3.1. If no task is found for that subject, the message is marked as complete
  4. The message is marked as complete after the Celery task has successfully been queued
  5. If the task is failed, an entry is automatically created in your database
  6. All failed tasks can be retried manually through the admin dashboard

Configure and install this package

Note For a complete example, have a look in demoproj/

  1. Create a METROID key in with all your subscriptions and handlers. Example settings:
    'subscriptions': [
            'topic_name': 'metro-demo',
            'subscription_name': 'sub-metrodemo-metrodemoerfett',
            'connection_string': config('CONNECTION_STRING_METRO_DEMO', None),
            'handlers': [
                  'subject': 'MetroDemo/Type/GeekJokes',
                  'regex': False,
                  'handler_function': ''
   'worker_type': 'celery', # default

The handler_function is defined by providing the full dotted path as a string. For example,from import my_func is provided as ''.

The handlers subject can be a regular expression or a string. If a regular expression is provided, the variable regex must be set to True. Example:

'handlers': [{'subject': r'^MetroDemo/Type/.*$','regex':True,'handler_function': my_func}],
  1. Configure Django-GUID by adding the app to your installed apps, to your middlewares and configuring logging as described here. Make sure you enable the CeleryIntegration:
from django_guid.integrations import CeleryIntegration


Creating your own handler functions

Your functions will be called with keyword arguments for

message, topic_name, subscription_name and subject. You function should in other words look something like this:

def my_func(*, message: dict, topic_name: str, subscription_name: str, subject: str) -> None:
def my_func(*, message: dict, topic_name: str, subscription_name: str, subject: str) -> None:

Running the project

  1. Ensure you have redis running:
docker-compose up
  1. Run migrations
python migrate
  1. Create an admin account
python createsuperuser
  1. Start a worker:
celery -A demoproj worker -l info
  1. Run the subscriber:
python metroid
  1. Send messages to Metro. Example code can be found in demoproj/demoapp/
  2. Run the webserver:
python runserver 8000
  1. See failed messages under http://localhost:8080/admin

To contribute, please see

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

metroid-1.4.0.tar.gz (15.0 kB view hashes)

Uploaded Source

Built Distribution

metroid-1.4.0-py3-none-any.whl (18.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page