pydocket 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

docket/__main__.py

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

docket/annotations.py

@@ -34,7 +34,29 @@ class Annotation(abc.ABC):
 
 
 class Logged(Annotation):
-    """Instructs docket to include arguments to this parameter in the log."""
+    """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
 

docket/cli.py

@@ -259,11 +259,20 @@ def worker(
             help="Exit after the current docket is finished",
         ),
     ] = False,
+    healthcheck_port: Annotated[
+        int | None,
+        typer.Option(
+            "--healthcheck-port",
+            help="The port to serve a healthcheck on",
+            envvar="DOCKET_WORKER_HEALTHCHECK_PORT",
+        ),
+    ] = None,
     metrics_port: Annotated[
         int | None,
         typer.Option(
             "--metrics-port",
             help="The port to serve Prometheus metrics on",
+            envvar="DOCKET_WORKER_METRICS_PORT",
         ),
     ] = None,
 ) -> None:
@@ -279,6 +288,7 @@ def worker(
             scheduling_resolution=scheduling_resolution,
             schedule_automatic_tasks=schedule_automatic_tasks,
             until_finished=until_finished,
+            healthcheck_port=healthcheck_port,
             metrics_port=metrics_port,
             tasks=tasks,
         )

docket/dependencies.py

@@ -49,6 +49,16 @@ class _CurrentWorker(Dependency):
 
 
 def CurrentWorker() -> "Worker":
+    """A dependency to access the current Worker.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(worker: Worker = CurrentWorker()) -> None:
+        assert isinstance(worker, Worker)
+    ```
+    """
     return cast("Worker", _CurrentWorker())
 
 
@@ -58,6 +68,16 @@ class _CurrentDocket(Dependency):
 
 
 def CurrentDocket() -> Docket:
+    """A dependency to access the current Docket.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(docket: Docket = CurrentDocket()) -> None:
+        assert isinstance(docket, Docket)
+    ```
+    """
     return cast(Docket, _CurrentDocket())
 
 
@@ -67,6 +87,16 @@ class _CurrentExecution(Dependency):
 
 
 def CurrentExecution() -> Execution:
+    """A dependency to access the current Execution.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(execution: Execution = CurrentExecution()) -> None:
+        assert isinstance(execution, Execution)
+    ```
+    """
     return cast(Execution, _CurrentExecution())
 
 
@@ -76,23 +106,56 @@ class _TaskKey(Dependency):
 
 
 def TaskKey() -> str:
+    """A dependency to access the key of the currently executing task.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(key: str = TaskKey()) -> None:
+        assert isinstance(key, str)
+    ```
+    """
     return cast(str, _TaskKey())
 
 
 class _TaskArgument(Dependency):
     parameter: str | None
+    optional: bool
 
-    def __init__(self, parameter: str | None = None) -> None:
+    def __init__(self, parameter: str | None = None, optional: bool = False) -> None:
         self.parameter = parameter
+        self.optional = optional
 
     async def __aenter__(self) -> Any:
         assert self.parameter is not None
         execution = self.execution.get()
-        return execution.get_argument(self.parameter)
+        try:
+            return execution.get_argument(self.parameter)
+        except KeyError:
+            if self.optional:
+                return None
+            raise
+
+
+def TaskArgument(parameter: str | None = None, optional: bool = False) -> Any:
+    """A dependency to access a argument of the currently executing task.  This is
+    often useful in dependency functions so they can access the arguments of the
+    task they are injected into.
+
+    Example:
 
