pydocket 0.6.3__py3-none-any.whl → 0.7.0__py3-none-any.whl

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

@@ -3,7 +3,7 @@ import logging
 import time
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
-from datetime import timedelta
+from datetime import datetime, timedelta, timezone
 from types import TracebackType
 from typing import (
     TYPE_CHECKING,
@@ -14,6 +14,7 @@ from typing import (
     Callable,
     Counter,
     Generic,
+    NoReturn,
     TypeVar,
     cast,
 )
@@ -49,6 +50,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 +69,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 +88,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,6 +107,16 @@ 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())
 
 
@@ -99,6 +140,22 @@ class _TaskArgument(Dependency):
 
 
 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"
+
+    @task
+    async def greet_customer(customer_id: int, name: str = Depends(customer_name)) -> None:
+        print(f"Hello, {name}!")
+    ```
+    """
     return cast(Any, _TaskArgument(parameter, optional))
 
 
@@ -117,15 +174,49 @@ 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 ForcedRetry(Exception):
+    """Raised when a task requests a retry via `in_` or `at`"""
+
+
 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
@@ -136,18 +227,46 @@ class Retry(Dependency):
         retry.attempt = execution.attempt
         return retry
 
+    def at(self, when: datetime) -> NoReturn:
+        now = datetime.now(timezone.utc)
+        diff = when - now
+        diff = diff if diff.total_seconds() >= 0 else timedelta(0)
+
+        self.in_(diff)
+
+    def in_(self, when: timedelta) -> NoReturn:
+        self.delay: timedelta = when
+        raise ForcedRetry()
+
 
 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
 
     async def __aenter__(self) -> "ExponentialRetry":
@@ -155,14 +274,14 @@ class ExponentialRetry(Retry):
 
         retry = ExponentialRetry(
             attempts=self.attempts,
-            minimum_delay=self.minimum_delay,
+            minimum_delay=self.delay,
             maximum_delay=self.maximum_delay,
         )
         retry.attempt = execution.attempt
 
         if execution.attempt > 1:
             backoff_factor = 2 ** (execution.attempt - 1)
-            calculated_delay = self.minimum_delay * backoff_factor
+            calculated_delay = self.delay * backoff_factor
 
             if calculated_delay > self.maximum_delay:
                 retry.delay = self.maximum_delay
@@ -173,6 +292,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
@@ -188,8 +320,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
@@ -217,13 +348,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":
@@ -238,9 +385,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()
@@ -328,6 +482,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

@@ -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:
@@ -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/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

docket/worker.py

@@ -51,6 +51,7 @@ from .instrumentation import (
     TASKS_STARTED,
     TASKS_STRICKEN,
     TASKS_SUCCEEDED,
+    healthcheck_server,
     metrics_server,
 )
 
@@ -65,6 +66,18 @@ class _stream_due_tasks(Protocol):
 
 
 class Worker:
+    """A Worker executes tasks on a Docket.  You may run as many workers as you like
+    to work a single Docket.
+
+    Example:
+
+    ```python
+    async with Docket() as docket:
+        async with Worker(docket) as worker:
+            await worker.run_forever()
+    ```
+    """
+
     docket: Docket
     name: str
     concurrency: int
@@ -140,10 +153,14 @@ class Worker:
         scheduling_resolution: timedelta = timedelta(milliseconds=250),
         schedule_automatic_tasks: bool = True,
         until_finished: bool = False,
+        healthcheck_port: int | None = None,
         metrics_port: int | None = None,
         tasks: list[str] = ["docket.tasks:standard_tasks"],
     ) -> None:
-        with metrics_server(port=metrics_port):
+        with (
+            healthcheck_server(port=healthcheck_port),
+            metrics_server(port=metrics_port),
+        ):
             async with Docket(name=docket_name, url=url) as docket:
                 for task_path in tasks:
                     docket.register_collection(task_path)

pydocket-0.7.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pydocket
+Version: 0.7.0
+Summary: A distributed background task system for Python functions
+Project-URL: Homepage, https://github.com/chrisguidry/docket
+Project-URL: Bug Tracker, https://github.com/chrisguidry/docket/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License: # Released under MIT License
+        
+        Copyright (c) 2025 Chris Guidry.
+        
+        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
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: opentelemetry-api>=1.30.0
+Requires-Dist: opentelemetry-exporter-prometheus>=0.51b0
+Requires-Dist: prometheus-client>=0.21.1
+Requires-Dist: python-json-logger>=3.2.1
+Requires-Dist: redis>=4.6
+Requires-Dist: rich>=13.9.4
+Requires-Dist: typer>=0.15.1
+Requires-Dist: uuid7>=0.1.0
+Description-Content-Type: text/markdown
+
+Docket 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.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pydocket)](https://pypi.org/project/pydocket/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydocket)](https://pypi.org/project/pydocket/)
+[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions/workflows/ci.yml)
+[![Codecov](https://img.shields.io/codecov/c/github/chrisguidry/docket)](https://app.codecov.io/gh/chrisguidry/docket)
+[![PyPI - License](https://img.shields.io/pypi/l/pydocket)](https://github.com/chrisguidry/docket/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://chrisguidry.github.io/docket/)
+
+## At a glance
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from docket import Docket
+
+
+async def greet(name: str, greeting="Hello") -> None:
+    print(f"{greeting}, {name} at {datetime.now()}!")
+
+
+async with Docket() as docket:
+    await docket.add(greet)("Jane")
+
+    now = datetime.now(timezone.utc)
+    soon = now + timedelta(seconds=3)
+    await docket.add(greet, when=soon)("John", greeting="Howdy")
+```
+
+```python
+from docket import Docket, Worker
+
+async with Docket() as docket:
+    async with Worker(docket) 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](http://chrisguidry.github.io/docket/),
+[examples](https://chrisguidry.github.io/docket/getting-started/), and the [API
+reference](https://chrisguidry.github.io/docket/api-reference/).
+
+## Why `docket`?
+
+⚡️ 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
+
+## Installing `docket`
+
+Docket is [available on PyPI](https://pypi.org/project/pydocket/) under the package name
+`pydocket`. It targets Python 3.12 or above.
+
+With [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install pydocket
+
+or
+
+uv add pydocket
+```
+
+With `pip`:
+
+```bash
+pip install pydocket
+```
+
+Docket requires a [Redis](http://redis.io/) server with Streams support (which was
+introduced in Redis 5.0.0). Docket is tested with Redis 6 and 7.
+
+# Hacking on `docket`
+
+We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up
+should be as simple as cloning the repo and running:
+
+```bash
+uv sync
+```
+
+The to run the test suite:
+
+```bash
+pytest
+```
+
+We aim to maintain 100% test coverage, which is required for all PRs to `docket`. We
+believe that `docket` 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.

