docket API reference

96 public APIs from docket (chrisguidry/docket) — 26 classes, 24 functions, 46 methods. Signatures extracted by static analysis of the actual source.

Repository: chrisguidry/docket

Kind	Count
Classes	26
Functions	24
Methods	46

API list

funcchaos.driver.package_exists_on_pypi(package:str, version:str) -> bool

Check if a package version exists on PyPI.

funcchaos.redis.get_free_port() -> int

Find an available TCP port.

funcchaos.redis.run_redis(version:str) -> AsyncGenerator[tuple[str, Container], None]

Start a Redis Docker container and yield (url, container).

funcchaos.signals.main() -> None

Run signal handling tests for both SIGTERM and SIGINT.

func

chaos.signals.run_signal_test(sig:signal.Signals, redis_url:str, num_workers:int=2, tasks_per_worker:int=2, task_duration:float=5.0) -> tuple[bool, str]

Run a single signal handling test.

funcchaos.signals.spawn_worker(docket_name:str, redis_url:str, channel:str, concurrency:int=2) -> Process

Spawn a worker subprocess.

funcchaos.signals.verify_tasks_completed(docket:Docket, task_keys:list[str]) -> tuple[bool, list[str]]

Verify all tasks completed successfully via Redis state.

classsrc.docket._execution_progress.ExecutionProgress

Manages user-reported progress for a task execution.

methodsrc.docket._execution_progress.ExecutionProgress.increment(amount:int=1) -> None

Atomically increment the current progress value.

methodsrc.docket._execution_progress.ExecutionProgress.set_message(message:str | None) -> None

Update the progress status message.

methodsrc.docket._execution_progress.ExecutionProgress.set_total(total:int) -> None

Set the total/target value for progress tracking.

method

src.docket._execution_progress.ExecutionProgress.subscribe(*ready:asyncio.Event | None=None) -> AsyncGenerator[ProgressEvent, None]

Subscribe to progress updates for this task.

classsrc.docket._prometheus_exporter.PrometheusMetricReader

Prometheus metric exporter for OpenTelemetry.

funcsrc.docket._prometheus_exporter.map_unit(unit:str) -> str

Map unit to Prometheus metric name conventions.

funcsrc.docket._prometheus_exporter.sanitize_attribute(key:str) -> str

Sanitize attribute key according to Prometheus rules.

funcsrc.docket._prometheus_exporter.sanitize_full_name(name:str) -> str

Sanitize metric name including leading digits.

classsrc.docket._redis.AsyncCloseable

Protocol for objects with an async aclose() method.

classsrc.docket._redis.PubSubClient

Protocol capturing the pub/sub interface that docket uses.

classsrc.docket._redis.RedisStreamPendingMessage

One entry returned by XPENDING ...

funcsrc.docket._redis.close_resource(resource:AsyncCloseable, name:str) -> None

Close a resource with error handling.

funcsrc.docket._redis.get_memory_server(url:str) -> MemoryRedisClient | None

Get the cached BurnerRedis instance for a URL, if any.

funcsrc.docket._redis_sentinel.is_sentinel_url(url:str) -> bool

Whether ``url`` is a redis+sentinel:// or rediss+sentinel:// URL.

funcsrc.docket._redis_sentinel.parse_sentinel_url(url:str) -> SentinelConfiguration

Parse a redis+sentinel:// or rediss+sentinel:// URL.

funcsrc.docket._redis_sentinel.urlparse_multihost(url:str) -> ParseResult

urlparse a sentinel URL while preserving its multi-host netloc.

classsrc.docket._result_store.ClusterKeyValueStore

A key-value store that works with RedisCluster.

methodsrc.docket._result_store.ClusterKeyValueStore.delete(key:str, *collection:str | None=None) -> bool

Delete a key-value pair.

methodsrc.docket._result_store.ClusterKeyValueStore.delete_many(keys:Sequence[str], *collection:str | None=None) -> int

Delete multiple key-value pairs.

methodsrc.docket._result_store.ClusterKeyValueStore.get(key:str, *collection:str | None=None) -> dict[str, Any] | None

Retrieve a value by key from the specified collection.

method

