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

Own one application's handler, active lifetimes and pending reports.

Method __init__ Initialize runtime ownership, reporting state, and task registries.
Async Method _attempt Select and validate deferred effects through an application hook.
Method _begin Claim or reuse an incident before handler execution can suspend.
Async Method _completeHandling Complete selected logging effects without requesting presentation.
Method _correlate Assign operation correlation lazily when recording a failure.
Async Method _defaultHandling Select native failure effects after application policy fails.
Async Method _drainShutdown Settle owned work and reports while admission remains closed.
Async Method _fallbackPresentation Share native presentation planning for an incident without a plan.
Method _finishCancelledWork Cancel abandoned work and retain local futures until cleanup completes.
Async Method _invoke Invoke an application handler method within the reporting timeout.
Method _recordIncident Record a new or reclaimed incident before invoking a handler.
Method _settleCancelledFuture Release completed cleanup and observe only unsupervised failures.
Method _shutdownFinished Release the coordinator context and retrieve an unclaimed failure.
Method activate Register a started owner and record the current event loop.
Method beginClosing Move an owner into closing while retaining cleanup observation.
Async Method capture Observe an original exception once per operation.
Async Method captureResult Observe a declared failed result without constructing an exception.
Method createTask Create and supervise application work until shutdown.
Method deactivate Release active and closing ownership for a lifecycle token.
Async Method dispatchFailure Select and complete failure effects without requesting presentation.
Async Method drain Await owned callback reports until no pending report remains.
Async Method handlingFor Return the selected plan without observing the exception twice.
Method hasOwner Check whether an owner is active or still completing shutdown.
Async Method prepare Resolve the application handler once outside operational scopes.
Async Method presentHandling Present a selected plan with bounded, nonrecursive failure handling.
Async Method shutdown Cancel owned application tasks and drain their failure reports.
Async Method start Activate an owner after earlier lifecycle transitions complete.
Method stopReporting Disable logging effects while retaining owner-based observation.
Instance Variable _closing_owners Owners retaining observation while final resource closure completes.
Instance Variable _fallback_handler Scope-free native policy selected after custom handling fails.
Instance Variable _loop Serving loop used to schedule notification from native threads.
Instance Variable _owners Active owners retaining the runtime's shared resources.
Instance Variable _pending Loop-local reports and abandoned futures retained through cleanup.
Instance Variable _pending_lock Serialize incident reservation and pending cross-thread registries.
Instance Variable _prepare_lock Serialize preparation of the shared application handler.
Instance Variable _reporting_enabled Whether ordinary logging resources remain safe to use.
Instance Variable _shutdown_pending Shared shutdown coordinator retained only while cleanup is pending.
Instance Variable _shutting_down Reject new work until a valid activation reopens task admission.
Instance Variable _tasks Supervised application tasks cancelled and drained at final shutdown.
Instance Variable _thread_pending Submissions retained until ownership transfers to a loop-side task.
Instance Variable app Application providing dependency resolution and hook invocation.
Instance Variable handler Prepared shared application handler, resolved lazily when absent.
Instance Variable lifecycle_lock Coordinate runtime activation with final shared-resource closure.
Instance Variable timeout Cooperative timeout in seconds for a reporting operation.
Property active Check whether active or closing owners keep observation enabled.
Property ownerCount Return the number of owners still holding resource ownership.
def __init__(self, app: object, handler: object | None = None, *, timeout: float = 5.0): (source)

Initialize runtime ownership, reporting state, and task registries.

Parameters
app:objectApplication providing handler resolution, construction, and invocation.
handler:object or None, optionalPre-resolved failure handler; resolve lazily when omitted.
timeout:float, optionalMaximum seconds allowed for each handler or logging action. Defaults to 5.0.
Returns
NoneNo return value.
async def _attempt(self, method: str, original: BaseException | None, incident: FailureContext, **kwargs: object) -> tuple[bool, FailureHandling | None]: (source)

Select and validate deferred effects through an application hook.

