pydocket 0.15.3__py3-none-any.whl

docket/__init__.py

@@ -0,0 +1,55 @@
+"""
+docket - A distributed background task system for Python functions.
+
+docket focuses on scheduling future work as seamlessly and efficiently as immediate work.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("pydocket")
+
+from .agenda import Agenda
+from .annotations import Logged
+from .dependencies import (
+    ConcurrencyLimit,
+    CurrentDocket,
+    CurrentExecution,
+    CurrentWorker,
+    Depends,
+    ExponentialRetry,
+    Perpetual,
+    Progress,
+    Retry,
+    TaskArgument,
+    TaskKey,
+    TaskLogger,
+    Timeout,
+)
+from .docket import Docket
+from .execution import Execution, ExecutionState
+from .worker import Worker
+from . import testing
+
+__all__ = [
+    "__version__",
+    "Agenda",
+    "ConcurrencyLimit",
+    "CurrentDocket",
+    "CurrentExecution",
+    "CurrentWorker",
+    "Depends",
+    "Docket",
+    "Execution",
+    "ExecutionState",
+    "ExponentialRetry",
+    "Logged",
+    "Perpetual",
+    "Progress",
+    "Retry",
+    "TaskArgument",
+    "TaskKey",
+    "TaskLogger",
+    "testing",
+    "Timeout",
+    "Worker",
+]

docket/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app()

docket/_uuid7.py

@@ -0,0 +1,99 @@
+"""
+UUID v7 polyfill for Python < 3.14.
+
+On Python 3.14+, we use the stdlib implementation. On older versions,
+we use a simplified vendored implementation.
+
+The vendored code can be removed once Python 3.13 support is dropped.
+"""
+
+import os
+import sys
+import time
+import uuid
+from typing import Callable
+
+__all__ = ("uuid7",)
+
+
+# Vendored implementation for Python < 3.14
+# From Stephen Simmons' implementation (v0.1.0, 2021-12-27)
+# Original: https://github.com/stevesimmons/uuid7
+# Adapted to match stdlib signature (no parameters)
+
+# Module-level state for sequence counter (maintains monotonicity within same timestamp)
+_last = [0, 0, 0, 0]
+
+
+def _vendored_uuid7() -> uuid.UUID:
+    """
+    Generate a UUID v7 with embedded timestamp and sequence counter.
+
+    This implementation matches stdlib behavior by using a sequence counter
+    to guarantee monotonic ordering when multiple UUIDs are generated within
+    the same timestamp tick.
+
+    The 128 bits in the UUID are allocated as follows:
+    - 36 bits of whole seconds
+    - 24 bits of fractional seconds, giving approx 50ns resolution
+    - 14 bits of sequence counter (increments when time unchanged)
+    - 48 bits of randomness
+    plus, at locations defined by RFC4122, 4 bits for the
+    uuid version (0b0111) and 2 bits for the uuid variant (0b10).
+
+             0                   1                   2                   3
+             0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+            +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    t1      |                 unixts (secs since epoch)                     |
+            +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    t2/t3   |unixts |  frac secs (12 bits)  |  ver  |  frac secs (12 bits)  |
+            +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    t4/rand |var|       seq (14 bits)       |          rand (16 bits)       |
+            +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    rand    |                          rand (32 bits)                       |
+            +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    """
+    # Get current time in nanoseconds
+    ns = time.time_ns()
+
+    # Split into seconds and fractional parts for high-precision timestamp
+    # Treat the first 8 bytes of the uuid as a long (t1) and two ints
+    # (t2 and t3) holding 36 bits of whole seconds and 24 bits of
+    # fractional seconds.
+    # This gives a nominal 60ns resolution, comparable to the
+    # timestamp precision in Linux (~200ns) and Windows (100ns ticks).
+    sixteen_secs = 16_000_000_000
+    t1, rest1 = divmod(ns, sixteen_secs)
+    t2, rest2 = divmod(rest1 << 16, sixteen_secs)
+    t3, _ = divmod(rest2 << 12, sixteen_secs)
+    t3 |= 7 << 12  # Put uuid version in top 4 bits, which are 0 in t3
+
+    # The next two bytes are an int (t4) with two bits for
+    # the variant 2 and a 14 bit sequence counter which increments
+    # if the time is unchanged.
+    if t1 == _last[0] and t2 == _last[1] and t3 == _last[2]:
+        # Stop the seq counter wrapping past 0x3FFF.
+        # This won't happen in practice, but if it does,
+        # uuids after the 16383rd with that same timestamp
+        # will not longer be correctly ordered but
+        # are still unique due to the 6 random bytes.
+        if _last[3] < 0x3FFF:
+            _last[3] += 1
+    else:
+        _last[:] = (t1, t2, t3, 0)
+    t4 = (2 << 14) | _last[3]  # Put variant 0b10 in top two bits
+
+    # Six random bytes for the lower part of the uuid
+    rand = os.urandom(6)
+
+    # Build the UUID from components
+    r = int.from_bytes(rand, "big")
+    uuid_int = (t1 << 96) + (t2 << 80) + (t3 << 64) + (t4 << 48) + r
+    return uuid.UUID(int=uuid_int)
+
+
+# On Python 3.14+, use stdlib uuid7; otherwise use vendored implementation
+if sys.version_info >= (3, 14):
+    from uuid import uuid7
+else:
+    uuid7: Callable[[], uuid.UUID] = _vendored_uuid7

docket/agenda.py

@@ -0,0 +1,202 @@
+"""
+Agenda - A collection of tasks that can be scheduled together.
+
+The Agenda class provides a way to collect multiple tasks and then scatter them
+evenly over a time period to avoid overwhelming the system with immediate work.
+"""
+
+import random
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Iterator, ParamSpec, TypeVar, overload
+
+from ._uuid7 import uuid7
+
+from .docket import Docket
+from .execution import Execution, TaskFunction
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class Agenda:
+    """A collection of tasks to be scheduled together on a Docket.
+
+    The Agenda allows you to build up a collection of tasks with their arguments,
+    then schedule them all at once using various timing strategies like scattering.
+
+    Example:
+        >>> agenda = Agenda()
+        >>> agenda.add(process_item)(item1)
+        >>> agenda.add(process_item)(item2)
+        >>> agenda.add(send_email)(email)
+        >>> await agenda.scatter(docket, over=timedelta(minutes=50))
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty Agenda."""
+        self._tasks: list[
+            tuple[TaskFunction | str, tuple[Any, ...], dict[str, Any]]
+        ] = []
+
+    def __len__(self) -> int:
+        """Return the number of tasks in the agenda."""
+        return len(self._tasks)
+
+    def __iter__(
+        self,
+    ) -> Iterator[tuple[TaskFunction | str, tuple[Any, ...], dict[str, Any]]]:
+        """Iterate over tasks in the agenda."""
+        return iter(self._tasks)
+
+    @overload
+    def add(
+        self,
+        function: Callable[P, Awaitable[R]],
+    ) -> Callable[P, None]:
+        """Add a task function to the agenda.
+
+        Args:
+            function: The task function to add.
+
+        Returns:
+            A callable that accepts the task arguments.
+        """
+
+    @overload
+    def add(
+        self,
+        function: str,
+    ) -> Callable[..., None]:
+        """Add a task by name to the agenda.
+
+        Args:
+            function: The name of a registered task.
+
+        Returns:
+            A callable that accepts the task arguments.
+        """
+
+    def add(
+        self,
+        function: Callable[P, Awaitable[R]] | str,
+    ) -> Callable[..., None]:
+        """Add a task to the agenda.
+
+        Args:
+            function: The task function or name to add.
+
+        Returns:
+            A callable that accepts the task arguments and adds them to the agenda.
+        """
+
+        def scheduler(*args: Any, **kwargs: Any) -> None:
+            self._tasks.append((function, args, kwargs))
+
+        return scheduler
+
+    def clear(self) -> None:
+        """Clear all tasks from the agenda."""
+        self._tasks.clear()
+
+    async def scatter(
+        self,
+        docket: Docket,
+        over: timedelta,
+        start: datetime | None = None,
+        jitter: timedelta | None = None,
+    ) -> list[Execution]:
+        """Scatter the tasks in this agenda over a time period.
+
+        Tasks are distributed evenly across the specified time window,
+        optionally with random jitter to prevent thundering herd effects.
+
+        If an error occurs during scheduling, some tasks may have already been
+        scheduled successfully before the failure occurred.
+
+        Args:
+            docket: The Docket to schedule tasks on.
+            over: Time period to scatter tasks over (required).
+            start: When to start scattering from. Defaults to now.
+            jitter: Maximum random offset to add/subtract from each scheduled time.
+
+        Returns:
+            List of Execution objects for the scheduled tasks.
+
+        Raises:
+            KeyError: If any task name is not registered with the docket.
+            ValueError: If any task is stricken or 'over' is not positive.
+        """
+        if over.total_seconds() <= 0:
+            raise ValueError("'over' parameter must be a positive duration")
+
+        if not self._tasks:
+            return []
+
+        if start is None:
+            start = datetime.now(timezone.utc)
+
+        # Calculate even distribution over the time period
+        task_count = len(self._tasks)
+
+        if task_count == 1:
+            # Single task goes in the middle of the window
+            schedule_times = [start + over / 2]
+        else:
+            # Distribute tasks evenly across the window
+            # For n tasks, we want n points from start to start+over inclusive
+            interval = over / (task_count - 1)
+            schedule_times = [start + interval * i for i in range(task_count)]
+
+        # Apply jitter if specified
+        if jitter:
+            jittered_times: list[datetime] = []
+            for schedule_time in schedule_times:
+                # Random offset between -jitter and +jitter
+                offset = timedelta(
+                    seconds=random.uniform(
+                        -jitter.total_seconds(), jitter.total_seconds()
+                    )
+                )
+                # Ensure the jittered time doesn't go before start
+                jittered_time = max(schedule_time + offset, start)
+                jittered_times.append(jittered_time)
+            schedule_times = jittered_times
+
+        # Build all Execution objects first, validating as we go
+        executions: list[Execution] = []
+        for (task_func, args, kwargs), schedule_time in zip(
+            self._tasks, schedule_times
+        ):
+            # Resolve task function if given by name
+            if isinstance(task_func, str):
+                if task_func not in docket.tasks:
+                    raise KeyError(f"Task '{task_func}' is not registered")
+                resolved_func = docket.tasks[task_func]
+            else:
+                # Ensure task is registered
+                if task_func not in docket.tasks.values():
+                    docket.register(task_func)
+                resolved_func = task_func
+
+            # Create execution with unique key
+            key = str(uuid7())
+            execution = Execution(
+                docket=docket,
+                function=resolved_func,
+                args=args,
+                kwargs=kwargs,
+                key=key,
+                when=schedule_time,
+                attempt=1,
+            )
+            executions.append(execution)
+
+        # Schedule all tasks - if any fail, some tasks may have been scheduled
+        for execution in executions:
+            scheduler = docket.add(
+                execution.function, when=execution.when, key=execution.key
+            )
+            # Actually schedule the task - if this fails, earlier tasks remain scheduled
+            await scheduler(*execution.args, **execution.kwargs)
+
+        return executions

docket/annotations.py

@@ -0,0 +1,81 @@
+import abc
+import inspect
+from typing import Any, Iterable, Mapping
+
+from typing_extensions import Self
+
+from .instrumentation import CACHE_SIZE
+
+
+class Annotation(abc.ABC):
+    _cache: dict[tuple[type[Self], inspect.Signature], Mapping[str, Self]] = {}
+
+    @classmethod
+    def annotated_parameters(cls, signature: inspect.Signature) -> Mapping[str, Self]:
+        key = (cls, signature)
+        if key in cls._cache:
+            CACHE_SIZE.set(len(cls._cache), {"cache": "annotation"})
+            return cls._cache[key]
+
+        annotated: dict[str, Self] = {}
+
+        for param_name, param in signature.parameters.items():
+            if param.annotation == inspect.Parameter.empty:
+                continue
+
+            try:
+                metadata: Iterable[Any] = param.annotation.__metadata__
+            except AttributeError:
+                continue
+
+            for arg_type in metadata:
+                if isinstance(arg_type, cls):
+                    annotated[param_name] = arg_type
+                elif isinstance(arg_type, type) and issubclass(arg_type, cls):
+                    annotated[param_name] = arg_type()
+
+        cls._cache[key] = annotated
+        CACHE_SIZE.set(len(cls._cache), {"cache": "annotation"})
+        return annotated
+
+
+class Logged(Annotation):
+    """Instructs docket to include arguments to this parameter in the log.
+
+    If `length_only` is `True`, only the length of the argument will be included in
+    the log.
+
+    Example:
+
+    ```python
+    @task
+    def setup_new_customer(
+        customer_id: Annotated[int, Logged],
+        addresses: Annotated[list[Address], Logged(length_only=True)],
+        password: str,
+    ) -> None:
+        ...
+    ```
+
+    In the logs, you's see the task referenced as:
+
+    ```
+    setup_new_customer(customer_id=123, addresses[len 2], password=...)
+    ```
+    """
+
+    length_only: bool = False
+
+    def __init__(self, length_only: bool = False) -> None:
+        self.length_only = length_only
+
+    def format(self, argument: Any) -> str:
+        if self.length_only:
+            if isinstance(argument, (dict, set)):
+                return f"{{len {len(argument)}}}"
+            elif isinstance(argument, tuple):
+                return f"(len {len(argument)})"
+            elif hasattr(argument, "__len__"):
+                return f"[len {len(argument)}]"
+
+        return repr(argument)