shadow-task 0.1.0

distributed background task system for python functions

Shadow is a distributed background task system for Python functions with a focus on the scheduling of future work as seamlessly and efficiently as immediate work.

At a glance

from datetime import datetime, timedelta, timezone

from shadows import Shadow


async def greet(name: str, greeting="Hello") -> None:
    print(f"{greeting}, {name} at {datetime.now()}!")


async with Shadow() as shadows:
    await shadows.add(greet)("Jane")

    now = datetime.now(timezone.utc)
    soon = now + timedelta(seconds=3)
    await shadows.add(greet, when=soon)("John", greeting="Howdy")

from shadows import Shadow, Worker

async with Shadow() as shadows:
    async with Worker(shadows) as worker:
        await worker.run_until_finished()

Hello, Jane at 2025-03-05 13:58:21.552644!
Howdy, John at 2025-03-05 13:58:24.550773!

Check out our docs for more details, examples, and the API reference.

Why shadows?

⚡️ Snappy one-way background task processing without any bloat

📅 Schedule immediate or future work seamlessly with the same interface

⏭️ Skip problematic tasks or parameters without redeploying

🌊 Purpose-built for Redis streams

🧩 Fully type-complete and type-aware for your background task functions

💉 Dependency injection like FastAPI, Typer, and FastMCP for reusable resources

Installing shadows

Shadow is available on PyPI under the package name shadow-task. It targets Python 3.12 or above.

With uv:

uv pip install shadows

or

uv add shadows

With pip:

pip install shadows

Shadow requires a Redis server with Streams support (which was introduced in Redis 5.0.0). Shadow is tested with Redis 6 and 7.

Hacking on shadows

We use uv for project management, so getting set up should be as simple as cloning the repo and running:

uv sync

The to run the test suite:

pytest

We aim to maintain 100% test coverage, which is required for all PRs to shadows. We believe that shadows should stay small, simple, understandable, and reliable, and that begins with testing all the dusty branches and corners. This will give us the confidence to upgrade dependencies quickly and to adapt to new versions of Redis over time.