Parameters
method:strApplication failure-handler method to invoke.
original:BaseException or NoneOriginal exception for fallback diagnostics, or None for a result.
incident:FailureContextIncident metadata used if application policy fails.
**kwargs:objectKeyword arguments forwarded to the application hook.
Returns
tuple[bool, FailureHandling | None]Whether policy completed with a valid return value, plus its plan. Return (False, None) after recoverable hook failures.
Raises
BaseExceptionIf caller cancellation or another control-flow exception must propagate.
def _begin(self, exception: BaseException, *, context: FailureContext, claimed: _Incident | None = None) -> tuple[FailureContext, FailureReceipt, _Incident | None]: (source)

Claim or reuse an incident before handler execution can suspend.

Parameters
exception:BaseExceptionOriginal exception whose incident identity is being claimed.
context:FailureContextMetadata supplied for the observation attempt.
claimed:_Incident or None, optionalCallback incident already claimed before asynchronous delivery.
Returns
tuple[FailureContext, FailureReceipt, _Incident | None]Resolved context, delivery receipt, and incident. A duplicate receipt signals that the caller must not deliver the failure again.
async def _completeHandling(self, handling: FailureHandling | None, exception: BaseException | None, context: FailureContext) -> tuple[bool, bool]: (source)

Complete selected logging effects without requesting presentation.

Parameters
handling:FailureHandling or NoneDeferred plan to complete, or None for observation without effects.
exception:BaseException or NoneOriginal failure, or None for a failed result.
context:FailureContextMetadata controlling whether reporting is allowed or expected.
Returns
tuple[bool, bool]Reported and degraded status flags, respectively.
Raises
BaseExceptionIf caller cancellation or another control-flow exception must propagate.
def _correlate(self, context: FailureContext) -> FailureContext: (source)

Assign operation correlation lazily when recording a failure.

Parameters
context:FailureContextMetadata to correlate with the current operation for this runtime.
Returns
FailureContextContext carrying an existing or newly allocated correlation identifier, or the original context when correlation is already set or unavailable.
async def _defaultHandling(self, exception: BaseException, context: FailureContext) -> FailureHandling | None: (source)

Select native failure effects after application policy fails.

Parameters
exception:BaseExceptionOriginal failure to pass to the native exception handler.
context:FailureContextIncident metadata controlling the fallback policy.
Returns
FailureHandling or NoneNative handling plan, or None when no plan can be selected.
Raises
BaseExceptionIf caller cancellation or another control-flow exception must propagate.
async def _drainShutdown(self, excluded: frozenset[asyncio.Task]): (source)

Settle owned work and reports while admission remains closed.

Parameters
excluded:frozenset[asyncio.Task]Lifecycle owners that are waiting for this coordinator.
Returns
NoneNo return value.
async def _fallbackPresentation(self, exception: BaseException, context: FailureContext, receipt: FailureReceipt, current: _Operation | None, incident: _Incident | None) -> FailureHandling | None: (source)

Share native presentation planning for an incident without a plan.

Parameters
exception:BaseExceptionPreviously observed exception requiring presentation policy.
context:FailureContextMetadata passed to fallback policy with reporting disabled.
receipt:FailureReceiptExisting delivery status used for the fallback claim.
current:_Operation or NoneOperation that can retain the fallback incident.
incident:_Incident or NoneExisting incident, or None to create a shared fallback claim.
Returns
FailureHandling or NoneNative handling plan, or None when fallback selection yields no plan.
def _finishCancelledWork(self, awaitable: object, *, supervised: bool, on_error: Callable[[BaseException], object]): (source)

Cancel abandoned work and retain local futures until cleanup completes.

Parameters
awaitable:objectApplication work whose supervising wrapper was cancelled.
supervised:boolWhether this runtime already owned the future at wrapper registration.
on_error:collections.abc.Callable[[BaseException], object]Central observer for original cleanup failures.
Returns
NoneNo return value.
async def _invoke(self, method: str, **kwargs: object) -> object: (source)

Invoke an application handler method within the reporting timeout.

Parameters
method:strName of the configured failure-handler method to invoke.
**kwargs:objectKeyword arguments passed through application dependency injection.
Returns
objectValue returned by the selected handler method.
Raises
TimeoutErrorIf handler preparation or invocation exceeds the configured timeout.
def _recordIncident(self, exception: BaseException, context: FailureContext, current: _Operation | None, incident: _Incident | None) -> tuple[FailureContext, FailureReceipt, _Incident]: (source)

Record a new or reclaimed incident before invoking a handler.