src.docket._result_store.ClusterKeyValueStore.get_many(keys:Sequence[str], *collection:str | None=None) -> list[dict[str, Any] | None]

Retrieve multiple values by key.

method

src.docket._result_store.ClusterKeyValueStore.put(key:str, value:Mapping[str, Any], *collection:str | None=None, *ttl:SupportsFloat | None=None) -> None

Store a key-value pair with optional TTL.

method

src.docket._result_store.ClusterKeyValueStore.put_many(keys:Sequence[str], values:Sequence[Mapping[str, Any]], *collection:str | None=None, *ttl:SupportsFloat | None=None) -> None

Store multiple key-value pairs.

method

src.docket._result_store.ClusterKeyValueStore.ttl(key:str, *collection:str | None=None) -> tuple[dict[str, Any] | None, float | None]

Retrieve the value and TTL for a key.

method

src.docket._result_store.ClusterKeyValueStore.ttl_many(keys:Sequence[str], *collection:str | None=None) -> list[tuple[dict[str, Any] | None, float | None]]

Retrieve multiple values and their TTLs.

classsrc.docket.agenda.Agenda

A collection of tasks to be scheduled together on a Docket.

methodsrc.docket.agenda.Agenda.add(function:Callable[P, Awaitable[R]], key:str | None=None) -> Callable[P, None]

Add a task function to the agenda.

methodsrc.docket.agenda.Agenda.clear() -> None

Clear all tasks from the agenda.

classsrc.docket.cli._support.TaskStats

Statistics for a single task function.

funcsrc.docket.cli._support.duration(duration_str:str | timedelta) -> timedelta

Parse a duration string into a timedelta.

funcsrc.docket.cli._support.validate_url(url:str) -> str

Validate that the provided URL is compatible with the CLI.

funcsrc.docket.cli.create_display_layout() -> Layout

Create the layout for watch display.

funcsrc.docket.cli.set_progress_start_time(task_id:TaskID, started_at:datetime) -> None

Set progress bar start time based on execution start time.

classsrc.docket.dependencies._base.AdmissionBlocked

Raised when a task cannot start due to admission control.

methodsrc.docket.dependencies._base.CompletionHandler.on_complete(execution:Execution, outcome:TaskOutcome) -> bool

Handle task completion.

classsrc.docket.dependencies._base.Runtime

Base class for dependencies that control task execution.

classsrc.docket.dependencies._base.TaskOutcome

Captures the outcome of a task execution for handlers.

funcsrc.docket.dependencies._base.format_duration(seconds:float) -> str

Format a duration for log output.

classsrc.docket.dependencies._concurrency.ConcurrencyLimit

Configures concurrency limits for task execution.

funcsrc.docket.dependencies._contextual.CurrentDocket() -> Docket

A dependency to access the current Docket.

funcsrc.docket.dependencies._contextual.CurrentExecution() -> Execution

A dependency to access the current Execution.

funcsrc.docket.dependencies._contextual.CurrentWorker() -> Worker

A dependency to access the current Worker.

classsrc.docket.dependencies._cooldown.Cooldown

Execute first, drop duplicates within window.

classsrc.docket.dependencies._cron.Cron

Declare a task that should run on a cron schedule.

methodsrc.docket.dependencies._cron.Cron.initial_when() -> datetime

Return the next cron time for initial scheduling.

classsrc.docket.dependencies._debounce.Debounce

Wait for submissions to settle, then fire once.

classsrc.docket.dependencies._perpetual.Perpetual

Declare a task that should be run perpetually.

methodsrc.docket.dependencies._perpetual.Perpetual.after(delay:timedelta) -> None

Schedule the next execution after the given delay.

methodsrc.docket.dependencies._perpetual.Perpetual.at(when:datetime) -> None

Schedule the next execution at the given time.

methodsrc.docket.dependencies._perpetual.Perpetual.on_complete(execution:Execution, outcome:TaskOutcome) -> bool

Handle completion by scheduling the next execution.

methodsrc.docket.dependencies._progress.Progress.current() -> int | None

Current progress value.

methodsrc.docket.dependencies._progress.Progress.increment(amount:int=1) -> None

Atomically increment the current progress value.

methodsrc.docket.dependencies._progress.Progress.message() -> str | None

