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.
Observe failures only inside an activated application runtime.
Core imports use the standard library and failure entities. Cancelled-work cleanup lazily reuses the shared awaitable utility. Protocols keep ownership of responses, cancellation and recovery.
| Class | _ |
Reuse identical nested metadata without replacing or closing its owner. |
| Class | _ |
Allocation-free context when no application observation is active. |
| Class | _ |
Keep deferred effects and their completion inside an operation ledger. |
| Class | _ |
Own an error-only ledger for one execution and its nested boundaries. |
| Class | _ |
Transfer report ownership from a worker submission to its loop task. |
| Class | |
Own one application's handler, active lifetimes and pending reports. |
| Async Function | _cancellation |
Deliver pending caller cancellation before entering a protected reporter. |
| Function | _completed |
Return a completed receipt future for the caller's event-loop context. |
| Function | _context |
Build failure metadata using compatible operation defaults. |
| Function | _emergency |
Write fallback diagnostics without exposing exception messages. |
| Function | _find |
Find an owned runtime without resolving a global facade. |
| Function | _handler |
Detach request and operation scopes while resolving shared handlers. |
| Function | _parent |
Link a secondary failure to an already observed cause. |
| Function | _pending |
Claim or reuse callback incident identity while its operation is live. |
| Function | _previous |
Reuse a direct incident receipt or an already observed group's receipt. |
| Function | _runtime |
Return the live operation only when it belongs to the supplied runtime. |
| Function | _submit |
Admit a callback report on its running loop and retain task ownership. |
| Async Function | capture |
Observe an exception through an active application runtime. |
| Function | capture |
Schedule supervised exception observation from a callback or worker. |
| Async Function | capture |
Observe a declared failed result through an active runtime. |
| Function | current |
Return the live operation bound to the current context. |
| Function | get |
Return the active runtime for an application or current operation. |
| Function | handoff |
Transfer an observed incident to its awaiting operation owner. |
| Function | is |
Check whether the current context is executing a failure reporter. |
| Function | operation |
Bind or reuse an execution context for failure observation. |
| Async Function | prepare |
Resolve an application's failure runtime without activating observation. |
| Function | reporting |
Bind a reporter identity while processing its queued log record. |
| Function | reporting |
Return the reporter identity bound to the current context. |
| Constant | _CONTROL |
Control-flow signals excluded from application failure reporting. |
| Variable | _borrowed |
Shared context manager for an identical nested operation. |
| Variable | _current |
Current operation carrying the application-local incident ledger. |
| Variable | _inactive |
Shared no-op boundary used when observation is inactive. |
| Variable | _reporting |
Runtime executing reporting effects, used to prevent recursive delivery. |
Deliver pending caller cancellation before entering a protected reporter.
| Returns | |
int | Cancellation requests already consumed by the caller. A later internal CancelledError must not be mistaken for one of these old requests. |
| Raises | |
asyncio.CancelledError | If a cancellation request is still pending at the checkpoint. |
asyncio.AbstractEventLoop, running: asyncio.AbstractEventLoop | None, receipt: FailureReceipt) -> asyncio.Future | ThreadFuture:
(source)
¶
Return a completed receipt future for the caller's event-loop context.
| Parameters | |
loop:asyncio.AbstractEventLoop | Runtime event loop used for same-loop callers. |
running:asyncio.AbstractEventLoop or None | Caller's event loop, or None outside an async event loop. |
receipt:FailureReceipt | Delivery status used to complete the returned future. |
| Returns | |
asyncio.Future or concurrent.futures.Future | Completed asyncio future on the runtime loop, or a thread-safe future for callers outside that loop. |
FailureRuntime, flow: str, phase: str, operation: str | None, correlation_id: str | None, expected: bool, metadata: Mapping[ str, object] | None, parent_event_id: str | None = None) -> FailureContext:
(source)
¶
Build failure metadata using compatible operation defaults.
| Parameters | |
runtime:FailureRuntime | Runtime whose current operation can supply inherited metadata. |
flow:str | Flow label; inherit the current flow when set to "runtime". |
phase:str | Failure phase to record. |
operation:str or None | Explicit operation name, or None to inherit the current name. |
correlationstr or None | Explicit correlation identifier, or None to inherit one. |
expected:bool | Whether the execution owner classifies this as an expected failure. |
metadata:collections.abc.Mapping[str, object] or None | Additional incident metadata to sanitize, or None for no metadata. |
parentstr or None, optional | Explicit causal incident transferred across an asynchronous boundary. |
| Returns | |
FailureContext | Immutable, sanitized context enriched by the current matching operation. |
BaseException | None, context: FailureContext, secondary: BaseException | None = None):
(source)
¶
Write fallback diagnostics without exposing exception messages.
| Parameters | |
exception:BaseException or None | Failure whose type is reported, or None for a failed result. |
context:FailureContext | Incident metadata supplying the event identifier. |
secondary:BaseException or None, optional | Reporting failure whose type is included in the diagnostic. |
| Returns | |
None | No return value. |
Find an owned runtime without resolving a global facade.
| Parameters | |
app:object or None, optional | Application to inspect; use the current operation only when None. |
| Returns | |
FailureRuntime or None | Runtime attached to the application or current operation, regardless of activation state, or None if unavailable. |
Detach request and operation scopes while resolving shared handlers.
| Yields | |
None | Enter a scope-free context and restore the previous contexts on exit. |
BaseException, context: FailureContext, current: _Operation | None) -> FailureContext:
(source)
¶
Link a secondary failure to an already observed cause.
| Parameters | |
exception:BaseException | Failure whose explicit cause or implicit context may have been observed. |
context:FailureContext | Metadata to enrich when no parent event is already set. |
current:_Operation or None | Operation used to look up the causal failure. |
| Returns | |
FailureContext | Context with the cause's event identifier, or the original context when no link can be added. |
FailureRuntime, exception: BaseException, context: FailureContext) -> tuple[ FailureContext, _Incident | None, FailureReceipt | None]:
(source)
¶
Claim or reuse callback incident identity while its operation is live.
| Parameters | |
runtime:FailureRuntime | Runtime owning the pending report and its claim lock. |
exception:BaseException | Original exception whose identity must be claimed before scheduling. |
context:FailureContext | Metadata to enrich for a new or reclaimed incident. |
| Returns | |
tuple[FailureContext, _Incident | None, FailureReceipt | None] | Resolved context, pending incident, and duplicate receipt; the final two entries are mutually exclusive. |
BaseException, current: _Operation | None, incident: _Incident | None) -> FailureReceipt | None:
(source)
¶
Reuse a direct incident receipt or an already observed group's receipt.
| Parameters | |
exception:BaseException | Exception or exception group to look up. |
current:_Operation or None | Operation supplying the ledger when no direct incident is available. |
incident:_Incident or None | Previously located incident, if any. |
| Returns | |
FailureReceipt or None | Existing incident or ledger receipt, or None when neither is available. |
Return the live operation only when it belongs to the supplied runtime.
| Parameters | |
runtime:FailureRuntime | Runtime whose current operation is required. |
| Returns | |
_Operation or None | Live operation associated with this runtime, or None. |
FailureRuntime, loop: asyncio.AbstractEventLoop, exception: BaseException, context: FailureContext, incident: _Incident) -> asyncio.Task | None:
(source)
¶
Admit a callback report on its running loop and retain task ownership.
| Parameters | |
runtime:FailureRuntime | Runtime that owns the report and incident ledger. |
loop:asyncio.AbstractEventLoop | Running event loop accepting the reporting coroutine. |
exception:BaseException | Original failure to observe. |
context:FailureContext | Metadata allocated before admission. |
incident:_Incident | Claimed incident to abandon if admission fails. |
| Returns | |
asyncio.Task or None | Owned reporting task, or None after an ordinary admission failure. |
| Raises | |
BaseException | If admission raises a control-flow signal after cleanup. |
BaseException, *, app: object | None = None, runtime: FailureRuntime | None = None, flow: str = 'runtime', phase: str = 'execution', operation: str | None = None, correlation_id: str | None = None, parent_event_id: str | None = None, expected: bool = False, metadata: Mapping[ str, object] | None = None) -> FailureReceipt | None:
(source)
¶
Observe an exception through an active application runtime.
Inherit flow, operation name, and correlation from a matching operation when their default values are used. Leave presentation and recovery to the caller.
| Parameters | |
exception:BaseException | Original exception instance to observe. |
app:object or None, optional | Application used to locate a runtime when none is supplied. |
runtime:FailureRuntime or None, optional | Explicit runtime; otherwise resolve one from the application or operation. |
flow:str, optional | Execution-flow label; inherit the current flow when "runtime". |
phase:str, optional | Failure phase. Defaults to "execution". |
operation:str or None, optional | Logical operation name; inherit the current name when None. |
correlationstr or None, optional | Correlation identifier; inherit the current value when None. |
parentstr or None, optional | Causal incident identifier supplied by an owner transferring cleanup across a task boundary without modifying the exception's Python chain. |
expected:bool, default False | Mark the failure as expected for reporting policy. |
metadata:collections.abc.Mapping[str, object] or None, optional | Additional incident metadata to copy, bound, and redact. |
| Returns | |
FailureReceipt or None | Delivery status, or None when no runtime is active or the failure represents cancellation or process control. |
| Raises | |
BaseException | If observation is interrupted by cancellation or a reporting-path control-flow exception. |
BaseException, *, app: object | None = None, runtime: FailureRuntime | None = None, flow: str = 'runtime', phase: str = 'execution', operation: str | None = None, correlation_id: str | None = None, expected: bool = False, metadata: Mapping[ str, object] | None = None) -> asyncio.Future | ThreadFuture | None:
(source)
¶
Schedule supervised exception observation from a callback or worker.
Claim incident identity before scheduling delivery on the runtime loop. Return completed futures for recursive or duplicate observations.
| Parameters | |
exception:BaseException | Original exception instance to observe. |
app:object or None, optional | Application used to locate a runtime when none is supplied. |
runtime:FailureRuntime or None, optional | Explicit runtime; otherwise resolve one from the application or operation. |
flow:str, optional | Execution-flow label; inherit the current flow when "runtime". |
phase:str, optional | Failure phase. Defaults to "execution". |
operation:str or None, optional | Logical operation name; inherit the current name when None. |
correlationstr or None, optional | Correlation identifier; inherit the current value when None. |
expected:bool, default False | Mark the failure as expected for reporting policy. |
metadata:collections.abc.Mapping[str, object] or None, optional | Additional incident metadata to copy, bound, and redact. |
| Returns | |
asyncio.Task or asyncio.Future or concurrent.futures.Future or None | Supervised report task or receipt future, or None when observation is inactive, the exception is a control signal, or admission cannot be scheduled. Cross-thread callers receive a thread-safe future; cancelling it preserves ownership of admitted work until its cleanup completes. |
object, *, app: object | None = None, runtime: FailureRuntime | None = None, flow: str = 'runtime', phase: str = 'result', operation: str | None = None, correlation_id: str | None = None, expected: bool = True, metadata: Mapping[ str, object] | None = None) -> FailureReceipt | None:
(source)
¶
Observe a declared failed result through an active runtime.
Preserve the result without synthesizing an exception or traceback.
| Parameters | |
value:object | Original result classified as a failure by its execution owner. |
app:object or None, optional | Application used to locate a runtime when none is supplied. |
runtime:FailureRuntime or None, optional | Explicit runtime; otherwise resolve one from the application or operation. |
flow:str, optional | Execution-flow label; inherit the current flow when "runtime". |
phase:str, optional | Failure phase. Defaults to "result". |
operation:str or None, optional | Logical operation name; inherit the current name when None. |
correlationstr or None, optional | Correlation identifier; inherit the current value when None. |
expected:bool, default True | Mark the result as expected for reporting policy. |
metadata:collections.abc.Mapping[str, object] or None, optional | Additional incident metadata to copy, bound, and redact. |
| Returns | |
FailureReceipt or None | Delivery and reporting status, or None when no runtime is active. |
| Raises | |
BaseException | If cancellation or a control-flow error escapes application policy. |
Return the live operation bound to the current context.
| Returns | |
_Operation or None | Current operation, or None when no live operation is bound. |
Return the active runtime for an application or current operation.
| Parameters | |
app:object or None, optional | Application to inspect; use the current operation only when None. |
| Returns | |
FailureRuntime or None | Resolved runtime if active, otherwise None. |
BaseException, *, target: _Operation | None, receipt: FailureReceipt | None = None) -> bool:
(source)
¶
Transfer an observed incident to its awaiting operation owner.
Reuse incident identity instead of mutating the exception.
| Parameters | |
exception:BaseException | Original exception whose delivery record is being transferred. |
target:_Operation or None | Destination operation; reject unavailable or closed targets. |
receipt:FailureReceipt or None, optional | Known receipt; otherwise look up the receipt in the current operation. |
| Returns | |
bool | True when a receipt can be handed to the live, compatible target, otherwise False. |
Check whether the current context is executing a failure reporter.
| Returns | |
bool | True if a reporting runtime is bound, otherwise False. |
object | None = None, *, runtime: FailureRuntime | None = None, flow: str = 'runtime', operation: str | None = None, correlation_id: str | None = None, isolated: bool = False) -> _Operation | _InactiveOperation | _BorrowedOperation:
(source)
¶
Bind or reuse an execution context for failure observation.
Allocate a ledger only when an incident is observed. Never capture or suppress exceptions; callers must report before consuming a failure.
| Parameters | |
app:object or None, optional | Application owning the runtime; use the current operation when omitted. |
runtime:FailureRuntime or None, optional | Explicit runtime taking precedence over application-based resolution. |
flow:str, optional | Execution-flow label. Defaults to "runtime". |
operation:str or None, optional | Logical operation name, if known. |
correlationstr or None, optional | Correlation identifier shared by related incidents, if supplied. |
isolated:bool, default False | Own a separate incident ledger instead of sharing the parent ledger. |
| Returns | |
_Operation or _InactiveOperation or _BorrowedOperation | Owned or borrowed context manager, or a no-op context if observation is inactive. |
Resolve an application's failure runtime without activating observation.
| Parameters | |
app:object | Application whose configured exception handler should be prepared. |
| Returns | |
FailureRuntime or None | Prepared runtime, or None if no runtime exists and the application is uncreated or lacks a catch binding. |
Bind a reporter identity while processing its queued log record.
| Parameters | |
runtime:FailureRuntime | Runtime whose reporter identity should be restored for the sink. |
| Yields | |
None | Keep the runtime bound for the block and restore the previous identity on exit. |
Return the reporter identity bound to the current context.
| Returns | |
FailureRuntime or None | Current reporting runtime, or None outside reporter execution. |
Control-flow signals excluded from application failure reporting.
| Value |
|