Parameters
exception:BaseExceptionOriginal exception to retain in the incident.
context:FailureContextMetadata to enrich with event, correlation, and parent identifiers.
current:_Operation or NoneCurrent operation that can retain the incident.
incident:_Incident or NoneReclaimed incident, or None to create one.
Returns
tuple[FailureContext, FailureReceipt, _Incident]Enriched context, fresh receipt, and incident marked as started.
def _settleCancelledFuture(self, completed: asyncio.Future, *, supervised: bool, on_error: Callable[[BaseException], object]): (source)

Release completed cleanup and observe only unsupervised failures.

Parameters
completed:asyncio.FutureAdopted local future whose cleanup has reached a terminal state.
supervised:boolWhether another runtime observer already owns this failure.
on_error:collections.abc.Callable[[BaseException], object]Central observer for original cleanup failures.
Returns
NoneNo return value.
def _shutdownFinished(self, completed: asyncio.Task[None]): (source)

Release the coordinator context and retrieve an unclaimed failure.

Parameters
completed:asyncio.Task[None]Shared shutdown coordinator that finished or was cancelled.
Returns
NoneNo return value.
def activate(self, owner: object): (source)

Register a started owner and record the current event loop.

Parameters
owner:objectHashable lifecycle token whose startup completed.
Returns
NoneNo return value.
Raises
RuntimeErrorIf no event loop is running or earlier shutdown is still pending.
def beginClosing(self, owner: object): (source)

Move an owner into closing while retaining cleanup observation.

Call while holding lifecycle_lock; drain reports before deactivation.

Parameters
owner:objectHashable lifecycle token retiring its resource ownership.
Returns
NoneNo return value.
async def capture(self, exception: BaseException, *, context: FailureContext, _incident: _Incident | None = None) -> FailureReceipt | None: (source)

Observe an original exception once per operation.

Leave presentation to the execution owner and ignore cancellation or process-control exceptions.

Parameters
exception:BaseExceptionOriginal exception instance to observe.
context:FailureContextExecution metadata for the incident.
_incident:_Incident or None, optionalIncident claimed by a callback before asynchronous delivery.
Returns
FailureReceipt or NoneDelivery receipt, including duplicate status, or None when inactive or when the exception represents cancellation or process control.
Raises
BaseExceptionIf delivery is interrupted by caller cancellation or a control-flow failure in the reporting path.
async def captureResult(self, value: object, *, context: FailureContext) -> FailureReceipt | None: (source)

Observe a declared failed result without constructing an exception.

Parameters
value:objectOriginal result classified as a failure by its execution owner.
context:FailureContextExecution metadata for the failed result.
Returns
FailureReceipt or NoneDelivery and reporting status, or None when the runtime is inactive.
Raises
BaseExceptionIf cancellation or a control-flow error escapes application policy.
def createTask(self, coroutine: object, *, name: str | None = None) -> asyncio.Task: (source)

Create and supervise application work until shutdown.

During shutdown, cancel new work before entering its awaitable. Valid activation or startup reopens admission after cleanup. If scheduling fails, close only the runtime wrapper; the original remains caller-owned. Adopted futures on the running loop remain owned until cancellation cleanup completes, without cancelling an already unwinding task again.

Parameters
coroutine:objectAwaitable application work whose failures must be observed.
name:str or None, optionalTask name and operation label for failure observation.
Returns
asyncio.TaskSupervised task registered for cancellation during runtime shutdown.
Raises
RuntimeErrorIf no event loop is running.
def deactivate(self, owner: object): (source)

Release active and closing ownership for a lifecycle token.

Parameters
owner:objectHashable lifecycle token whose work and reporting have drained.
Returns
NoneNo return value.
async def dispatchFailure(self, exception: BaseException, *, context: FailureContext) -> tuple[FailureReceipt, FailureHandling | None]: (source)

Select and complete failure effects without requesting presentation.

Allow explicitly invoked standalone handling without activating the runtime; normal framework observation enters through capture. Control-flow signals return an undelivered receipt and no plan without invoking application policy; exception groups remain intact.

Parameters
exception:BaseExceptionOriginal exception supplied to application policy.
context:FailureContextIncident metadata, with an event identifier allocated if needed.
Returns
tuple[FailureReceipt, FailureHandling | None]Delivery and logging status, followed by the selected plan, if any.
Raises
BaseExceptionIf cancellation or a control-flow error escapes application policy.
async def drain(self): (source)

