ORIONIS API REFERENCE

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 documentation

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 _consumeJobs 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 _handleFailure 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 _releaseCancelled Attempt reservation release while preserving the original cancellation.
Method _validateReservation 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 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_after 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.
def __init__(self, app: IApplication, driver: IQueueDriver, serializer: IJobSerializer, options: WorkerOptions, failed: IFailedJobRepository | FailedResolver | None = None): (source)

Initialize a worker without opening queue-backend connections.

Parameters
app:orionis.IApplicationApplication used to create an isolated dependency scope per job.
driver:orionis.queues.contracts.driver.IQueueDriverBackend used to reserve, release, and acknowledge jobs.
serializer:orionis.queues.contracts.serializer.IJobSerializerSerializer restoring dispatch envelopes and registered job instances.
options:orionis.queues.worker.WorkerOptionsValidated connection, queues, concurrency, lease, and polling settings.
failed:IFailedJobRepository | FailedResolver | None, optionalRepository or asynchronous resolver, resolved lazily and cached. None makes terminal failure storage unavailable.
Returns
NoneRetain dependencies and initialize polling, counters, and stop state.
async def _consume(self, *, stop_when_empty: bool, max_jobs: int | None): (source)

Run one consumer in an isolated queue-failure observation context.

Parameters
stop_when_empty:boolEnd this consumer after an empty reservation attempt.
max_jobs:int or NoneShared reservation cap across consumers, or None for no cap.
Returns
NoneFinish this consumer when its stopping condition or budget is reached.
Raises
ExceptionIf polling or execution fails; observe the consumer failure before propagating it.
async def _consumeJobs(self, *, stop_when_empty: bool, max_jobs: int | None): (source)

Reserve and execute jobs within the worker's shared reservation budget.

Parameters
stop_when_empty:boolReturn when the backend has no ready job instead of polling again.
max_jobs:int | NoneShared reservation limit across consumers, or None for no cap.
Returns
NoneUpdate shared counters and return on stop, an exhausted budget, or empty polling when requested.
Raises
ExceptionIf reservation or execution raises outside its own recovery policy.
async def _fail(self, reserved: ReservedJob, exception: Exception) -> bool: (source)

Record a terminal job failure before deleting its leased reservation.

Parameters
reserved:orionis.queues.entities.reserved_job.ReservedJobReservation whose lease must remain valid before terminal recording.
exception:ExceptionJob or recovery exception to record in failed-job storage.
Returns
boolTrue 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.QueueConfigurationErrorIf terminal storage is required and no repository can be resolved.
ExceptionIf observation, repository resolution, recording, or deletion fails.
async def _finish(self, context: JobContext, *, raise_errors: bool): (source)

Acknowledge unfinished work or propagate an explicitly recorded job failure.

