Docket

Warnings

• breaking From version 0.18.0, Docket's internal dependency system was extracted into the `uncalled-for` library. While intended to be a transparent change for most users, deep or custom integrations with Docket's dependency resolution might require review.
  Fix: No direct code changes are typically required, as `uncalled-for` is installed as a dependency of `docket`. However, if experiencing issues, ensure `uncalled-for` is correctly installed and consult its documentation if custom dependency injection logic was previously implemented.
• gotcha Docket tasks are fundamentally asynchronous (`async def`) and rely on `asyncio`. Incorrectly mixing synchronous code in an async task, or blocking the event loop, can lead to performance issues or deadlocks.
  Fix: Ensure all I/O-bound or long-running operations within tasks are non-blocking or are offloaded to an executor (e.g., `loop.run_in_executor`) to prevent blocking the `asyncio` event loop. Always `await` asynchronous calls.
• gotcha When using `Cron` dependencies for task scheduling, ensure careful consideration of timezones. Default behavior might rely on the system's local timezone, which can lead to unexpected execution times in distributed or timezone-aware applications.
  Fix: Explicitly specify the timezone using the `tz` argument in the `Cron` constructor (e.g., `Cron('0 0 * * *', tz='America/New_York')`). Verify that your system's timezone settings are consistent across all Docket worker nodes.
• gotcha Using persistent backends (e.g., Redis, PostgreSQL) requires robust configuration and connection management to ensure tasks are reliably stored, retrieved, and processed across application restarts and distributed environments.
  Fix: Refer to the Docket documentation for the specific backend chosen. Implement proper connection pooling, error handling, and retry mechanisms for backend connections. Misconfigurations can lead to lost tasks or inconsistent state.

Install

• pip install docket Install latest version

Imports

• Docket

  from docket import Docket

• task

  from docket import task

• Cron

  from docket.dependencies import Cron

  Used for defining tasks that run on a cron schedule.

Quickstart

A minimal example demonstrating how to define an asynchronous task and run it using Docket. This example uses the default in-memory backend.

import asyncio
from docket import Docket, task

@task
async def greet_task(name: str):
    """An example asynchronous task."""
    print(f"Hello, {name}!")
    return f"Greeted {name}"

async def main():
    # Initialize Docket. In a real application, you might configure a backend like Redis.
    docket = Docket()

    # Add the task to be run. This queues it for execution.
    await docket.add(greet_task, name="World")
    print("Task added. Running Docket...")

    # Run Docket. In a long-running service, this would be awaited indefinitely.
    # For a quickstart, we'll run it briefly to allow the task to execute.
    # For simplicity, we'll assume the task completes quickly.
    try:
        await asyncio.wait_for(docket.run(), timeout=5) # Run for max 5 seconds
    except asyncio.TimeoutError:
        print("Docket run timed out after 5 seconds.")

if __name__ == "__main__":
    asyncio.run(main())