pydocket 0.6.1__tar.gz → 0.6.3__tar.gz

{pydocket-0.6.1 → pydocket-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.6.1
+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
@@ -31,6 +31,7 @@ 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

{pydocket-0.6.1 → pydocket-0.6.3}/examples/common.py

@@ -43,8 +43,6 @@ async def run_example_workers(workers: int, concurrency: int, tasks: str):
             await asyncio.create_subprocess_exec(
                 "docket",
                 "worker",
-                "--name",
-                f"worker-{i}",
                 "--url",
                 redis_url,
                 "--tasks",

{pydocket-0.6.1 → pydocket-0.6.3}/examples/find_and_flood.py

@@ -1,4 +1,5 @@
 import asyncio
+import random
 from datetime import timedelta
 from logging import Logger, LoggerAdapter
 from typing import Annotated
@@ -16,7 +17,7 @@ async def find(
     perpetual: Perpetual = Perpetual(every=timedelta(seconds=3), automatic=True),
 ) -> None:
     for i in range(1, 10 + 1):
-        await docket.add(flood, key=f"item-{i}")(i)
+        await docket.add(flood)(i)
 
 
 async def flood(
@@ -24,6 +25,7 @@ async def flood(
     logger: LoggerAdapter[Logger] = TaskLogger(),
 ) -> None:
     logger.info("Working on %s", item)
+    await asyncio.sleep(random.uniform(0.5, 2))
 
 
 tasks = [find, flood]

pydocket-0.6.3/examples/self_perpetuating.py

@@ -0,0 +1,36 @@
+import asyncio
+import random
+from datetime import datetime, timedelta, timezone
+from logging import Logger, LoggerAdapter
+
+from docket import Docket
+from docket.dependencies import CurrentDocket, Perpetual, TaskLogger
+
+from .common import run_example_workers
+
+
+def now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+async def bouncey(
+    docket: Docket = CurrentDocket(),
+    logger: LoggerAdapter[Logger] = TaskLogger(),
+    perpetual: Perpetual = Perpetual(every=timedelta(seconds=3), automatic=True),
+) -> None:
+    seconds = random.randint(1, 10)
+    perpetual.every = timedelta(seconds=seconds)
+    logger.info("See you in %s seconds at %s", seconds, now() + perpetual.every)
+
+
+tasks = [bouncey]
+
+
+if __name__ == "__main__":
+    asyncio.run(
+        run_example_workers(
+            workers=3,
+            concurrency=8,
+            tasks="examples.self_perpetuating:tasks",
+        )
+    )

{pydocket-0.6.1 → pydocket-0.6.3}/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "redis>=4.6",
     "rich>=13.9.4",
     "typer>=0.15.1",
+    "uuid7>=0.1.0",
 ]
 
 [dependency-groups]
@@ -64,6 +65,9 @@ source = "vcs"
 [tool.hatch.build.targets.wheel]
 packages = ["src/docket"]
 
+[tool.ruff]
+target-version = "py312"
+
 [tool.pytest.ini_options]
 addopts = [
     "--numprocesses=logical",

{pydocket-0.6.1 → pydocket-0.6.3}/src/docket/__init__.py

@@ -17,6 +17,7 @@ from .dependencies import (
     ExponentialRetry,
     Perpetual,
     Retry,
+    TaskArgument,
     TaskKey,
     TaskLogger,
     Timeout,
@@ -26,19 +27,20 @@ from .execution import Execution
 from .worker import Worker
 
 __all__ = [
-    "Docket",
-    "Worker",
-    "Execution",
+    "__version__",
     "CurrentDocket",
-    "CurrentWorker",
     "CurrentExecution",
-    "TaskKey",
-    "TaskLogger",
-    "Retry",
+    "CurrentWorker",
+    "Depends",
+    "Docket",
+    "Execution",
     "ExponentialRetry",
     "Logged",
     "Perpetual",
+    "Retry",
+    "TaskArgument",
+    "TaskKey",
+    "TaskLogger",
     "Timeout",
-    "Depends",
-    "__version__",
+    "Worker",
 ]

pydocket-0.6.3/src/docket/__main__.py

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

{pydocket-0.6.1 → pydocket-0.6.3}/src/docket/cli.py

@@ -245,6 +245,13 @@ def worker(
             envvar="DOCKET_WORKER_SCHEDULING_RESOLUTION",
         ),
     ] = timedelta(milliseconds=250),
+    schedule_automatic_tasks: Annotated[
+        bool,
+        typer.Option(
+            "--schedule-automatic-tasks",
+            help="Schedule automatic tasks",
+        ),
+    ] = True,
     until_finished: Annotated[
         bool,
         typer.Option(
@@ -270,6 +277,7 @@ def worker(
             reconnection_delay=reconnection_delay,
             minimum_check_interval=minimum_check_interval,
             scheduling_resolution=scheduling_resolution,
+            schedule_automatic_tasks=schedule_automatic_tasks,
             until_finished=until_finished,
             metrics_port=metrics_port,
             tasks=tasks,

{pydocket-0.6.1 → pydocket-0.6.3}/src/docket/dependencies.py

@@ -79,6 +79,29 @@ def TaskKey() -> str:
     return cast(str, _TaskKey())
 
 
+class _TaskArgument(Dependency):
+    parameter: str | None
+    optional: bool
+
+    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()
+        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:
+    return cast(Any, _TaskArgument(parameter, optional))
+
+
 class _TaskLogger(Dependency):
     async def __aenter__(self) -> logging.LoggerAdapter[logging.Logger]:
         execution = self.execution.get()
@@ -275,6 +298,11 @@ class _Depends(Dependency, Generic[R]):
         parameters = get_dependency_parameters(function)
 
         for parameter, dependency in parameters.items():
+            # Special case for TaskArguments, they are "magical" and infer the parameter
+            # they refer to from the parameter name (unless otherwise specified)
+            if isinstance(dependency, _TaskArgument) and not dependency.parameter:
+                dependency.parameter = parameter
+
             arguments[parameter] = await stack.enter_async_context(dependency)
 
         return arguments
@@ -338,6 +366,12 @@ def validate_dependencies(function: TaskFunction) -> None:
             )
 
 
+class FailedDependency:
+    def __init__(self, parameter: str, error: Exception) -> None:
+        self.parameter = parameter
+        self.error = error
+
+
 @asynccontextmanager
 async def resolved_dependencies(
     worker: "Worker", execution: Execution
@@ -361,6 +395,19 @@ async def resolved_dependencies(
                 arguments[parameter] = kwargs[parameter]
                 continue
 
-            arguments[parameter] = await stack.enter_async_context(dependency)
+            # Special case for TaskArguments, they are "magical" and infer the parameter
+            # they refer to from the parameter name (unless otherwise specified).  At
+            # the top-level task function call, it doesn't make sense to specify one
+            # _without_ a parameter name, so we'll call that a failed dependency.
+            if isinstance(dependency, _TaskArgument) and not dependency.parameter:
+                arguments[parameter] = FailedDependency(
+                    parameter, ValueError("No parameter name specified")
+                )
+                continue
+
+            try:
+                arguments[parameter] = await stack.enter_async_context(dependency)
+            except Exception as error:
+                arguments[parameter] = FailedDependency(parameter, error)
 
         yield arguments

{pydocket-0.6.1 → pydocket-0.6.3}/src/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,
@@ -254,7 +254,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)

{pydocket-0.6.1 → pydocket-0.6.3}/src/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__)
 
@@ -83,6 +91,11 @@ class Execution:
             "docket.attempt": self.attempt,
         }
 
+    def get_argument(self, parameter: str) -> Any:
+        signature = get_signature(self.function)
+        bound_args = signature.bind(*self.args, **self.kwargs)
+        return bound_args.arguments[parameter]
+
     def call_repr(self) -> str:
         arguments: list[str] = []
         function_name = self.function.__name__
@@ -112,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 = "!="

{pydocket-0.6.1 → pydocket-0.6.3}/src/docket/worker.py

@@ -1,5 +1,7 @@
 import asyncio
 import logging
+import os
+import socket
 import sys
 import time
 from datetime import datetime, timedelta, timezone
@@ -11,17 +13,15 @@ from typing import (
     Self,
     cast,
 )
-from uuid import uuid4
 
 from opentelemetry import trace
 from opentelemetry.trace import Tracer
 from redis.asyncio import Redis
 from redis.exceptions import ConnectionError, LockError
 
-from docket.execution import get_signature
-
 from .dependencies import (
     Dependency,
+    FailedDependency,
     Perpetual,
     Retry,
     Timeout,
@@ -36,6 +36,7 @@ from .docket import (
     RedisMessageID,
     RedisReadGroupResponse,
 )
+from .execution import compact_signature, get_signature
 from .instrumentation import (
     QUEUE_DEPTH,
     REDIS_DISRUPTIONS,
@@ -71,6 +72,7 @@ class Worker:
     reconnection_delay: timedelta
     minimum_check_interval: timedelta
     scheduling_resolution: timedelta
+    schedule_automatic_tasks: bool
 
     def __init__(
         self,
@@ -81,14 +83,16 @@ class Worker:
         reconnection_delay: timedelta = timedelta(seconds=5),
         minimum_check_interval: timedelta = timedelta(milliseconds=250),
         scheduling_resolution: timedelta = timedelta(milliseconds=250),
+        schedule_automatic_tasks: bool = True,
     ) -> None:
         self.docket = docket
-        self.name = name or f"worker:{uuid4()}"
+        self.name = name or f"{socket.gethostname()}#{os.getpid()}"
         self.concurrency = concurrency
         self.redelivery_timeout = redelivery_timeout
         self.reconnection_delay = reconnection_delay
         self.minimum_check_interval = minimum_check_interval
         self.scheduling_resolution = scheduling_resolution
+        self.schedule_automatic_tasks = schedule_automatic_tasks
 
     async def __aenter__(self) -> Self:
         self._heartbeat_task = asyncio.create_task(self._heartbeat())
@@ -134,6 +138,7 @@ class Worker:
         reconnection_delay: timedelta = timedelta(seconds=5),
         minimum_check_interval: timedelta = timedelta(milliseconds=100),
         scheduling_resolution: timedelta = timedelta(milliseconds=250),
+        schedule_automatic_tasks: bool = True,
         until_finished: bool = False,
         metrics_port: int | None = None,
         tasks: list[str] = ["docket.tasks:standard_tasks"],
@@ -151,6 +156,7 @@ class Worker:
                     reconnection_delay=reconnection_delay,
                     minimum_check_interval=minimum_check_interval,
                     scheduling_resolution=scheduling_resolution,
+                    schedule_automatic_tasks=schedule_automatic_tasks,
                 ) as worker:
                     if until_finished:
                         await worker.run_until_finished()
@@ -199,10 +205,7 @@ class Worker:
             self._execution_counts = {}
 
     async def _run(self, forever: bool = False) -> None:
-        logger.info("Starting worker %r with the following tasks:", self.name)
-        for task_name, task in self.docket.tasks.items():
-            signature = get_signature(task)
-            logger.info("* %s%s", task_name, signature)
+        self._startup_log()
 
         while True:
             try:
@@ -220,7 +223,8 @@ class Worker:
     async def _worker_loop(self, redis: Redis, forever: bool = False):
         worker_stopping = asyncio.Event()
 
-        await self._schedule_all_automatic_perpetual_tasks()
+        if self.schedule_automatic_tasks:
+            await self._schedule_all_automatic_perpetual_tasks()
 
         scheduler_task = asyncio.create_task(
             self._scheduler_loop(redis, worker_stopping)
@@ -499,6 +503,8 @@ class Worker:
         arrow = "↬" if execution.attempt > 1 else "↪"
         logger.info("%s [%s] %s", arrow, ms(punctuality), call, extra=log_context)
 
+        dependencies: dict[str, Dependency] = {}
+
         with tracer.start_as_current_span(
             execution.function.__name__,
             kind=trace.SpanKind.CONSUMER,
@@ -509,17 +515,34 @@ class Worker:
             },
             links=execution.incoming_span_links(),
         ):
-            async with resolved_dependencies(self, execution) as dependencies:
-                # Preemptively reschedule the perpetual task for the future, or clear
-                # the known task key for this task
-                rescheduled = await self._perpetuate_if_requested(
-                    execution, dependencies
-                )
-                if not rescheduled:
-                    async with self.docket.redis() as redis:
-                        await self._delete_known_task(redis, execution)
+            try:
+                async with resolved_dependencies(self, execution) as dependencies:
+                    # Preemptively reschedule the perpetual task for the future, or clear
+                    # the known task key for this task
+                    rescheduled = await self._perpetuate_if_requested(
+                        execution, dependencies
+                    )
+                    if not rescheduled:
+                        async with self.docket.redis() as redis:
+                            await self._delete_known_task(redis, execution)
+
+                    dependency_failures = {
+                        k: v
+                        for k, v in dependencies.items()
+                        if isinstance(v, FailedDependency)
+                    }
+                    if dependency_failures:
+                        raise ExceptionGroup(
+                            (
+                                "Failed to resolve dependencies for parameter(s): "
+                                + ", ".join(dependency_failures.keys())
+                            ),
+                            [
+                                dependency.error
+                                for dependency in dependency_failures.values()
+                            ],
+                        )
 
-                try:
                     if timeout := get_single_dependency_of_type(dependencies, Timeout):
                         await self._run_function_with_timeout(
                             execution, dependencies, timeout
@@ -544,24 +567,24 @@ class Worker:
                     logger.info(
                         "%s [%s] %s", arrow, ms(duration), call, extra=log_context
                     )
-                except Exception:
-                    duration = log_context["duration"] = time.time() - start
-                    TASKS_FAILED.add(1, counter_labels)
-
-                    retried = await self._retry_if_requested(execution, dependencies)
-                    if not retried:
-                        retried = await self._perpetuate_if_requested(
-                            execution, dependencies, timedelta(seconds=duration)
-                        )
+            except Exception:
+                duration = log_context["duration"] = time.time() - start
+                TASKS_FAILED.add(1, counter_labels)
 
-                    arrow = "↫" if retried else "↩"
-                    logger.exception(
-                        "%s [%s] %s", arrow, ms(duration), call, extra=log_context
+                retried = await self._retry_if_requested(execution, dependencies)
+                if not retried:
+                    retried = await self._perpetuate_if_requested(
+                        execution, dependencies, timedelta(seconds=duration)
                     )
-                finally:
-                    TASKS_RUNNING.add(-1, counter_labels)
-                    TASKS_COMPLETED.add(1, counter_labels)
-                    TASK_DURATION.record(duration, counter_labels)
+
+                arrow = "↫" if retried else "↩"
+                logger.exception(
+                    "%s [%s] %s", arrow, ms(duration), call, extra=log_context
+                )
+            finally:
+                TASKS_RUNNING.add(-1, counter_labels)
+                TASKS_COMPLETED.add(1, counter_labels)
+                TASK_DURATION.record(duration, counter_labels)
 
     async def _run_function_with_timeout(
         self,
@@ -641,6 +664,11 @@ class Worker:
 
         return True
 
+    def _startup_log(self) -> None:
+        logger.info("Starting worker %r with the following tasks:", self.name)
+        for task_name, task in self.docket.tasks.items():
+            logger.info("* %s(%s)", task_name, compact_signature(get_signature(task)))
+
     @property
     def workers_set(self) -> str:
         return self.docket.workers_set

{pydocket-0.6.1 → pydocket-0.6.3}/tests/test_dependencies.py

@@ -1,7 +1,9 @@
+import logging
+
 import pytest
 
 from docket import CurrentDocket, CurrentWorker, Docket, Worker
-from docket.dependencies import Retry
+from docket.dependencies import Depends, Retry, TaskArgument
 
 
 async def test_dependencies_may_be_duplicated(docket: Docket, worker: Worker):
@@ -91,3 +93,48 @@ async def test_user_provide_retries_are_used(docket: Docket, worker: Worker):
     await worker.run_until_finished()
 
     assert calls == 2
+
+
+async def test_dependencies_error_for_missing_task_argument(
+    docket: Docket, worker: Worker, caplog: pytest.LogCaptureFixture
+):
+    """A task will fail when asking for a missing task argument"""
+
+    async def dependency_one(nope: list[str] = TaskArgument()) -> list[str]:
+        raise NotImplementedError("This should not be called")  # pragma: no cover
+
+    async def dependent_task(
+        a: list[str],
+        b: list[str] = TaskArgument("a"),
+        c: list[str] = Depends(dependency_one),
+    ) -> None:
+        raise NotImplementedError("This should not be called")  # pragma: no cover
+
+    await docket.add(dependent_task)(a=["hello", "world"])
+
+    await worker.run_until_finished()
+
+    with caplog.at_level(logging.ERROR):
+        await worker.run_until_finished()
+
+    assert "Failed to resolve dependencies for parameter(s): c" in caplog.text
+    assert "ExceptionGroup" in caplog.text
+    assert "KeyError: 'nope'" in caplog.text
+
+
+async def test_a_task_argument_cannot_ask_for_itself(
+    docket: Docket, worker: Worker, caplog: pytest.LogCaptureFixture
+):
+    """A task argument cannot ask for itself"""
+
+    # This task would be nonsense, because it's asking for itself.
+    async def dependent_task(a: list[str] = TaskArgument()) -> None:
+        raise NotImplementedError("This should not be called")  # pragma: no cover
+
+    await docket.add(dependent_task)()
+
+    with caplog.at_level(logging.ERROR):
+        await worker.run_until_finished()
+
+    assert "Failed to resolve dependencies for parameter(s): a" in caplog.text
+    assert "ValueError: No parameter name specified" in caplog.text

pydocket-0.6.3/tests/test_execution.py

@@ -0,0 +1,63 @@
+from typing import Annotated
+
+import pytest
+
+from docket import Docket, Worker
+from docket.annotations import Logged
+from docket.dependencies import CurrentDocket, CurrentWorker, Depends
+from docket.execution import TaskFunction, compact_signature, get_signature
+
+
+async def no_args() -> None: ...  # pragma: no cover
+
+
+async def one_arg(a: str) -> None: ...  # pragma: no cover
+
+
+async def two_args(a: str, b: str) -> None: ...  # pragma: no cover
+
+
+async def optional_args(a: str, b: str, c: str = "c") -> None: ...  # pragma: no cover
+
+
+async def logged_args(
+    a: Annotated[str, Logged()],
+    b: Annotated[str, Logged()] = "foo",
+) -> None: ...  # pragma: no cover
+
+
+async def a_dependency() -> str: ...  # pragma: no cover
+
+
+async def dependencies(
+    a: str,
+    b: int = 42,
+    c: str = Depends(a_dependency),
+    docket: Docket = CurrentDocket(),
+    worker: Worker = CurrentWorker(),
+) -> None: ...  # pragma: no cover
+
+
+async def only_dependencies(
+    a: str = Depends(a_dependency),
+    docket: Docket = CurrentDocket(),
+    worker: Worker = CurrentWorker(),
+) -> None: ...  # pragma: no cover
+
+
+@pytest.mark.parametrize(
+    "function, expected",
+    [
+        (no_args, ""),
+        (one_arg, "a: str"),
+        (two_args, "a: str, b: str"),
+        (optional_args, "a: str, b: str, c: str = 'c'"),
+        (logged_args, "a: str, b: str = 'foo'"),
+        (dependencies, "a: str, b: int = 42, ..."),
+        (only_dependencies, "..."),
+    ],
+)
+async def test_compact_signature(
+    docket: Docket, worker: Worker, function: TaskFunction, expected: str
+):
+    assert compact_signature(get_signature(function)) == expected

{pydocket-0.6.1 → pydocket-0.6.3}/tests/test_fundamentals.py

@@ -27,6 +27,7 @@ from docket import (
     Logged,
     Perpetual,
     Retry,
+    TaskArgument,
     TaskKey,
     TaskLogger,
     Timeout,
@@ -150,10 +151,10 @@ async def test_rescheduling_by_name(
 
     key = f"my-cool-task:{uuid4()}"
 
-    soon = now() + timedelta(milliseconds=10)
+    soon = now() + timedelta(milliseconds=100)
     await docket.add(the_task, soon, key=key)("a", "b", c="c")
 
-    later = now() + timedelta(milliseconds=100)
+    later = now() + timedelta(milliseconds=200)
     await docket.replace("the_task", later, key=key)("b", "c", c="d")
 
     await worker.run_until_finished()
@@ -1383,3 +1384,152 @@ async def test_dependencies_can_ask_for_docket_dependencies(
     await docket.add(dependent_task)()
 
     await worker.run_until_finished()
+
+
+async def test_dependency_failures_are_task_failures(
+    docket: Docket, worker: Worker, caplog: pytest.LogCaptureFixture
+):
+    """A task dependency failure will cause the task to fail"""
+
+    called: bool = False
+
+    async def dependency_one() -> str:
+        raise ValueError("this one is bad")
+
+    async def dependency_two() -> str:
+        raise ValueError("and so is this one")
+
+    async def dependent_task(
+        a: str = Depends(dependency_one),
+        b: str = Depends(dependency_two),
+    ) -> None:
+        nonlocal called
+        called = True  # pragma: no cover
+
+    await docket.add(dependent_task)()
+
+    with caplog.at_level(logging.ERROR):
+        await worker.run_until_finished()
+
+    assert not called
+
+    assert "Failed to resolve dependencies for parameter(s): a, b" in caplog.text
+    assert "ValueError: this one is bad" in caplog.text
+    assert "ValueError: and so is this one" in caplog.text
+
+
+async def test_contextual_dependency_before_failures_are_task_failures(
+    docket: Docket, worker: Worker, caplog: pytest.LogCaptureFixture
+):
+    """A contextual task dependency failure will cause the task to fail"""
+
+    called: int = 0
+
+    @asynccontextmanager
+    async def dependency_before() -> AsyncGenerator[str, None]:
+        raise ValueError("this one is bad")
+        yield "this won't be used"  # pragma: no cover
+
+    async def dependent_task(
+        a: str = Depends(dependency_before),
+    ) -> None:
+        nonlocal called
+        called += 1  # pragma: no cover
+
+    await docket.add(dependent_task)()
+
+    with caplog.at_level(logging.ERROR):
+        await worker.run_until_finished()
+
+    assert not called
+
+    assert "Failed to resolve dependencies for parameter(s): a" in caplog.text
+    assert "ValueError: this one is bad" in caplog.text
+
+
+async def test_contextual_dependency_after_failures_are_task_failures(
+    docket: Docket, worker: Worker, caplog: pytest.LogCaptureFixture
+):
+    """A contextual task dependency failure will cause the task to fail"""
+
+    called: int = 0
+
+    @asynccontextmanager
+    async def dependency_after() -> AsyncGenerator[str, None]:
+        yield "this will be used"
+        raise ValueError("this one is bad")
+
+    async def dependent_task(
+        a: str = Depends(dependency_after),
+    ) -> None:
+        assert a == "this will be used"
+
+        nonlocal called
+        called += 1
+
+    await docket.add(dependent_task)()
+
+    with caplog.at_level(logging.ERROR):
+        await worker.run_until_finished()
+
+    assert called == 1
+
+    assert "ValueError: this one is bad" in caplog.text
+
+
+async def test_dependencies_can_ask_for_task_arguments(docket: Docket, worker: Worker):
+    """A task dependency can ask for a task argument"""
+
+    called = 0
+
+    async def dependency_one(a: list[str] = TaskArgument()) -> list[str]:
+        return a
+
+    async def dependency_two(another_name: list[str] = TaskArgument("a")) -> list[str]:
+        return another_name
+
+    async def dependent_task(
+        a: list[str],
+        b: list[str] = TaskArgument("a"),
+        c: list[str] = Depends(dependency_one),
+        d: list[str] = Depends(dependency_two),
+    ) -> None:
+        assert a is b
+        assert a is c
+        assert a is d
+
+        nonlocal called
+        called += 1
+
+    await docket.add(dependent_task)(a=["hello", "world"])
+
+    await worker.run_until_finished()
+
+    assert called == 1
+
+
+async def test_task_arguments_may_be_optional(docket: Docket, worker: Worker):
+    """A task dependency can ask for a task argument optionally"""
+
+    called = 0
+
+    async def dependency_one(
+        a: list[str] | None = TaskArgument(optional=True),
+    ) -> list[str] | None:
+        return a
+
+    async def dependent_task(
+        not_a: list[str],
+        b: list[str] | None = Depends(dependency_one),
+    ) -> None:
+        assert not_a == ["hello", "world"]
+        assert b is None
+
+        nonlocal called
+        called += 1
+
+    await docket.add(dependent_task)(not_a=["hello", "world"])
+
+    await worker.run_until_finished()
+
+    assert called == 1

{pydocket-0.6.1 → pydocket-0.6.3}/tests/test_worker.py

@@ -273,14 +273,14 @@ async def test_worker_announcements(
     docket.register(the_task)
     docket.register(another_task)
 
-    async with Worker(docket) as worker_a:
+    async with Worker(docket, name="worker-a") as worker_a:
         await asyncio.sleep(heartbeat.total_seconds() * 5)
 
         workers = await docket.workers()
         assert len(workers) == 1
         assert worker_a.name in {w.name for w in workers}
 
-        async with Worker(docket) as worker_b:
+        async with Worker(docket, name="worker-b") as worker_b:
             await asyncio.sleep(heartbeat.total_seconds() * 5)
 
             workers = await docket.workers()
@@ -315,14 +315,14 @@ async def test_task_announcements(
 
     docket.register(the_task)
     docket.register(another_task)
-    async with Worker(docket) as worker_a:
+    async with Worker(docket, name="worker-a") as worker_a:
         await asyncio.sleep(heartbeat.total_seconds() * 5)
 
         workers = await docket.task_workers("the_task")
         assert len(workers) == 1
         assert worker_a.name in {w.name for w in workers}
 
-        async with Worker(docket) as worker_b:
+        async with Worker(docket, name="worker-b") as worker_b:
             await asyncio.sleep(heartbeat.total_seconds() * 5)
 
             workers = await docket.task_workers("the_task")
@@ -422,13 +422,13 @@ async def test_perpetual_tasks_are_scheduled_close_to_target_time(
     assert len(timestamps) == 8
 
     intervals = [next - previous for previous, next in zip(timestamps, timestamps[1:])]
-    minimum = min(intervals)
+    average = sum(intervals, timedelta(0)) / len(intervals)
 
     debug = ", ".join([f"{i.total_seconds() * 1000:.2f}ms" for i in intervals])
 
     # It's not reliable to assert the maximum duration on different machine setups, but
     # we'll make sure that the minimum is observed (within 5ms), which is the guarantee
-    assert minimum >= timedelta(milliseconds=45), debug
+    assert average >= timedelta(milliseconds=50), debug
 
 
 async def test_worker_can_exit_from_perpetual_tasks_that_queue_further_tasks(
@@ -491,3 +491,25 @@ def test_formatting_durations():
     assert ms(1000.000) == "  1000s "
     assert ms(10000.00) == " 10000s "
     assert ms(100000.0) == "100000s "
+
+
+async def test_worker_can_be_told_to_skip_automatic_tasks(docket: Docket):
+    """A worker can be told to skip automatic tasks"""
+
+    called = False
+
+    async def perpetual_task(
+        perpetual: Perpetual = Perpetual(
+            every=timedelta(milliseconds=50), automatic=True
+        ),
+    ):
+        nonlocal called
+        called = True  # pragma: no cover
+
+    docket.register(perpetual_task)
+
+    # Without the flag, this would hang because the task would always be scheduled
+    async with Worker(docket, schedule_automatic_tasks=False) as worker:
+        await worker.run_until_finished()
+
+    assert not called

{pydocket-0.6.1 → pydocket-0.6.3}/uv.lock

@@ -723,6 +723,7 @@ dependencies = [
     { name = "redis" },
     { name = "rich" },
     { name = "typer" },
+    { name = "uuid7" },
 ]
 
 [package.dev-dependencies]
@@ -756,6 +757,7 @@ requires-dist = [
     { name = "redis", specifier = ">=4.6" },
     { name = "rich", specifier = ">=13.9.4" },
     { name = "typer", specifier = ">=0.15.1" },
+    { name = "uuid7", specifier = ">=0.1.0" },
 ]
 
 [package.metadata.requires-dev]
@@ -1029,6 +1031,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c8/19/4ec628951a74043532ca2cf5d97b7b14863931476d117c471e8e2b1eb39f/urllib3-2.3.0-py3-none-any.whl", hash = "sha256:1cee9ad369867bfdbbb48b7dd50374c0967a0bb7710050facf0dd6911440e3df", size = 128369 },
 ]
 
+[[package]]
+name = "uuid7"
+version = "0.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5c/19/7472bd526591e2192926247109dbf78692e709d3e56775792fec877a7720/uuid7-0.1.0.tar.gz", hash = "sha256:8c57aa32ee7456d3cc68c95c4530bc571646defac01895cfc73545449894a63c", size = 14052 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b5/77/8852f89a91453956582a85024d80ad96f30a41fed4c2b3dce0c9f12ecc7e/uuid7-0.1.0-py2.py3-none-any.whl", hash = "sha256:5e259bb63c8cb4aded5927ff41b444a80d0c7124e8a0ced7cf44efa1f5cccf61", size = 7477 },
+]
+
 [[package]]
 name = "virtualenv"
 version = "20.29.2"

pydocket-0.6.1/src/docket/__main__.py

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