pydocket-0.7.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+docket/__init__.py,sha256=sY1T_NVsXQNOmOhOnfYmZ95dcE_52Ov6DSIVIMZp-1w,869
+docket/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
+docket/annotations.py,sha256=SFBrOMbpAh7P67u8fRTH-u3MVvJQxe0qYi92WAShAsw,2173
+docket/cli.py,sha256=WPm_URZ54h8gHjrsHKP8SXpRzdeepmyH_FhQHai-Qus,20899
+docket/dependencies.py,sha256=fX4vafGjQf7s4x0YROaw7fzQPlYW7TZtCqNhu7Kxj40,16831
+docket/docket.py,sha256=5e101CGLZ2tWNcADo4cdewapmXab47ieMCeQr6d92YQ,24478
+docket/execution.py,sha256=6KozjnS96byvyCMTQ2-IkcIrPsqaPIVu2HZU0U4Be9E,14813
+docket/instrumentation.py,sha256=f-GG5VS6EdS2It30qxjVpzWUBOZQcTnat-3KzPwwDgQ,5367
+docket/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docket/tasks.py,sha256=RIlSM2omh-YDwVnCz6M5MtmK8T_m_s1w2OlRRxDUs6A,1437
+docket/worker.py,sha256=tJfk2rlHODzHaWBzpBXT8h-Lo7RDQ6gb6HU8b3T9gFA,27878
+pydocket-0.7.0.dist-info/METADATA,sha256=soXf7ybhgvSykxRDH56pMJX2DaXf3SJfDFUFLbebAvM,5335
+pydocket-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydocket-0.7.0.dist-info/entry_points.txt,sha256=4WOk1nUlBsUT5O3RyMci2ImuC5XFswuopElYcLHtD5k,47
+pydocket-0.7.0.dist-info/licenses/LICENSE,sha256=YuVWU_ZXO0K_k2FG8xWKe5RGxV24AhJKTvQmKfqXuyk,1087
+pydocket-0.7.0.dist-info/RECORD,,

pydocket-0.6.3.dist-info/METADATA

