hawkapi-celery 0.1.0__py3-none-any.whl

hawkapi_celery/__init__.py

@@ -0,0 +1,54 @@
+"""hawkapi-celery — Celery integration for HawkAPI.
+
+Async tasks, beat scheduler, broker/worker healthchecks, request-context
+propagation between HTTP handlers and Celery workers, and eager-mode fixtures
+for testing.
+"""
+
+from __future__ import annotations
+
+from ._app import CeleryConfig, create_celery
+from ._beat import Periodic, add_periodic, crontab, every, every_seconds
+from ._context import (
+    attach_context_signals,
+    bind_context,
+    current_context,
+    reset_context,
+    set_context,
+)
+from ._health import HealthReport, check_broker, check_workers, healthcheck
+from ._plugin import get_celery, get_task_result, init_celery, resolve_celery
+from ._tasks import compute_backoff, task
+from ._testing import CapturedTask, TaskRecorder, eager_mode, record_tasks
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CapturedTask",
+    "CeleryConfig",
+    "HealthReport",
+    "Periodic",
+    "TaskRecorder",
+    "__version__",
+    "add_periodic",
+    "attach_context_signals",
+    "bind_context",
+    "check_broker",
+    "check_workers",
+    "compute_backoff",
+    "create_celery",
+    "crontab",
+    "current_context",
+    "eager_mode",
+    "every",
+    "every_seconds",
+    "get_celery",
+    "get_task_result",
+    "healthcheck",
+    "init_celery",
+    "record_tasks",
+    "reset_context",
+    "resolve_celery",
+    "set_context",
+    "task",
+]

hawkapi_celery/_app.py

@@ -0,0 +1,62 @@
+"""Celery app construction + sensible defaults."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from celery import Celery
+
+
+@dataclass(slots=True)
+class CeleryConfig:
+    broker_url: str = "redis://localhost:6379/0"
+    result_backend: str = "redis://localhost:6379/0"
+    task_serializer: str = "json"
+    result_serializer: str = "json"
+    accept_content: list[str] = field(default_factory=lambda: ["json"])
+    timezone: str = "UTC"
+    enable_utc: bool = True
+    task_track_started: bool = True
+    task_time_limit: int = 600
+    task_soft_time_limit: int = 540
+    worker_prefetch_multiplier: int = 1
+    worker_max_tasks_per_child: int = 1000
+    task_default_queue: str = "default"
+    task_default_priority: int = 5
+    task_always_eager: bool = False
+    task_eager_propagates: bool = False
+    beat_schedule: dict[str, Any] = field(default_factory=dict)
+    include: list[str] = field(default_factory=list)
+    extra_kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+def create_celery(name: str = "hawkapi", *, config: CeleryConfig | None = None) -> Celery:
+    """Build a Celery app from :class:`CeleryConfig` with sensible defaults."""
+    config = config or CeleryConfig()
+    app = Celery(name, broker=config.broker_url, backend=config.result_backend)
+    app.conf.update(
+        broker_url=config.broker_url,
+        result_backend=config.result_backend,
+        task_serializer=config.task_serializer,
+        result_serializer=config.result_serializer,
+        accept_content=list(config.accept_content),
+        timezone=config.timezone,
+        enable_utc=config.enable_utc,
+        task_track_started=config.task_track_started,
+        task_time_limit=config.task_time_limit,
+        task_soft_time_limit=config.task_soft_time_limit,
+        worker_prefetch_multiplier=config.worker_prefetch_multiplier,
+        worker_max_tasks_per_child=config.worker_max_tasks_per_child,
+        task_default_queue=config.task_default_queue,
+        task_default_priority=config.task_default_priority,
+        task_always_eager=config.task_always_eager,
+        task_eager_propagates=config.task_eager_propagates,
+        beat_schedule=dict(config.beat_schedule),
+        include=list(config.include),
+        **config.extra_kwargs,
+    )
+    return app
+
+
+__all__ = ["CeleryConfig", "create_celery"]

hawkapi_celery/_beat.py

@@ -0,0 +1,49 @@
+"""Periodic-task helpers — declarative schedule entries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any
+
+from celery import Celery
+from celery.schedules import crontab
+
+
+@dataclass(slots=True)
+class Periodic:
+    """One periodic-task entry. Use :func:`add_periodic` to register."""
+
+    task: str
+    schedule: float | timedelta | crontab
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        entry: dict[str, Any] = {"task": self.task, "schedule": self.schedule}
+        if self.args:
+            entry["args"] = list(self.args)
+        if self.kwargs:
+            entry["kwargs"] = dict(self.kwargs)
+        if self.options:
+            entry["options"] = dict(self.options)
+        return entry
+
+
+def add_periodic(celery_app: Celery, name: str, periodic: Periodic) -> None:
+    """Add ``periodic`` to the Celery beat schedule under ``name``."""
+    schedule: dict[str, Any] = dict(celery_app.conf.beat_schedule or {})
+    schedule[name] = periodic.to_dict()
+    celery_app.conf.beat_schedule = schedule
+
+
+def every_seconds(seconds: float) -> float:
+    return float(seconds)
+
+
+def every(timedelta_value: timedelta) -> timedelta:
+    return timedelta_value
+
+
+__all__ = ["Periodic", "add_periodic", "crontab", "every", "every_seconds"]