+    ```python
+    async def customer_name(customer_id: int = TaskArgument()) -> str:
+        ...look up the customer's name by ID...
+        return "John Doe"
 
-def TaskArgument(parameter: str | None = None) -> Any:
-    return cast(Any, _TaskArgument(parameter))
+    @task
+    async def greet_customer(customer_id: int, name: str = Depends(customer_name)) -> None:
+        print(f"Hello, {name}!")
+    ```
+    """
+    return cast(Any, _TaskArgument(parameter, optional))
 
 
 class _TaskLogger(Dependency):
@@ -110,15 +173,45 @@ class _TaskLogger(Dependency):
 
 
 def TaskLogger() -> logging.LoggerAdapter[logging.Logger]:
+    """A dependency to access a logger for the currently executing task.  The logger
+    will automatically inject contextual information such as the worker and docket
+    name, the task key, and the current execution attempt number.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(logger: LoggerAdapter[Logger] = TaskLogger()) -> None:
+        logger.info("Hello, world!")
+    ```
+    """
     return cast(logging.LoggerAdapter[logging.Logger], _TaskLogger())
 
 
 class Retry(Dependency):
+    """Configures linear retries for a task.  You can specify the total number of
+    attempts (or `None` to retry indefinitely), and the delay between attempts.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(retry: Retry = Retry(attempts=3)) -> None:
+        ...
+    ```
+    """
+
     single: bool = True
 
     def __init__(
         self, attempts: int | None = 1, delay: timedelta = timedelta(0)
     ) -> None:
+        """
+        Args:
+            attempts: The total number of attempts to make.  If `None`, the task will
+                be retried indefinitely.
+            delay: The delay between attempts.
+        """
         self.attempts = attempts
         self.delay = delay
         self.attempt = 1
@@ -131,14 +224,32 @@ class Retry(Dependency):
 
 
 class ExponentialRetry(Retry):
-    attempts: int
+    """Configures exponential retries for a task.  You can specify the total number
+    of attempts (or `None` to retry indefinitely), and the minimum and maximum delays
+    between attempts.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(retry: ExponentialRetry = ExponentialRetry(attempts=3)) -> None:
+        ...
+    ```
+    """
 
     def __init__(
         self,
-        attempts: int = 1,
+        attempts: int | None = 1,
         minimum_delay: timedelta = timedelta(seconds=1),
         maximum_delay: timedelta = timedelta(seconds=64),
     ) -> None:
+        """
+        Args:
+            attempts: The total number of attempts to make.  If `None`, the task will
+                be retried indefinitely.
+            minimum_delay: The minimum delay between attempts.
+            maximum_delay: The maximum delay between attempts.
+        """
         super().__init__(attempts=attempts, delay=minimum_delay)
         self.minimum_delay = minimum_delay
         self.maximum_delay = maximum_delay
@@ -166,6 +277,19 @@ class ExponentialRetry(Retry):
 
 
 class Perpetual(Dependency):
+    """Declare a task that should be run perpetually.  Perpetual tasks are automatically
+    rescheduled for the future after they finish (whether they succeed or fail).  A
+    perpetual task can be scheduled at worker startup with the `automatic=True`.
+
+    Example:
+
+    ```python
+    @task
+    async def my_task(perpetual: Perpetual = Perpetual()) -> None:
+        ...
+    ```
+    """
+
     single = True
 
     every: timedelta
@@ -181,8 +305,7 @@ class Perpetual(Dependency):
         every: timedelta = timedelta(0),
         automatic: bool = False,
     ) -> None:
-        """Declare a task that should be run perpetually.
-
+        """
         Args:
             every: The target interval between task executions.
             automatic: If set, this task will be automatically scheduled during worker
@@ -210,13 +333,29 @@ class Perpetual(Dependency):
 
 
 class Timeout(Dependency):
-    single = True
+    """Configures a timeout for a task.  You can specify the base timeout, and the
+    task will be cancelled if it exceeds this duration.  The timeout may be extended
+    within the context of a single running task.
 
-    base: timedelta
+    Example:
+
+    ```python
+    @task
+    async def my_task(timeout: Timeout = Timeout(timedelta(seconds=10))) -> None:
+        ...
+    ```
+    """
 
+    single: bool = True
+
+    base: timedelta
     _deadline: float
 
     def __init__(self, base: timedelta) -> None:
+        """
+        Args:
+            base: The base timeout duration.
+        """
         self.base = base
 
     async def __aenter__(self) -> "Timeout":
@@ -231,9 +370,16 @@ class Timeout(Dependency):
         return time.monotonic() >= self._deadline
 
     def remaining(self) -> timedelta:
+        """Get the remaining time until the timeout expires."""
         return timedelta(seconds=self._deadline - time.monotonic())
 
     def extend(self, by: timedelta | None = None) -> None:
+        """Extend the timeout by a given duration.  If no duration is provided, the
+        base timeout will be used.
+
+        Args:
+            by: The duration to extend the timeout by.
+        """
         if by is None:
             by = self.base
         self._deadline += by.total_seconds()
@@ -321,6 +467,23 @@ class _Depends(Dependency, Generic[R]):
 
 
 def Depends(dependency: DependencyFunction[R]) -> R:
+    """Include a user-defined function as a dependency.  Dependencies may either return
+    a value or an async context manager.  If it returns a context manager, the
+    dependency will be entered and exited around the task, giving an opportunity to
+    control the lifetime of a resource, like a database connection.
+
+    Example:
+
+    ```python
+
+    async def my_dependency() -> str:
+        return "Hello, world!"
+
+    @task async def my_task(dependency: str = Depends(my_dependency)) -> None:
+        print(dependency)
+
+    ```
+    """
     return cast(R, _Depends(dependency))
 
 

docket/docket.py

@@ -23,12 +23,12 @@ from typing import (
     cast,
     overload,
 )
-from uuid import uuid4
 
 import redis.exceptions
 from opentelemetry import propagate, trace
 from redis.asyncio import ConnectionPool, Redis
 from redis.asyncio.client import Pipeline
+from uuid_extensions import uuid7
 
 from .execution import (
     Execution,
@@ -112,6 +112,20 @@ class DocketSnapshot:
 
 
 class Docket:
+    """A Docket represents a collection of tasks that may be scheduled for later
+    execution.  With a Docket, you can add, replace, and cancel tasks.
+    Example:
+
+    ```python
+    @task
+    async def my_task(greeting: str, recipient: str) -> None:
+        print(f"{greeting}, {recipient}!")
+
+    async with Docket() as docket:
+        docket.add(my_task)("Hello", recipient="world")
+    ```
+    """
+
     tasks: dict[str, TaskFunction]
     strike_list: StrikeList
 
@@ -199,6 +213,11 @@ class Docket:
             await asyncio.shield(r.__aexit__(None, None, None))
 
     def register(self, function: TaskFunction) -> None:
+        """Register a task with the Docket.
+
+        Args:
+            function: The task to register.
+        """
         from .dependencies import validate_dependencies
 
         validate_dependencies(function)
@@ -229,7 +248,14 @@ class Docket:
         function: Callable[P, Awaitable[R]],
         when: datetime | None = None,
         key: str | None = None,
-    ) -> Callable[P, Awaitable[Execution]]: ...  # pragma: no cover
+    ) -> Callable[P, Awaitable[Execution]]:
+        """Add a task to the Docket.
+
+        Args:
+            function: The task function to add.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
 
     @overload
     def add(
@@ -237,7 +263,14 @@ class Docket:
         function: str,
         when: datetime | None = None,
         key: str | None = None,
-    ) -> Callable[..., Awaitable[Execution]]: ...  # pragma: no cover
+    ) -> Callable[..., Awaitable[Execution]]:
+        """Add a task to the Docket.
+
+        Args:
+            function: The name of a task to add.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
 
     def add(
         self,
@@ -245,6 +278,13 @@ class Docket:
         when: datetime | None = None,
         key: str | None = None,
     ) -> Callable[..., Awaitable[Execution]]:
+        """Add a task to the Docket.
+
+        Args:
+            function: The task to add.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
         if isinstance(function, str):
             function = self.tasks[function]
         else:
@@ -254,7 +294,7 @@ class Docket:
             when = datetime.now(timezone.utc)
 
         if key is None:
-            key = f"{function.__name__}:{uuid4()}"
+            key = str(uuid7())
 
         async def scheduler(*args: P.args, **kwargs: P.kwargs) -> Execution:
             execution = Execution(function, args, kwargs, when, key, attempt=1)
@@ -277,7 +317,14 @@ class Docket:
         function: Callable[P, Awaitable[R]],
         when: datetime,
         key: str,
-    ) -> Callable[P, Awaitable[Execution]]: ...  # pragma: no cover
+    ) -> Callable[P, Awaitable[Execution]]:
+        """Replace a previously scheduled task on the Docket.
+
+        Args:
+            function: The task function to replace.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
 
     @overload
     def replace(
@@ -285,7 +332,14 @@ class Docket:
         function: str,
         when: datetime,
         key: str,
-    ) -> Callable[..., Awaitable[Execution]]: ...  # pragma: no cover
+    ) -> Callable[..., Awaitable[Execution]]:
+        """Replace a previously scheduled task on the Docket.
+
+        Args:
+            function: The name of a task to replace.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
 
     def replace(
         self,
@@ -293,6 +347,13 @@ class Docket:
         when: datetime,
         key: str,
     ) -> Callable[..., Awaitable[Execution]]:
+        """Replace a previously scheduled task on the Docket.
+
+        Args:
+            function: The task to replace.
+            when: The time to schedule the task.
+            key: The key to schedule the task under.
+        """
         if isinstance(function, str):
             function = self.tasks[function]
 
@@ -329,6 +390,11 @@ class Docket:
         TASKS_SCHEDULED.add(1, {**self.labels(), **execution.general_labels()})
 
     async def cancel(self, key: str) -> None:
+        """Cancel a previously scheduled task on the Docket.
+
+        Args:
+            key: The key of the task to cancel.
+        """
         with tracer.start_as_current_span(
             "docket.cancel",
             attributes={**self.labels(), "docket.key": key},
@@ -421,6 +487,14 @@ class Docket:
         operator: Operator | LiteralOperator = "==",
         value: Hashable | None = None,
     ) -> None:
+        """Strike a task from the Docket.
+
+        Args:
+            function: The task to strike.
+            parameter: The parameter to strike on.
+            operator: The operator to use.
+            value: The value to strike on.
+        """
         if not isinstance(function, (str, type(None))):
             function = function.__name__
 
@@ -436,6 +510,14 @@ class Docket:
         operator: Operator | LiteralOperator = "==",
         value: Hashable | None = None,
     ) -> None:
+        """Restore a previously stricken task to the Docket.
+
+        Args:
+            function: The task to restore.
+            parameter: The parameter to restore on.
+            operator: The operator to use.
+            value: The value to restore on.
+        """
         if not isinstance(function, (str, type(None))):
             function = function.__name__
 
@@ -501,6 +583,12 @@ class Docket:
                 await asyncio.sleep(1)
 
     async def snapshot(self) -> DocketSnapshot:
+        """Get a snapshot of the Docket, including which tasks are scheduled or currently
+        running, as well as which workers are active.
+
+        Returns:
+            A snapshot of the Docket.
+        """
         running: list[RunningExecution] = []
         future: list[Execution] = []
 
@@ -585,6 +673,11 @@ class Docket:
         return f"{self.name}:task-workers:{task_name}"
 
     async def workers(self) -> Collection[WorkerInfo]:
+        """Get a list of all workers that have sent heartbeats to the Docket.
+
+        Returns:
+            A list of all workers that have sent heartbeats to the Docket.
+        """
         workers: list[WorkerInfo] = []
 
         oldest = datetime.now(timezone.utc).timestamp() - (
@@ -615,8 +708,15 @@ class Docket:
         return workers
 
     async def task_workers(self, task_name: str) -> Collection[WorkerInfo]:
-        workers: list[WorkerInfo] = []
+        """Get a list of all workers that are able to execute a given task.
+
+        Args:
+            task_name: The name of the task.
 
+        Returns:
+            A list of all workers that are able to execute the given task.
+        """
+        workers: list[WorkerInfo] = []
         oldest = datetime.now(timezone.utc).timestamp() - (
             self.heartbeat_interval.total_seconds() * self.missed_heartbeats
         )

docket/execution.py

@@ -3,15 +3,23 @@ import enum
 import inspect
 import logging
 from datetime import datetime
-from typing import Any, Awaitable, Callable, Hashable, Literal, Mapping, Self, cast
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Hashable,
+    Literal,
+    Mapping,
+    Self,
+    cast,
+)
 
 import cloudpickle  # type: ignore[import]
-
-from opentelemetry import trace, propagate
 import opentelemetry.context
+from opentelemetry import propagate, trace
 
 from .annotations import Logged
-from docket.instrumentation import message_getter
+from .instrumentation import message_getter
 
 logger: logging.Logger = logging.getLogger(__name__)
 
@@ -117,6 +125,37 @@ class Execution:
         return [trace.Link(initiating_context)] if initiating_context.is_valid else []
 
 
+def compact_signature(signature: inspect.Signature) -> str:
+    from .dependencies import Dependency
+
+    parameters: list[str] = []
+    dependencies: int = 0
+
+    for parameter in signature.parameters.values():
+        if isinstance(parameter.default, Dependency):
+            dependencies += 1
+            continue
+
+        parameter_definition = parameter.name
+        if parameter.annotation is not parameter.empty:
+            annotation = parameter.annotation
+            if hasattr(annotation, "__origin__"):
+                annotation = annotation.__args__[0]
+
+            type_name = getattr(annotation, "__name__", str(annotation))
+            parameter_definition = f"{parameter.name}: {type_name}"
+
+        if parameter.default is not parameter.empty:
+            parameter_definition = f"{parameter_definition} = {parameter.default!r}"
+
+        parameters.append(parameter_definition)
+
+    if dependencies > 0:
+        parameters.append("...")
+
+    return ", ".join(parameters)
+
+
 class Operator(enum.StrEnum):
     EQUAL = "=="
     NOT_EQUAL = "!="

docket/instrumentation.py

@@ -1,5 +1,5 @@
-import threading
 from contextlib import contextmanager
+from threading import Thread
 from typing import Generator, cast
 
 from opentelemetry import metrics
@@ -145,6 +145,34 @@ message_getter: MessageGetter = MessageGetter()
 message_setter: MessageSetter = MessageSetter()
 
 
+@contextmanager
+def healthcheck_server(
+    host: str = "0.0.0.0", port: int | None = None
+) -> Generator[None, None, None]:
+    if port is None:
+        yield
+        return
+
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    class HealthcheckHandler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            self.send_response(200)
+            self.send_header("Content-type", "text/plain")
+            self.end_headers()
+            self.wfile.write(b"OK")
+
+        def log_message(self, format: str, *args: object) -> None:
+            # Suppress access logs from the webserver
+            pass
+
+    server = HTTPServer((host, port), HealthcheckHandler)
+    with server:
+        Thread(target=server.serve_forever, daemon=True).start()
+
+        yield
+
+
 @contextmanager
 def metrics_server(
     host: str = "0.0.0.0", port: int | None = None
@@ -173,8 +201,6 @@ def metrics_server(
         handler_class=_SilentHandler,
     )
     with server:
-        t = threading.Thread(target=server.serve_forever)
-        t.daemon = True
-        t.start()
+        Thread(target=server.serve_forever, daemon=True).start()
 
         yield