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.
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 | _complete |
Complete selected logging effects without requesting presentation. |
| Method | _correlate |
Assign operation correlation lazily when recording a failure. |
| Async Method | _default |
Select native failure effects after application policy fails. |
| Async Method | _drain |
Settle owned work and reports while admission remains closed. |
| Async Method | _fallback |
Share native presentation planning for an incident without a plan. |
| Method | _finish |
Cancel abandoned work and retain local futures until cleanup completes. |
| Async Method | _invoke |
Invoke an application handler method within the reporting timeout. |
| Method | _record |
Record a new or reclaimed incident before invoking a handler. |
| Method | _settle |
Release completed cleanup and observe only unsupervised failures. |
| Method | _shutdown |
Release the coordinator context and retrieve an unclaimed failure. |
| Method | activate |
Register a started owner and record the current event loop. |
| Method | begin |
Move an owner into closing while retaining cleanup observation. |
| Async Method | capture |
Observe an original exception once per operation. |
| Async Method | capture |
Observe a declared failed result without constructing an exception. |
| Method | create |
Create and supervise application work until shutdown. |
| Method | deactivate |
Release active and closing ownership for a lifecycle token. |
| Async Method | dispatch |
Select and complete failure effects without requesting presentation. |
| Async Method | drain |
Await owned callback reports until no pending report remains. |
| Async Method | handling |
Return the selected plan without observing the exception twice. |
| Method | has |
Check whether an owner is active or still completing shutdown. |
| Async Method | prepare |
Resolve the application handler once outside operational scopes. |
| Async Method | present |
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 | stop |
Disable logging effects while retaining owner-based observation. |
| Instance Variable | _closing |
Owners retaining observation while final resource closure completes. |
| Instance Variable | _fallback |
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 |
Serialize incident reservation and pending cross-thread registries. |
| Instance Variable | _prepare |
Serialize preparation of the shared application handler. |
| Instance Variable | _reporting |
Whether ordinary logging resources remain safe to use. |
| Instance Variable | _shutdown |
Shared shutdown coordinator retained only while cleanup is pending. |
| Instance Variable | _shutting |
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 |
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 |
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 | owner |
Return the number of owners still holding resource ownership. |
Initialize runtime ownership, reporting state, and task registries.
| Parameters | |
app:object | Application providing handler resolution, construction, and invocation. |
handler:object or None, optional | Pre-resolved failure handler; resolve lazily when omitted. |
timeout:float, optional | Maximum seconds allowed for each handler or logging action. Defaults to 5.0. |
| Returns | |
None | No return value. |
str, original: BaseException | None, incident: FailureContext, **kwargs: object) -> tuple[ bool, FailureHandling | None]:
(source)
¶
Select and validate deferred effects through an application hook.
| Parameters | |
method:str | Application failure-handler method to invoke. |
original:BaseException or None | Original exception for fallback diagnostics, or None for a result. |
incident:FailureContext | Incident metadata used if application policy fails. |
**kwargs:object | Keyword 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 | |
BaseException | If caller cancellation or another control-flow exception must propagate. |
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:BaseException | Original exception whose incident identity is being claimed. |
context:FailureContext | Metadata supplied for the observation attempt. |
claimed:_Incident or None, optional | Callback 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. |
FailureHandling | None, exception: BaseException | None, context: FailureContext) -> tuple[ bool, bool]:
(source)
¶
Complete selected logging effects without requesting presentation.
| Parameters | |
handling:FailureHandling or None | Deferred plan to complete, or None for observation without effects. |
exception:BaseException or None | Original failure, or None for a failed result. |
context:FailureContext | Metadata controlling whether reporting is allowed or expected. |
| Returns | |
tuple[bool, bool] | Reported and degraded status flags, respectively. |
| Raises | |
BaseException | If caller cancellation or another control-flow exception must propagate. |
Assign operation correlation lazily when recording a failure.
| Parameters | |
context:FailureContext | Metadata to correlate with the current operation for this runtime. |
| Returns | |
FailureContext | Context carrying an existing or newly allocated correlation identifier, or the original context when correlation is already set or unavailable. |
BaseException, context: FailureContext) -> FailureHandling | None:
(source)
¶
Select native failure effects after application policy fails.
| Parameters | |
exception:BaseException | Original failure to pass to the native exception handler. |
context:FailureContext | Incident metadata controlling the fallback policy. |
| Returns | |
FailureHandling or None | Native handling plan, or None when no plan can be selected. |
| Raises | |
BaseException | If caller cancellation or another control-flow exception must propagate. |
Settle owned work and reports while admission remains closed.
| Parameters | |
excluded:frozenset[asyncio.Task] | Lifecycle owners that are waiting for this coordinator. |
| Returns | |
None | No return value. |
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:BaseException | Previously observed exception requiring presentation policy. |
context:FailureContext | Metadata passed to fallback policy with reporting disabled. |
receipt:FailureReceipt | Existing delivery status used for the fallback claim. |
current:_Operation or None | Operation that can retain the fallback incident. |
incident:_Incident or None | Existing incident, or None to create a shared fallback claim. |
| Returns | |
FailureHandling or None | Native handling plan, or None when fallback selection yields no plan. |
object, *, supervised: bool, on_error: Callable[ [ BaseException], object]):
(source)
¶
Cancel abandoned work and retain local futures until cleanup completes.
| Parameters | |
awaitable:object | Application work whose supervising wrapper was cancelled. |
supervised:bool | Whether this runtime already owned the future at wrapper registration. |
oncollections.abc.Callable[[BaseException], object] | Central observer for original cleanup failures. |
| Returns | |
None | No return value. |
Invoke an application handler method within the reporting timeout.
| Parameters | |
method:str | Name of the configured failure-handler method to invoke. |
**kwargs:object | Keyword arguments passed through application dependency injection. |
| Returns | |
object | Value returned by the selected handler method. |
| Raises | |
TimeoutError | If handler preparation or invocation exceeds the configured timeout. |
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:BaseException | Original exception to retain in the incident. |
context:FailureContext | Metadata to enrich with event, correlation, and parent identifiers. |
current:_Operation or None | Current operation that can retain the incident. |
incident:_Incident or None | Reclaimed incident, or None to create one. |
| Returns | |
tuple[FailureContext, FailureReceipt, _Incident] | Enriched context, fresh receipt, and incident marked as started. |
asyncio.Future, *, supervised: bool, on_error: Callable[ [ BaseException], object]):
(source)
¶
Release completed cleanup and observe only unsupervised failures.
| Parameters | |
completed:asyncio.Future | Adopted local future whose cleanup has reached a terminal state. |
supervised:bool | Whether another runtime observer already owns this failure. |
oncollections.abc.Callable[[BaseException], object] | Central observer for original cleanup failures. |
| Returns | |
None | No return value. |
Release the coordinator context and retrieve an unclaimed failure.
| Parameters | |
completed:asyncio.Task[None] | Shared shutdown coordinator that finished or was cancelled. |
| Returns | |
None | No return value. |
Register a started owner and record the current event loop.
| Parameters | |
owner:object | Hashable lifecycle token whose startup completed. |
| Returns | |
None | No return value. |
| Raises | |
RuntimeError | If no event loop is running or earlier shutdown is still pending. |
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:BaseException | Original exception instance to observe. |
context:FailureContext | Execution metadata for the incident. |
_incident:_Incident or None, optional | Incident claimed by a callback before asynchronous delivery. |
| Returns | |
FailureReceipt or None | Delivery receipt, including duplicate status, or None when inactive or when the exception represents cancellation or process control. |
| Raises | |
BaseException | If delivery is interrupted by caller cancellation or a control-flow failure in the reporting path. |
object, *, context: FailureContext) -> FailureReceipt | None:
(source)
¶
Observe a declared failed result without constructing an exception.
| Parameters | |
value:object | Original result classified as a failure by its execution owner. |
context:FailureContext | Execution metadata for the failed result. |
| Returns | |
FailureReceipt or None | Delivery and reporting status, or None when the runtime is inactive. |
| Raises | |
BaseException | If cancellation or a control-flow error escapes application policy. |
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:object | Awaitable application work whose failures must be observed. |
name:str or None, optional | Task name and operation label for failure observation. |
| Returns | |
asyncio.Task | Supervised task registered for cancellation during runtime shutdown. |
| Raises | |
RuntimeError | If no event loop is running. |
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:BaseException | Original exception supplied to application policy. |
context:FailureContext | Incident 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 | |
BaseException | If cancellation or a control-flow error escapes application policy. |
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 | |
None | No return value. |
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:BaseException | Original exception whose deferred handling is required. |
context:FailureContext | Metadata for observation or native fallback selection. |
| Returns | |
FailureHandling or None | Shared plan, or None when observation is inactive, reporting is recursive, or no plan is selected. |
FailureHandling, exception: BaseException, *, context: FailureContext, request: object | None = None) -> object:
(source)
¶
Present a selected plan with bounded, nonrecursive failure handling.
| Parameters | |
handling:FailureHandling | Shared incident plan whose presentation must never be retried. |
exception:BaseException | Primary failure to preserve if presentation cannot complete. |
context:FailureContext | Presentation flow and incident metadata for emergency diagnostics. |
request:object or None, optional | Live transport state, retained only by the selected plan. |
| Returns | |
object | Selected presentation result, or None on reporter reentry. |
| Raises | |
BaseException | The primary failure if presentation fails or times out. Genuine caller cancellation and process-control signals propagate unchanged. |
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, optional | Lifecycle owner awaiting this cleanup from another task. Exclude it to avoid cancelling and waiting on the task that owns this shutdown. |
| Returns | |
None | No return value. |
Activate an owner after earlier lifecycle transitions complete.
| Parameters | |
owner:object | Hashable token for the successfully started lifecycle. |
| Returns | |
None | No return value. |
| Raises | |
RuntimeError | If cleanup or its reporter attempts to await its own restart. |
Check whether active or closing owners keep observation enabled.
| Returns | |
bool | True if either ownership set is nonempty, otherwise False. |