THE ORIONIS API
Build with clarity.
Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.
class Worker(IWorker): (source)
Constructor: Worker(app, driver, serializer, options, ...)
Consume leased jobs through isolated Orionis dependency scopes.
| Method | __init__ |
Initialize a worker without opening queue-backend connections. |
| Async Method | _consume |
Run one consumer in an isolated queue-failure observation context. |
| Async Method | _consume |
Reserve and execute jobs within the worker's shared reservation budget. |
| Async Method | _fail |
Record a terminal job failure before deleting its leased reservation. |
| Async Method | _finish |
Acknowledge unfinished work or propagate an explicitly recorded job failure. |
| Async Method | _handle |
Select a delayed retry or terminal handling from the envelope's policy. |
| Async Method | _observe |
Observe a job failure without letting fallback logging replace it. |
| Async Method | _release |
Attempt reservation release while preserving the original cancellation. |
| Method | _validate |
Validate reservation routing, timeout compatibility, and retry eligibility. |
| Async Method | execute |
Execute one leased job in an isolated scope and apply its lifecycle outcome. |
| Async Method | run |
Run concurrent consumers under shared stop and reservation limits. |
| Method | stop |
Signal consumers to stop after their in-flight reservations finish. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | _app |
Application container used to create an isolated scope per job. |
| Instance Variable | _concurrency |
Concurrency obtained from options.concurrency. |
| Instance Variable | _connection |
Configured connection used to store or dispatch the operation. |
| Instance Variable | _driver |
Backend used to reserve, release and acknowledge jobs. |
| Instance Variable | _failed |
Failure repository or async resolver invoked on terminal failure. If None, terminal failures cannot be recorded. |
| Instance Variable | _failed |
Resolver supplying the configured failed-job storage backend. |
| Instance Variable | _processed |
Processed value used by Worker. |
| Instance Variable | _queues |
Queue names selected for worker polling. |
| Instance Variable | _retry |
Retry after obtained from options.retry_after. |
| Instance Variable | _running |
Running flag used by Worker. |
| Instance Variable | _serializer |
Serializer used to restore envelopes and registered jobs. |
| Instance Variable | _sleep |
Sleep obtained from options.sleep. |
| Instance Variable | _started |
Started value used by Worker. |
| Instance Variable | _stop |
Stop produced by asyncio.Event. |
IApplication, driver: IQueueDriver, serializer: IJobSerializer, options: WorkerOptions, failed: IFailedJobRepository | FailedResolver | None = None):
(source)
¶
Initialize a worker without opening queue-backend connections.
| Parameters | |
app:orionis.IApplication | Application used to create an isolated dependency scope per job. |
driver:orionis.queues.contracts.driver.IQueueDriver | Backend used to reserve, release, and acknowledge jobs. |
serializer:orionis.queues.contracts.serializer.IJobSerializer | Serializer restoring dispatch envelopes and registered job instances. |
options:orionis.queues.worker.WorkerOptions | Validated connection, queues, concurrency, lease, and polling settings. |
failed:IFailedJobRepository | FailedResolver | None, optional | Repository or asynchronous resolver, resolved lazily and cached. None makes terminal failure storage unavailable. |
| Returns | |
None | Retain dependencies and initialize polling, counters, and stop state. |
Run one consumer in an isolated queue-failure observation context.
| Parameters | |
stopbool | End this consumer after an empty reservation attempt. |
maxint or None | Shared reservation cap across consumers, or None for no cap. |
| Returns | |
None | Finish this consumer when its stopping condition or budget is reached. |
| Raises | |
Exception | If polling or execution fails; observe the consumer failure before propagating it. |
Reserve and execute jobs within the worker's shared reservation budget.
| Parameters | |
stopbool | Return when the backend has no ready job instead of polling again. |
maxint | None | Shared reservation limit across consumers, or None for no cap. |
| Returns | |
None | Update shared counters and return on stop, an exhausted budget, or empty polling when requested. |
| Raises | |
Exception | If reservation or execution raises outside its own recovery policy. |
Record a terminal job failure before deleting its leased reservation.
| Parameters | |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Reservation whose lease must remain valid before terminal recording. |
exception:Exception | Job or recovery exception to record in failed-job storage. |
| Returns | |
bool | True if deletion succeeds; False if the lease expired or was lost. A failure may already be recorded when deletion returns false. |
| Raises | |
orionis.queues.exceptions.QueueConfigurationError | If terminal storage is required and no repository can be resolved. |
Exception | If observation, repository resolution, recording, or deletion fails. |
Acknowledge unfinished work or propagate an explicitly recorded job failure.
| Parameters | |
context:orionis.queues.JobContext | Job state tracking release, deletion, and explicit failure. |
raisebool | Re-raise a recorded failure after an explicit lifecycle transition. |
| Returns | |
None | Attempt to delete unfinished work, or preserve an existing transition. |
| Raises | |
Exception | If deletion fails or a recorded job failure must be propagated. |
ReservedJob, envelope: JobEnvelope | None, exception: Exception, *, raise_errors: bool):
(source)
¶
Select a delayed retry or terminal handling from the envelope's policy.
Reject retries for payload, configuration, or retry-policy errors. Reuse the last configured backoff entry for later attempts.
| Parameters | |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Current reservation whose lease controls release and terminal deletion. |
envelope:orionis.queues.JobEnvelope | None | Retry limits and backoff schedule; None selects terminal handling. |
exception:Exception | Original error used to reject non-retryable failures and populate storage. |
raisebool | Force terminal handling for immediate execution instead of retrying. |
| Returns | |
None | Attempt a backoff-delayed release or a terminal failure transition. |
| Raises | |
orionis.queues.exceptions.QueueConfigurationError | If terminal handling requires an unavailable failed-job repository. |
Exception | If a backend transition, failure recording, or lease-loss warning fails. |
Exception, reserved: ReservedJob, phase: str, message: str, *args: object):
(source)
¶
Observe a job failure without letting fallback logging replace it.
| Parameters | |
error:Exception | Job or recovery exception sent through shared failure observation. |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Reservation supplying the job identifier and attempt metadata. |
phase:str | Queue operation phase associated with the failure. |
message:str | Fallback log template used when no capture receipt is returned. |
*args:object | Positional values interpolated into the fallback log message. |
| Returns | |
None | Await observation and, if no receipt is returned, attempt fallback logging while suppressing its ordinary exceptions. |
Attempt reservation release while preserving the original cancellation.
| Parameters | |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Unfinished reservation to release after cancellation. |
| Returns | |
None | Attempt lease release and observe ordinary backend errors without re-raising them. |
Validate reservation routing, timeout compatibility, and retry eligibility.
| Parameters | |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Reservation identifier, queue, and current attempt count. |
envelope:orionis.queues.JobEnvelope | Decoded routing, execution timeout, and retry policy. |
| Returns | |
None | Accept matching routing, a valid attempt, and an eligible retry policy. |
| Raises | |
orionis.queues.exceptions.QueuePayloadError | If identifiers or routing differ, or the attempt count is invalid. |
orionis.queues.exceptions.QueueConfigurationError | If the timeout is missing or not strictly below worker retry_after. |
orionis.queues.exceptions.QueueRetryError | If attempts exceed max_tries or retry_until has been reached. |
Execute one leased job in an isolated scope and apply its lifecycle outcome.
Limit handler execution to its configured timeout or 95% of the remaining lease, whichever is shorter.
| Parameters | |
reserved:orionis.queues.entities.reserved_job.ReservedJob | Backend reservation containing the payload, attempt count, and lease. |
raisebool, optional | Propagate the original execution or completion error and disable retries. |
| Returns | |
None | Attempt acknowledgement, retry release, or terminal storage; skip expired reservations without invoking their jobs. |
| Raises | |
asyncio.CancelledError | If execution or failure observation is cancelled, after draining the release of unfinished work, including repeated cancellation. |
Exception | If raise_errors requests error propagation, or reporting an expired reservation itself fails. |
bool = False, max_jobs: int | None = None) -> int:
(source)
¶
Run concurrent consumers under shared stop and reservation limits.
| Parameters | |
stopbool, optional | Stop each consumer after an empty poll, even if delayed jobs remain. |
maxint | None, optional | Shared reservation cap, or None for no job-count limit. |
| Returns | |
int | Number of processed reservations, including retries, handled failures, and skipped expired leases. |
| Raises | |
orionis.queues.exceptions.QueueConfigurationError | If already running or a supplied limit is not a positive, non-boolean integer. |
asyncio.CancelledError | If cancelled, after requesting a stop and draining active consumers. |
Exception | If a consumer fails, after requesting a stop and joining its peers. |
Signal consumers to stop after their in-flight reservations finish.
| Returns | |
None | Set the shared stop event without waiting for active consumers. |