hawkapi_celery/_context.py

@@ -0,0 +1,106 @@
+"""Propagate request context (request_id, user_id, etc.) from HTTP handlers to Celery workers.
+
+Usage:
+
+.. code-block:: python
+
+    from hawkapi_celery import bind_context, attach_context_signals
+
+    attach_context_signals(celery_app)            # once, at startup
+
+    # In a handler:
+    with bind_context(request_id=request_id, user_id=user.id):
+        my_task.delay(...)
+
+The context dict is shipped in the task's ``headers["hawkapi_context"]`` and
+restored into a module-level :class:`ContextVar` on the worker side. Read it
+back inside the task with :func:`current_context`.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+from celery import Celery
+from celery.signals import before_task_publish, task_postrun, task_prerun
+
+_CONTEXT_VAR: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
+    "hawkapi_celery_context", default=None
+)
+_HEADER_KEY = "hawkapi_context"
+
+
+def current_context() -> dict[str, Any]:
+    """Return the active context dict (empty if unset)."""
+    return dict(_CONTEXT_VAR.get() or {})
+
+
+@contextmanager
+def bind_context(**values: Any) -> Generator[None, None, None]:
+    """Temporarily merge ``values`` into the active context."""
+    merged = {**(_CONTEXT_VAR.get() or {}), **values}
+    token = _CONTEXT_VAR.set(merged)
+    try:
+        yield
+    finally:
+        _CONTEXT_VAR.reset(token)
+
+
+def set_context(values: dict[str, Any]) -> contextvars.Token[dict[str, Any] | None]:
+    """Set the active context unconditionally and return a reset token."""
+    return _CONTEXT_VAR.set(dict(values))
+
+
+def reset_context(token: contextvars.Token[dict[str, Any] | None]) -> None:
+    _CONTEXT_VAR.reset(token)
+
+
+def attach_context_signals(celery_app: Celery) -> None:
+    """Wire the publisher → worker context propagation. Idempotent per app."""
+    flag = "_hawkapi_context_signals"
+    if getattr(celery_app, flag, False):
+        return
+    setattr(celery_app, flag, True)
+
+    @before_task_publish.connect(weak=False)
+    def _publish(headers: dict[str, Any] | None = None, **_: Any) -> None:
+        if headers is None:
+            return
+        ctx = _CONTEXT_VAR.get()
+        if ctx:
+            headers[_HEADER_KEY] = dict(ctx)
+
+    @task_prerun.connect(weak=False)
+    def _prerun(task: Any = None, **_: Any) -> None:
+        if task is None:
+            return
+        try:
+            headers = task.request.headers or {}
+        except AttributeError:
+            return
+        ctx = headers.get(_HEADER_KEY) if isinstance(headers, dict) else None
+        if isinstance(ctx, dict):
+            task.request._hawkapi_token = _CONTEXT_VAR.set(dict(ctx))
+
+    @task_postrun.connect(weak=False)
+    def _postrun(task: Any = None, **_: Any) -> None:
+        if task is None:
+            return
+        token = getattr(task.request, "_hawkapi_token", None)
+        if token is not None:
+            import contextlib
+
+            with contextlib.suppress(ValueError, LookupError):
+                _CONTEXT_VAR.reset(token)
+
+
+__all__ = [
+    "attach_context_signals",
+    "bind_context",
+    "current_context",
+    "reset_context",
+    "set_context",
+]

hawkapi_celery/_health.py

@@ -0,0 +1,56 @@
+"""Healthcheck helpers — broker ping + worker discovery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from celery import Celery
+
+
+@dataclass(slots=True)
+class HealthReport:
+    broker_ok: bool
+    workers_alive: int
+    workers: dict[str, Any] = field(default_factory=dict)
+    error: str = ""
+
+
+def check_broker(celery_app: Celery, *, timeout: float = 5.0) -> bool:
+    """Open a broker connection and verify it is reachable."""
+    try:
+        with celery_app.connection_for_read() as conn:  # type: ignore[attr-defined]
+            conn.ensure_connection(max_retries=1, interval_start=0, timeout=timeout)
+        return True
+    except Exception:
+        return False
+
+
+def check_workers(celery_app: Celery, *, timeout: float = 5.0) -> dict[str, Any]:
+    """Return a mapping of worker-name -> ping response. Empty dict if no workers."""
+    try:
+        replies = celery_app.control.ping(timeout=timeout)
+    except Exception:
+        return {}
+    result: dict[str, Any] = {}
+    for reply in replies or []:
+        for worker, payload in reply.items():
+            result[worker] = payload
+    return result
+
+
+def healthcheck(celery_app: Celery, *, timeout: float = 5.0) -> HealthReport:
+    """Combined broker + worker probe."""
+    try:
+        broker_ok = check_broker(celery_app, timeout=timeout)
+        workers = check_workers(celery_app, timeout=timeout) if broker_ok else {}
+        return HealthReport(
+            broker_ok=broker_ok,
+            workers_alive=len(workers),
+            workers=workers,
+        )
+    except Exception as exc:
+        return HealthReport(broker_ok=False, workers_alive=0, error=str(exc))
+
+
+__all__ = ["HealthReport", "check_broker", "check_workers", "healthcheck"]