@@ -1,389 +0,0 @@
-Metadata-Version: 2.4
-Name: pydocket
-Version: 0.6.3
-Summary: A distributed background task system for Python functions
-Project-URL: Homepage, https://github.com/chrisguidry/docket
-Project-URL: Bug Tracker, https://github.com/chrisguidry/docket/issues
-Author-email: Chris Guidry <guid@omg.lol>
-License: # Released under MIT License
-        
-        Copyright (c) 2025 Chris Guidry.
-        
-        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
-Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Requires-Dist: cloudpickle>=3.1.1
-Requires-Dist: opentelemetry-api>=1.30.0
-Requires-Dist: opentelemetry-exporter-prometheus>=0.51b0
-Requires-Dist: prometheus-client>=0.21.1
-Requires-Dist: python-json-logger>=3.2.1
-Requires-Dist: redis>=4.6
-Requires-Dist: rich>=13.9.4
-Requires-Dist: typer>=0.15.1
-Requires-Dist: uuid7>=0.1.0
-Description-Content-Type: text/markdown
-
-Docket is a distributed background task system for Python functions with a focus
-on the scheduling of future work as seamlessly and efficiency as immediate work.
-
-[![PyPI - Version](https://img.shields.io/pypi/v/pydocket)](https://pypi.org/project/pydocket/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydocket)](https://pypi.org/project/pydocket/)
-[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions/workflows/ci.yml)
-[![Codecov](https://img.shields.io/codecov/c/github/chrisguidry/docket)](https://app.codecov.io/gh/chrisguidry/docket)
-[![PyPI - License](https://img.shields.io/pypi/l/pydocket)](https://github.com/chrisguidry/docket/blob/main/LICENSE)
-
-## At a glance
-
-```python
-from datetime import datetime, timedelta, timezone
-
-from docket import Docket
-
-
-async def greet(name: str, greeting="Hello") -> None:
-    print(f"{greeting}, {name} at {datetime.now()}!")
-
-
-async with Docket() as docket:
-    await docket.add(greet)("Jane")
-
-    now = datetime.now(timezone.utc)
-    soon = now + timedelta(seconds=3)
-    await docket.add(greet, when=soon)("John", greeting="Howdy")
-```
-
-```python
-from docket import Docket, Worker
-
-async with Docket() as docket:
-    async with Worker(docket) 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!
-```
-
-## Why `docket`?
-
-⚡️ 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
-
-
-## Installing `docket`
-
-Docket is [available on PyPI](https://pypi.org/project/pydocket/) under the package name
-`pydocket`.  It targets Python 3.12 or above.
-
-With [`uv`](https://docs.astral.sh/uv/):
-
-```bash
-uv pip install pydocket
-
-or
-
-uv add pydocket
-```
-
-With `pip`:
-
-```bash
-pip install pydocket
-```
-
-Docket requires a [Redis](http://redis.io/) server with Streams support (which was
-introduced in Redis 5.0.0).  Docket is tested with Redis 7.
-
-
-## Creating a `Docket`
-
-Each `Docket` should have a name that will be shared across your system, like the name
-of a topic or queue.  By default this is `"docket"`.  You can support many separate
-dockets on a single Redis server as long as they have different names.
-
-Docket accepts a URL to connect to the Redis server (defaulting to the local
-server), and you can pass any additional connection configuration you need on that
-connection URL.
-
-```python
-async with Docket(name="orders", url="redis://my-redis:6379/0") as docket:
-    ...
-```
-
-The `name` and `url` together represent a single shared docket of work across all your
-system.
-
-
-## Scheduling work
-
-A `Docket` is the entrypoint to scheduling immediate and future work.  You define work
-in the form of `async` functions that return `None`.  These task functions can accept
-any parameter types, so long as they can be serialized with
-[`cloudpickle`](https://github.com/cloudpipe/cloudpickle).
-
-```python
-def now() -> datetime:
-    return datetime.now(timezone.utc)
-
-async def send_welcome_email(customer_id: int, name: str) -> None:
-    ...
-
-async def send_followup_email(customer_id: int, name: str) -> None:
-    ...
-
-async with Docket() as docket:
-    await docket.add(send_welcome_email)(12345, "Jane Smith")
-
-    tomorrow = now() + timedelta(days=1)
-    await docket.add(send_followup_email, when=tomorrow)(12345, "Jane Smith")
-```
-
-`docket.add` schedules both immediate work (the default) or future work (with the
-`when: datetime` parameter).
-
-All task executions are identified with a `key` that captures the unique essence of that
-piece of work.  By default they are randomly assigned UUIDs, but assigning your own keys
-unlocks many powerful capabilities.
-
-```python
-async with Docket() as docket:
-    await docket.add(send_welcome_email)(12345, "Jane Smith")
-
-    tomorrow = now() + timedelta(days=1)
-    key = "welcome-email-for-12345"
-    await docket.add(send_followup_email, when=tomorrow, key=key)(12345, "Jane Smith")
-```
-
-If you've given your future work a `key`, then only one unique instance of that
-execution will exist in the future:
-
-```python
-key = "welcome-email-for-12345"
-await docket.add(send_followup_email, when=tomorrow, key=key)(12345, "Jane Smith")
-```
-
-Calling `.add` a second time with the same key won't do anything, so luckily your
-customer won't get two emails!
-
-However, at any time later you can replace that task execution to alter _when_ it will
-happen:
-
-```python
-key = "welcome-email-for-12345"
-next_week = now() + timedelta(days=7)
-await docket.replace(send_followup_email, when=next_week, key=key)(12345, "Jane Smith")
-```
-
-_what arguments_ will be passed:
-
-```python
-key = "welcome-email-for-12345"
-await docket.replace(send_followup_email, when=tomorrow, key=key)(12345, "Jane Q. Smith")
-```
-
-Or just cancel it outright:
-
-```python
-await docket.cancel("welcome-email-for-12345")
-```
-
-Tasks may also be called by name, in cases where you can't or don't want to import the
-module that has your tasks.  This may be common in a distributed environment where the
-code of your task system just isn't available, or it requires heavyweight libraries that
-you wouldn't want to import into your web server.  In this case, you will lose the
-type-checking for `.add` and `.replace` calls, but otherwise everything will work as
-it does with the actual function:
-
-```python
-await docket.add("send_followup_email", when=tomorrow)(12345, "Jane Smith")
-```
-
-These primitives of `.add`, `.replace`, and `.cancel` are sufficient to build a
-large-scale and robust system of background tasks for your application.
-
-## Writing tasks
-
-Tasks are any `async` function that takes `cloudpickle`-able parameters, and returns
-`None`.  Returning `None` is a strong signal that these are _fire-and-forget_ tasks
-whose results aren't used or waited-on by your application.  These are the only kinds of
-tasks that Docket supports.
-
-Docket uses a parameter-based dependency and configuration pattern, which has become
-common in frameworks like [FastAPI](https://fastapi.tiangolo.com/),
-[Typer](https://typer.tiangolo.com/), or [FastMCP](https://github.com/jlowin/fastmcp).
-As such, there is no decorator for tasks.
-
-A very common requirement for tasks is that they have access to schedule further work
-on their own docket, especially for chains of self-perpetuating tasks to implement
-distributed polling and other periodic systems.  One of the first dependencies you may
-look for is the `CurrentDocket`:
-
-```python
-from docket import Docket, CurrentDocket
-
-POLLING_INTERVAL = timedelta(seconds=10)
-
-async def poll_for_changes(file: Path, docket: Docket = CurrentDocket()) -> None:
-    if file.exists():
-        ...do something interesting...
-        return
-    else:
-        await docket.add(poll_for_changes, when=now() + POLLING_INTERVAL)(file)
-```
-
-Here the argument to `docket` is an instance of `Docket` with the same name and URL as
-the worker it's running on.  You can ask for the `CurrentWorker` and `CurrentExecution`
-as well.  Many times it could be useful to have your own task `key` available in order
-to idempotently schedule future work:
-
-```python
-from docket import Docket, CurrentDocket, TaskKey
-
-async def poll_for_changes(
-    file: Path,
-    key: str = TaskKey(),
-    docket: Docket = CurrentDocket()
-) -> None:
-    if file.exists():
-        ...do something interesting...
-        return
-    else:
-        await docket.add(poll_for_changes, when=now() + POLLING_INTERVAL, key=key)(file)
-```
-
-This helps to ensure that there is one continuous "chain" of these future tasks, as they
-all use the same key.
-
-Configuring the retry behavior for a task is also done with a dependency:
-
-```python
-from datetime import timedelta
-from docket import Retry
-
-async def faily(retry: Retry = Retry(attempts=5, delay=timedelta(seconds=3))):
-    if retry.attempt == 4:
-        print("whew!")
-        return
-
-    raise ValueError("whoops!")
-```
-
-In this case, the task `faily` will run 4 times with a delay of 3 seconds between each
-attempt.  If it were to get to 5 attempts, no more would be attempted.  This is a
-linear retry, and an `ExponentialRetry` is also available:
-
-```python
-from datetime import timedelta
-from docket import Retry, ExponentialRetry
-
-
-async def faily(
-    retry: Retry = Retry(
-        attempts=5,
-        minimum_delay=timedelta(seconds=2),
-        maximum_delay=timedelta(seconds=32),
-    ),
-):
-    if retry.attempt == 4:
-        print("whew!")
-        return
-
-    raise ValueError("whoops!")
-```
-
-This would retry in 2, 4, 8, then 16 seconds before that fourth attempt succeeded.
-
-
-## Running workers
-
-You can run as many workers as you like to process the tasks on your docket.  You can
-either run a worker programmatically in Python, or via the CLI.  Clients using docket
-have the advantage that they are usually passing the task functions, but workers don't
-necessarily know which tasks they are supposed to run.  Docket solves this by allowing
-you to explicitly register tasks.
-
-In `my_tasks.py`:
-
-```python
-async def my_first_task():
-    ...
-
-async def my_second_task():
-    ...
-
-my_task_collection = [
-    my_first_task,
-    my_second_task,
-]
-```
-
-From Python:
-
-```python
-from my_tasks import my_task_collection
-
-async with Docket() as docket:
-    for task in my_task_collection:
-        docket.register(task)
-
-    async with Worker(docket) as worker:
-        await worker.run_forever()
-```
-
-From the CLI:
-
-```bash
-docket worker --tasks my_tasks:my_task_collection
-```
-
-By default, workers will process up to 10 tasks concurrently, but you can adjust this
-to your needs with the `concurrency=` keyword argument or the `--concurrency` CLI
-option.
-
-When a worker crashes ungracefully, any tasks it was currently executing will be held
-for a period of time before being redelivered to other workers.  You can control this
-time period with `redelivery_timeout=` or `--redelivery-timeout`.  You'd want to set
-this to a value higher than the longest task you expect to run.  For queues of very fast
-tasks, a few seconds may be ideal; for long data-processing steps involving large
-amount of data, you may need minutes.
-
-
-# Hacking on `docket`
-
-We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up
-should be as simple as cloning the repo and running:
-
-```bash
-uv sync
-```
-
-The to run the test suite:
-
-```bash
-pytest
-```
-
-We aim to main 100% test coverage, which is required for all PRs to `docket`.  We
-believe that `docket` 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.

pydocket-0.6.3.dist-info/RECORD

@@ -1,16 +0,0 @@
-docket/__init__.py,sha256=sY1T_NVsXQNOmOhOnfYmZ95dcE_52Ov6DSIVIMZp-1w,869
-docket/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
-docket/annotations.py,sha256=6sCgQxsgOjBN6ithFdXulXq4CPNSdyFocwyJ1gK9v2Q,1688
-docket/cli.py,sha256=znHN7eqaD_PFpSFn7iXa_uZlKzVWDrKkrmOd1CNuZRk,20561
-docket/dependencies.py,sha256=-gruEho5jf07Jx9fEh2YBFg4gDSJFm7X5qhQjArVXjU,11910
-docket/docket.py,sha256=r5TNcGmaQuxST56OVKNjFXDsrU5-Ioz3Y_I38PkLqRM,21411
-docket/execution.py,sha256=6KozjnS96byvyCMTQ2-IkcIrPsqaPIVu2HZU0U4Be9E,14813
-docket/instrumentation.py,sha256=bZlGA02JoJcY0J1WGm5_qXDfY0AXKr0ZLAYu67wkeKY,4611
-docket/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-docket/tasks.py,sha256=RIlSM2omh-YDwVnCz6M5MtmK8T_m_s1w2OlRRxDUs6A,1437
-docket/worker.py,sha256=Xf6_7GyrIUNq1jG8YjbJk5KkRQdvxs0CniF9XW8kdJg,27450
-pydocket-0.6.3.dist-info/METADATA,sha256=LRtykRFP2dcauKjzQDoNpC_xe6aVjvleAN1xS5cSIUY,13120
-pydocket-0.6.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydocket-0.6.3.dist-info/entry_points.txt,sha256=4WOk1nUlBsUT5O3RyMci2ImuC5XFswuopElYcLHtD5k,47
-pydocket-0.6.3.dist-info/licenses/LICENSE,sha256=YuVWU_ZXO0K_k2FG8xWKe5RGxV24AhJKTvQmKfqXuyk,1087
-pydocket-0.6.3.dist-info/RECORD,,