Muffin-Donald

Muffin-Donald is a plugin for the Muffin framework that provides support for asynchronous background tasks, workers, and scheduling.

Features

✅ Register async tasks
✅ Run background workers
✅ Schedule periodic tasks (cron or intervals)
✅ RPC-style submit and wait for result
✅ Muffin plugin integration with lifecycle management

Requirements

python >= 3.11
muffin >= 0.60.0
donald >= 0.1.0

Installation

pip install muffin-donald

Usage

Initialize the plugin:

import muffin
from muffin_donald import Plugin

app = muffin.Application("example")

tasks = Plugin(app, backend="redis", backend_params={
    "url": "redis://localhost:6379/0"
}, start_worker=True, start_scheduler=True)

@tasks.task()
async def my_task(x, y):
    return x + y

Submit task for background execution:

my_task.submit(1, 2)

Submit and wait for result (RPC style):

result = await my_task.submit_and_wait(1, 2)
print("Result:", result)  # Result: 3

Schedule a periodic task:

@tasks.task()
async def periodic_task():
    print("Periodic task executed")

periodic_task.schedule("*/5 * * * *")  # every 5 minutes

Handle task errors with on_error:

@tasks.on_error
async def handle_error(exc):
    print("Task error:", exc)

Lifecycle hooks:

@tasks.on_start
async def startup():
    print("Tasks manager started")

@tasks.on_stop
async def shutdown():
    print("Tasks manager stopped")

Healthcheck commands:

muffin <app> tasks-worker-health
muffin <app> tasks-scheduler-health

Returns exit code 0 if healthy
Returns exit code 1 if unhealthy

Commands

Command	Description
tasks-worker	Run the worker process
tasks-scheduler	Run the scheduler
tasks-worker-health	Check worker health
tasks-scheduler-health	Check scheduler health

Configuration Options

You can configure the plugin via parameters or Muffin settings (with TASKS_ prefix):

Name	Default	Description
log_level	INFO	Logger level
log_config	None	Logger config
backend	memory	Backend: memory, redis, amqp
backend_params	{}	Backend connection params
worker_params	{}	Worker params
start_worker	False	Auto start a worker on startup
start_scheduler	False	Auto start a scheduler on startup

Example in Muffin settings:

TASKS_BACKEND = "redis"
TASKS_BACKEND_PARAMS = {"url": "redis://localhost:6379/0"}
TASKS_START_WORKER = True
TASKS_START_SCHEDULER = True

Testing

Example using manage_lifespan:

import pytest
from asgi_tools.tests import manage_lifespan

async def test_tasks(app, tasks):
    async with manage_lifespan(app):
        result = await my_task.submit_and_wait(1, 2)
        assert result == 3

Bug Tracker

Please report issues or suggestions at https://github.com/klen/muffin-donald/issues

Contributing

Development happens at: https://github.com/klen/muffin-donald

Contributors

klen (Kirill Klenov)

License

Licensed under the MIT license.

Metadata

Release files for muffin-donald 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for muffin-donald 2.0.0
File	Size	Uploaded
muffin_donald-2.0.0.tar.gz	4.1 kB	Jun 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for muffin-donald 2.0.0
File	Interpreter	ABI	Platform	Reset
muffin_donald-2.0.0-py3-none-any.whl 4.4 kB Jun 25, 2026	Python 3	none	any	Details

Total release size: 8.5 kB

Release files / muffin_donald-2.0.0.tar.gz

Download URL	muffin_donald-2.0.0.tar.gz
Size	4.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`2769edb5150d32ab0915a1822f01a08708a8f456a19ef1c5c72adf8fa0dd7067`
BLAKE2b-256 checksum How to use checksums	`144cadf5019ae835967b4a120a467598b98d8b32d61dea700901267460b80b86`
Upload date	Jun 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / muffin_donald-2.0.0-py3-none-any.whl

Download URL	muffin_donald-2.0.0-py3-none-any.whl
Size	4.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`990730ec09fbad94e187eb87a43d64b1a46a13525a123d91d19cd232bdbf5ea6`
BLAKE2b-256 checksum How to use checksums	`d443098d11ffb2a8d028078e1425ff6afbf240ed863e32241d96c0d287e9e32d`
Upload date	Jun 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`