hawkapi_celery/_plugin.py

@@ -0,0 +1,74 @@
+"""Plugin entry point + DI helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from celery import Celery
+from celery.result import AsyncResult
+from hawkapi import HTTPException, Request
+
+from ._app import CeleryConfig, create_celery
+from ._context import attach_context_signals
+
+
+class _StateNamespace:
+    celery: Any
+
+
+_ACTIVE_APPS: dict[int, Celery] = {}
+_LAST_APP: list[Celery | None] = [None]
+
+
+def init_celery(
+    app: Any,
+    *,
+    celery_app: Celery | None = None,
+    config: CeleryConfig | None = None,
+    name: str = "hawkapi",
+    propagate_context: bool = True,
+) -> Celery:
+    """Attach a Celery app to ``app.state.celery`` and register it for DI lookup.
+
+    Pass an existing ``celery_app=`` to wire up a Celery instance you built yourself;
+    otherwise pass a ``config=`` (or nothing for defaults) and we will build one for you.
+    """
+    if celery_app is None:
+        celery_app = create_celery(name, config=config or CeleryConfig())
+
+    if propagate_context:
+        attach_context_signals(celery_app)
+
+    if getattr(app, "state", None) is None:
+        app.state = _StateNamespace()
+    app.state.celery = celery_app
+    _ACTIVE_APPS[id(app)] = celery_app
+    _LAST_APP[0] = celery_app
+    return celery_app
+
+
+def resolve_celery(app: Any) -> Celery | None:
+    if app is None:
+        return _LAST_APP[0]
+    found = _ACTIVE_APPS.get(id(app))
+    if found is not None:
+        return found
+    state = getattr(app, "state", None)
+    if state is not None and hasattr(state, "celery"):
+        return state.celery  # type: ignore[no-any-return]
+    return _LAST_APP[0]
+
+
+def get_celery(request: Request) -> Celery:
+    found = resolve_celery(request.scope.get("app"))
+    if found is None:
+        raise HTTPException(500, detail="Celery not configured — call init_celery(app, ...) first")
+    return found
+
+
+def get_task_result(task_id: str, request: Request) -> AsyncResult:
+    """Resolve an ``AsyncResult`` for ``task_id`` against the configured Celery app."""
+    return AsyncResult(task_id, app=get_celery(request))
+
+
+__all__ = ["get_celery", "get_task_result", "init_celery", "resolve_celery"]

hawkapi_celery/_tasks.py

@@ -0,0 +1,93 @@
+"""Task decorators — sync, async-coroutine, and retry helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import random
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from celery import Celery
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def task(
+    celery_app: Celery,
+    *,
+    name: str | None = None,
+    queue: str | None = None,
+    bind: bool = False,
+    autoretry_for: tuple[type[BaseException], ...] = (),
+    retry_backoff: bool | int | float = False,
+    retry_backoff_max: int = 600,
+    retry_jitter: bool = True,
+    max_retries: int = 3,
+    **task_kwargs: Any,
+) -> Callable[[Callable[P, R]], Any]:
+    """Register ``fn`` as a Celery task with sensible retry defaults.
+
+    The wrapper auto-detects ``async def`` and runs the coroutine on a private
+    event loop for each invocation. For sync functions it forwards as-is.
+    """
+
+    def decorator(fn: Callable[P, R]) -> Any:
+        register_kwargs: dict[str, Any] = {
+            "name": name or f"{fn.__module__}.{fn.__qualname__}",
+            "queue": queue,
+            "bind": bind,
+            "autoretry_for": autoretry_for,
+            "retry_backoff": retry_backoff,
+            "retry_backoff_max": retry_backoff_max,
+            "retry_jitter": retry_jitter,
+            "max_retries": max_retries,
+            **task_kwargs,
+        }
+        register_kwargs = {k: v for k, v in register_kwargs.items() if v is not None}
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                return _run_coroutine(fn, *args, **kwargs)  # type: ignore[arg-type]
+
+            return celery_app.task(**register_kwargs)(wrapper)
+        return celery_app.task(**register_kwargs)(fn)
+
+    return decorator
+
+
+def _run_coroutine(coro_fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+    """Run ``coro_fn(*args, **kwargs)`` on a private event loop."""
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # Nested call — bail rather than block the outer loop.
+            raise RuntimeError("cannot run coroutine task inside an active event loop")
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        return loop.run_until_complete(coro_fn(*args, **kwargs))
+    finally:
+        loop.close()
+        asyncio.set_event_loop(None)
+
+
+def compute_backoff(
+    attempt: int, *, base: float = 1.0, cap: float = 60.0, jitter: bool = True
+) -> float:
+    """Compute exponential backoff with optional decorrelated jitter.
+
+    Useful when scheduling manual retries via ``task.retry(countdown=...)``.
+    """
+    delay = min(cap, base * (2 ** max(0, attempt - 1)))
+    if jitter:
+        delay = random.uniform(base, max(base, delay))  # noqa: S311 - not crypto
+    return delay
+
+
+__all__ = ["compute_backoff", "task"]

hawkapi_celery/_testing.py

@@ -0,0 +1,86 @@
+"""Test helpers — eager-mode and task capture."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any
+
+from celery import Celery
+from celery.signals import before_task_publish
+
+
+@dataclass(slots=True)
+class CapturedTask:
+    name: str
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, Any] = field(default_factory=dict)
+
+
+class TaskRecorder:
+    """Captures every task publish on a Celery app — useful in tests."""
+
+    def __init__(self) -> None:
+        self.captured: list[CapturedTask] = []
+
+    def __len__(self) -> int:
+        return len(self.captured)
+
+    def clear(self) -> None:
+        self.captured.clear()
+
+
+@contextmanager
+def record_tasks(celery_app: Celery) -> Generator[TaskRecorder, None, None]:
+    """Capture every task publish for the duration of the block."""
+    recorder = TaskRecorder()
+
+    def _capture(
+        sender: str | None = None,
+        body: Any = None,
+        headers: dict[str, Any] | None = None,
+        **_: Any,
+    ) -> None:
+        args: tuple[Any, ...] = ()
+        kwargs: dict[str, Any] = {}
+        if isinstance(body, tuple) and len(body) >= 2:
+            a, k = body[0], body[1]
+            if isinstance(a, (list, tuple)):
+                args = tuple(a)
+            if isinstance(k, dict):
+                kwargs = dict(k)
+        recorder.captured.append(
+            CapturedTask(
+                name=sender or "",
+                args=args,
+                kwargs=kwargs,
+                headers=dict(headers or {}),
+            )
+        )
+
+    before_task_publish.connect(_capture, weak=False, sender=None)
+    try:
+        yield recorder
+    finally:
+        before_task_publish.disconnect(_capture)
+        # Reference to celery_app keeps signature stable / lets us extend later.
+        _ = celery_app
+
+
+@contextmanager
+def eager_mode(celery_app: Celery, *, propagate: bool = True) -> Generator[Celery, None, None]:
+    """Run all tasks synchronously in-process — drop-in for tests."""
+    prev_always = celery_app.conf.task_always_eager
+    prev_prop = celery_app.conf.task_eager_propagates
+    celery_app.conf.task_always_eager = True
+    celery_app.conf.task_eager_propagates = propagate
+    try:
+        yield celery_app
+    finally:
+        celery_app.conf.task_always_eager = prev_always
+        celery_app.conf.task_eager_propagates = prev_prop
+
+
+__all__ = ["CapturedTask", "TaskRecorder", "eager_mode", "record_tasks"]

hawkapi_celery-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: hawkapi-celery
+Version: 0.1.0
+Summary: Celery integration for HawkAPI — async tasks, beat scheduler, context propagation, healthchecks, eager-mode fixtures
+Project-URL: Homepage, https://pypi.org/project/hawkapi-celery/
+Project-URL: Repository, https://github.com/ashimov/hawkapi-celery
+Project-URL: Issues, https://github.com/ashimov/hawkapi-celery/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: async,background,beat,celery,hawkapi,queue,tasks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Celery
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: celery>=5.4
+Requires-Dist: hawkapi>=0.1.7
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# hawkapi-celery
+
+Celery integration for [HawkAPI](https://github.com/ashimov/HawkAPI). Async tasks, beat scheduler, request-context propagation, broker/worker healthchecks, and eager-mode fixtures for tests.
+
+## Install
+
+```bash
+pip install hawkapi-celery
+pip install 'hawkapi-celery[redis]'         # adds redis client
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from celery import Celery
+from hawkapi_celery import (
+    CeleryConfig, bind_context, get_celery, init_celery, task,
+)
+
+
+celery_app: Celery  # populated below
+
+
+def make_app() -> HawkAPI:
+    app = HawkAPI()
+    global celery_app
+    celery_app = init_celery(
+        app,
+        config=CeleryConfig(
+            broker_url="redis://localhost:6379/0",
+            result_backend="redis://localhost:6379/0",
+        ),
+    )
+
+
+    @task(celery_app, name="emails.send")
+    async def send_email(to: str, subject: str, body: str) -> None:
+        ...  # any await-able send logic
+
+
+    @app.post("/notify")
+    async def notify(email: str, c: Celery = Depends(get_celery)):
+        with bind_context(request_id="…"):
+            send_email.delay(email, "Welcome", "Hello!")
+        return {"ok": True}
+
+    return app
+```
+
+## Tasks
+
+```python
+from hawkapi_celery import task
+
+@task(celery_app, name="myapp.work", queue="default",
+      autoretry_for=(ConnectionError,), retry_backoff=True, max_retries=5)
+async def work(x: int) -> int:        # async def — runs on a private event loop
+    ...
+    return x * 2
+
+
+@task(celery_app, bind=True)
+def slow_work(self, payload):          # sync — bound `self` for retry handling
+    try:
+        do_thing(payload)
+    except TransientError as exc:
+        raise self.retry(exc=exc, countdown=compute_backoff(self.request.retries))
+```
+
+## Beat (periodic tasks)
+
+```python
+from datetime import timedelta
+from hawkapi_celery import Periodic, add_periodic, crontab, every
+
+add_periodic(celery_app, "cleanup",
+             Periodic(task="myapp.cleanup", schedule=every(timedelta(hours=1))))
+
+add_periodic(celery_app, "nightly_report",
+             Periodic(task="myapp.report", schedule=crontab(hour=2, minute=0),
+                      kwargs={"date": "yesterday"}))
+```
+
+## Context propagation
+
+`bind_context()` carries a dict from the HTTP handler to the worker process via the task headers. Inside the task call `current_context()` to read it back.
+
+```python
+from hawkapi_celery import bind_context, current_context
+
+@task(celery_app, name="log.event")
+def log_event(payload: dict) -> None:
+    ctx = current_context()                  # {"request_id": "…", "user_id": "…"}
+    log.info("event", **ctx, **payload)
+
+
+@app.post("/event")
+async def post_event(p: Payload):
+    with bind_context(request_id=p.request_id, user_id=p.user_id):
+        log_event.delay(p.model_dump())
+```
+
+Wired automatically by `init_celery(..., propagate_context=True)` (default).
+
+## Healthchecks
+
+```python
+from hawkapi_celery import healthcheck
+
+
+@app.get("/healthz")
+async def healthz():
+    report = healthcheck(celery_app, timeout=2.0)
+    return {
+        "broker": report.broker_ok,
+        "workers_alive": report.workers_alive,
+        "workers": list(report.workers),
+    }
+```
+
+## Testing
+
+```python
+from hawkapi_celery import eager_mode, record_tasks
+
+
+def test_signup_enqueues_welcome_email(client, celery_app):
+    with record_tasks(celery_app) as recorder:
+        client.post("/signup", json={"email": "x@y.z"})
+    assert any(t.name == "emails.send" for t in recorder.captured)
+
+
+def test_signup_runs_welcome_email_inline(client, celery_app):
+    with eager_mode(celery_app):
+        client.post("/signup", json={"email": "x@y.z"})
+    # All tasks executed synchronously in-process — assert their side-effects directly.
+```
+
+## CeleryConfig
+
+```python
+CeleryConfig(
+    broker_url="redis://localhost:6379/0",
+    result_backend="redis://localhost:6379/0",
+    task_serializer="json",
+    timezone="UTC",
+    task_time_limit=600,
+    task_soft_time_limit=540,
+    worker_prefetch_multiplier=1,
+    worker_max_tasks_per_child=1000,
+    task_default_queue="default",
+    extra_kwargs={...},          # forwarded to celery.conf.update
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-celery.git
+cd hawkapi-celery
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_celery-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+hawkapi_celery/__init__.py,sha256=gtBjDMMZwVP2gxCMk_Jiz9fLKABRaXiz7EpWZ98rfrc,1350
+hawkapi_celery/_app.py,sha256=T7K6p7_1LraqtIHqvZ3e9ECjSCm0w1jcKsGY4hVhmG8,2371
+hawkapi_celery/_beat.py,sha256=pZK7CCMLkvqDCiBWLSrYXt7_KyyDnOWzx1mBLN-TnlY,1469
+hawkapi_celery/_context.py,sha256=R-Q4NjUZP8LgKC7oDYbmT4xlKRPA6evsXPCNK58K6Go,3224
+hawkapi_celery/_health.py,sha256=BCfXICrUWjXKkaKJH7J5-ve5bc6ABJG6AbcqVZCou8s,1777
+hawkapi_celery/_plugin.py,sha256=7RILxG0zwubXbxiN8QBnA5bBHvYohhvzJ18rFKCJxSY,2153
+hawkapi_celery/_tasks.py,sha256=kLDt2TLNGb8HacjZ5GQ1uHB_THpZluVtbsVwZob1CG4,2962
+hawkapi_celery/_testing.py,sha256=77IrAUw5UgCPaqT8KfgRpgaW8X-6RAGzEZji_dQcZwQ,2586
+hawkapi_celery/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hawkapi_celery-0.1.0.dist-info/METADATA,sha256=7u7B8Zb-M9uYeOueZ-A1oHbBBjBUuyc6dRniUcVw5Qo,7066
+hawkapi_celery-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hawkapi_celery-0.1.0.dist-info/licenses/LICENSE,sha256=_RpjhvsfLqqeG_gv2cRatjIxCTGXTpXhKU9jqLZXYa4,1077
+hawkapi_celery-0.1.0.dist-info/RECORD,,

hawkapi_celery-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hawkapi_celery-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HawkAPI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.