User-provided status message.

methodsrc.docket.dependencies._progress.Progress.set_message(message:str | None) -> None

Update the progress status message.

methodsrc.docket.dependencies._progress.Progress.set_total(total:int) -> None

Set the total/target value for progress tracking.

methodsrc.docket.dependencies._progress.Progress.total() -> int

Total/target value for progress tracking.

classsrc.docket.dependencies._ratelimit.RateLimit

Cap executions within a sliding time window.

classsrc.docket.dependencies._retry.ExponentialRetry

Configures exponential retries for a task.

classsrc.docket.dependencies._retry.ForcedRetry

Raised when a task requests a retry via `after` or `at`

classsrc.docket.dependencies._retry.Retry

Configures linear retries for a task.

methodsrc.docket.dependencies._retry.Retry.after(delay:timedelta) -> NoReturn

Request a retry after the given delay.

methodsrc.docket.dependencies._retry.Retry.at(when:datetime) -> NoReturn

Request a retry at the given time.

methodsrc.docket.dependencies._retry.Retry.handle_failure(execution:Execution, outcome:TaskOutcome) -> bool

Handle failure by scheduling a retry if attempts remain.

methodsrc.docket.dependencies._retry.Retry.in_(delay:timedelta) -> NoReturn

Deprecated: use after() instead.

classsrc.docket.dependencies._timeout.Timeout

Configures a timeout for a task.

methodsrc.docket.dependencies._timeout.Timeout.extend(by:timedelta | None=None) -> None

Extend the timeout by a given duration.

methodsrc.docket.dependencies._timeout.Timeout.remaining() -> timedelta

Get the remaining time until the timeout expires.

classsrc.docket.execution.Disposition

Outcome of a scheduling attempt for an Execution.

methodsrc.docket.execution.Execution.args() -> tuple[Any, ...]

Positional arguments for the task.

methodsrc.docket.execution.Execution.claim(worker:str) -> bool

Atomically check supersession and claim task in a single round-trip.

methodsrc.docket.execution.Execution.docket() -> 'Docket'

Parent docket instance.

methodsrc.docket.execution.Execution.function() -> TaskFunction

Task function to execute.

methodsrc.docket.execution.Execution.get_result(*timeout:timedelta | None=None, *deadline:datetime | None=None) -> Any

Retrieve the result of this task execution.

methodsrc.docket.execution.Execution.key() -> str

Unique task identifier.

methodsrc.docket.execution.Execution.kwargs() -> dict[str, Any]

Keyword arguments for the task.

methodsrc.docket.execution.Execution.mark_as_cancelled() -> None

Mark task as cancelled.

methodsrc.docket.execution.Execution.mark_as_completed(result_key:str | None=None) -> None

Mark task as completed successfully.

methodsrc.docket.execution.Execution.mark_as_failed(error:str | None=None, result_key:str | None=None) -> None

Mark task as failed.

methodsrc.docket.execution.Execution.redelivered() -> bool

Whether this message was redelivered.

method

src.docket.execution.Execution.schedule(replace:bool=False, reschedule_message:'RedisMessageID | None'=None) -> Disposition

Schedule this task atomically in Redis.

methodsrc.docket.execution.Execution.trace_context() -> opentelemetry.context.Context | None

OpenTelemetry trace context.

classsrc.docket.execution.ExecutionState

Lifecycle states for task execution.

classsrc.docket.execution.TaskCall

A fully-resolved request to schedule one task.

funcsrc.docket.testing.assert_no_tasks(docket:Docket) -> None

Assert that no tasks are scheduled on the docket.

classsrc.docket.worker.PubSubMessage

Message received from Redis pub/sub pattern subscription.

classsrc.docket.worker.Worker

A Worker executes tasks on a Docket.

methodsrc.docket.worker.Worker.run_forever() -> None

Run the worker indefinitely.

methodsrc.docket.worker.Worker.run_until_finished() -> None

Run the worker until there are no more tasks to process.

About this data

These signatures were extracted from the public source of chrisguidry/docket using Python's ast module. Argument names, default values, type annotations and return types are taken verbatim from the code. Implementation bodies are never stored. See how it works for details.

Back to all 805 libraries