Parameters
context:orionis.queues.JobContextJob state tracking release, deletion, and explicit failure.
raise_errors:boolRe-raise a recorded failure after an explicit lifecycle transition.
Returns
NoneAttempt to delete unfinished work, or preserve an existing transition.
Raises
ExceptionIf deletion fails or a recorded job failure must be propagated.
async def _handleFailure(self, reserved: 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.ReservedJobCurrent reservation whose lease controls release and terminal deletion.
envelope:orionis.queues.JobEnvelope | NoneRetry limits and backoff schedule; None selects terminal handling.
exception:ExceptionOriginal error used to reject non-retryable failures and populate storage.
raise_errors:boolForce terminal handling for immediate execution instead of retrying.
Returns
NoneAttempt a backoff-delayed release or a terminal failure transition.
Raises
orionis.queues.exceptions.QueueConfigurationErrorIf terminal handling requires an unavailable failed-job repository.
ExceptionIf a backend transition, failure recording, or lease-loss warning fails.
async def _observe(self, error: Exception, reserved: ReservedJob, phase: str, message: str, *args: object): (source)

Observe a job failure without letting fallback logging replace it.

Parameters
error:ExceptionJob or recovery exception sent through shared failure observation.
reserved:orionis.queues.entities.reserved_job.ReservedJobReservation supplying the job identifier and attempt metadata.
phase:strQueue operation phase associated with the failure.
message:strFallback log template used when no capture receipt is returned.
*args:objectPositional values interpolated into the fallback log message.
Returns
NoneAwait observation and, if no receipt is returned, attempt fallback logging while suppressing its ordinary exceptions.
async def _releaseCancelled(self, reserved: ReservedJob): (source)

Attempt reservation release while preserving the original cancellation.

Parameters
reserved:orionis.queues.entities.reserved_job.ReservedJobUnfinished reservation to release after cancellation.
Returns
NoneAttempt lease release and observe ordinary backend errors without re-raising them.
def _validateReservation(self, reserved: ReservedJob, envelope: JobEnvelope): (source)

Validate reservation routing, timeout compatibility, and retry eligibility.

Parameters
reserved:orionis.queues.entities.reserved_job.ReservedJobReservation identifier, queue, and current attempt count.
envelope:orionis.queues.JobEnvelopeDecoded routing, execution timeout, and retry policy.
Returns
NoneAccept matching routing, a valid attempt, and an eligible retry policy.
Raises
orionis.queues.exceptions.QueuePayloadErrorIf identifiers or routing differ, or the attempt count is invalid.
orionis.queues.exceptions.QueueConfigurationErrorIf the timeout is missing or not strictly below worker retry_after.
orionis.queues.exceptions.QueueRetryErrorIf attempts exceed max_tries or retry_until has been reached.
async def execute(self, reserved: ReservedJob, *, raise_errors: bool = False): (source)

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.ReservedJobBackend reservation containing the payload, attempt count, and lease.
raise_errors:bool, optionalPropagate the original execution or completion error and disable retries.
Returns
NoneAttempt acknowledgement, retry release, or terminal storage; skip expired reservations without invoking their jobs.
Raises
asyncio.CancelledErrorIf execution or failure observation is cancelled, after draining the release of unfinished work, including repeated cancellation.
ExceptionIf raise_errors requests error propagation, or reporting an expired reservation itself fails.
async def run(self, *, stop_when_empty: bool = False, max_jobs: int | None = None) -> int: (source)

Run concurrent consumers under shared stop and reservation limits.

Parameters
stop_when_empty:bool, optionalStop each consumer after an empty poll, even if delayed jobs remain.
max_jobs:int | None, optionalShared reservation cap, or None for no job-count limit.
Returns
intNumber of processed reservations, including retries, handled failures, and skipped expired leases.
Raises
orionis.queues.exceptions.QueueConfigurationErrorIf already running or a supplied limit is not a positive, non-boolean integer.
asyncio.CancelledErrorIf cancelled, after requesting a stop and draining active consumers.
ExceptionIf a consumer fails, after requesting a stop and joining its peers.
def stop(self): (source)

Signal consumers to stop after their in-flight reservations finish.

Returns
NoneSet the shared stop event without waiting for active consumers.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Application container used to create an isolated scope per job.

_concurrency = (source)

Concurrency obtained from options.concurrency.

_connection = (source)

Configured connection used to store or dispatch the operation.

Backend used to reserve, release and acknowledge jobs.

Failure repository or async resolver invoked on terminal failure. If None, terminal failures cannot be recorded.

_failed_resolver = (source)

Resolver supplying the configured failed-job storage backend.

_processed: int = (source)

Processed value used by Worker.

Queue names selected for worker polling.

_retry_after = (source)

Retry after obtained from options.retry_after.

_running: bool = (source)

Running flag used by Worker.

_serializer = (source)

Serializer used to restore envelopes and registered jobs.

Sleep obtained from options.sleep.

_started: int = (source)

Started value used by Worker.

Stop produced by asyncio.Event.