Await owned callback reports until no pending report remains.

Include reports enqueued during draining. Return immediately from this runtime's application reporter or an adopted cleanup task to avoid self-deadlock. Yield after joining completed reports so their queued ownership callbacks can run.

Returns
NoneNo return value.
async def handlingFor(self, exception: BaseException, *, context: FailureContext) -> FailureHandling | None: (source)

Return the selected plan without observing the exception twice.

Wait for in-flight delivery and retry claims abandoned before execution.

Parameters
exception:BaseExceptionOriginal exception whose deferred handling is required.
context:FailureContextMetadata for observation or native fallback selection.
Returns
FailureHandling or NoneShared plan, or None when observation is inactive, reporting is recursive, or no plan is selected.
def hasOwner(self, owner: object) -> bool: (source)

Check whether an owner is active or still completing shutdown.

Parameters
owner:objectHashable lifecycle token to locate in the ownership sets.
Returns
boolTrue if the owner appears in either ownership set, otherwise False.
async def prepare(self): (source)

Resolve the application handler once outside operational scopes.

Returns
NoneNo return value.
async def presentHandling(self, handling: FailureHandling, exception: BaseException, *, context: FailureContext, request: object | None = None) -> object: (source)

Present a selected plan with bounded, nonrecursive failure handling.

Parameters
handling:FailureHandlingShared incident plan whose presentation must never be retried.
exception:BaseExceptionPrimary failure to preserve if presentation cannot complete.
context:FailureContextPresentation flow and incident metadata for emergency diagnostics.
request:object or None, optionalLive transport state, retained only by the selected plan.
Returns
objectSelected presentation result, or None on reporter reentry.
Raises
BaseExceptionThe primary failure if presentation fails or times out. Genuine caller cancellation and process-control signals propagate unchanged.
async def shutdown(self, *, exclude: asyncio.Task | None = None): (source)

Cancel owned application tasks and drain their failure reports.

Exclude the current task and return immediately from a reporting callback or adopted cleanup task to avoid self-deadlock. Concurrent callers share one cleanup task; cancelling a waiter does not cancel that cleanup. Keep admission closed until a subsequent valid activation or startup.

Parameters
exclude:asyncio.Task or None, optionalLifecycle owner awaiting this cleanup from another task. Exclude it to avoid cancelling and waiting on the task that owns this shutdown.
Returns
NoneNo return value.
async def start(self, owner: object): (source)

Activate an owner after earlier lifecycle transitions complete.

Parameters
owner:objectHashable token for the successfully started lifecycle.
Returns
NoneNo return value.
Raises
RuntimeErrorIf cleanup or its reporter attempts to await its own restart.
def stopReporting(self): (source)

Disable logging effects while retaining owner-based observation.

Returns
NoneNo return value.
_closing_owners: set[object] = (source)

Owners retaining observation while final resource closure completes.

_fallback_handler = (source)

Scope-free native policy selected after custom handling fails.

Serving loop used to schedule notification from native threads.

Active owners retaining the runtime's shared resources.

Loop-local reports and abandoned futures retained through cleanup.

_pending_lock = (source)

Serialize incident reservation and pending cross-thread registries.

_prepare_lock = (source)

Serialize preparation of the shared application handler.

_reporting_enabled: bool = (source)

Whether ordinary logging resources remain safe to use.

_shutdown_pending: asyncio.Task[None] | None = (source)

Shared shutdown coordinator retained only while cleanup is pending.

_shutting_down: bool = (source)

Reject new work until a valid activation reopens task admission.

Supervised application tasks cancelled and drained at final shutdown.

_thread_pending: set[ThreadFuture] = (source)

Submissions retained until ownership transfers to a loop-side task.

Application providing dependency resolution and hook invocation.

Prepared shared application handler, resolved lazily when absent.

lifecycle_lock = (source)

Coordinate runtime activation with final shared-resource closure.

Cooperative timeout in seconds for a reporting operation.

Check whether active or closing owners keep observation enabled.

Returns
boolTrue if either ownership set is nonempty, otherwise False.

Return the number of owners still holding resource ownership.

Returns
intCount of active owners, excluding owners already moved into closing.