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.

module documentation

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 _BorrowedOperation Reuse identical nested metadata without replacing or closing its owner.
Class _InactiveOperation Allocation-free context when no application observation is active.
Class _Incident Keep deferred effects and their completion inside an operation ledger.
Class _Operation Own an error-only ledger for one execution and its nested boundaries.
Class _ThreadReport Transfer report ownership from a worker submission to its loop task.
Class FailureRuntime Own one application's handler, active lifetimes and pending reports.
Async Function _cancellation_checkpoint Deliver pending caller cancellation before entering a protected reporter.
Function _completed_receipt 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_runtime Find an owned runtime without resolving a global facade.
Function _handler_dependencies Detach request and operation scopes while resolving shared handlers.
Function _parent_context Link a secondary failure to an already observed cause.
Function _pending_incident Claim or reuse callback incident identity while its operation is live.
Function _previous_receipt Reuse a direct incident receipt or an already observed group's receipt.
Function _runtime_operation Return the live operation only when it belongs to the supplied runtime.
Function _submit_loop 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_nowait Schedule supervised exception observation from a callback or worker.
Async Function capture_result Observe a declared failed result through an active runtime.
Function current_operation Return the live operation bound to the current context.
Function get_runtime Return the active runtime for an application or current operation.
Function handoff Transfer an observed incident to its awaiting operation owner.
Function is_reporting 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_from Bind a reporter identity while processing its queued log record.
Function reporting_runtime Return the reporter identity bound to the current context.
Constant _CONTROL_EXCEPTIONS Control-flow signals excluded from application failure reporting.
Variable _borrowed_operation Shared context manager for an identical nested operation.
Variable _current Current operation carrying the application-local incident ledger.
Variable _inactive_operation Shared no-op boundary used when observation is inactive.
Variable _reporting Runtime executing reporting effects, used to prevent recursive delivery.
async def _cancellation_checkpoint() -> int: (source)

Deliver pending caller cancellation before entering a protected reporter.

Returns
intCancellation requests already consumed by the caller. A later internal CancelledError must not be mistaken for one of these old requests.
Raises
asyncio.CancelledErrorIf a cancellation request is still pending at the checkpoint.
def _completed_receipt(loop: 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.AbstractEventLoopRuntime event loop used for same-loop callers.
running:asyncio.AbstractEventLoop or NoneCaller's event loop, or None outside an async event loop.
receipt:FailureReceiptDelivery status used to complete the returned future.
Returns
asyncio.Future or concurrent.futures.FutureCompleted asyncio future on the runtime loop, or a thread-safe future for callers outside that loop.
def _context(*, runtime: 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:FailureRuntimeRuntime whose current operation can supply inherited metadata.
flow:strFlow label; inherit the current flow when set to "runtime".
phase:strFailure phase to record.
operation:str or NoneExplicit operation name, or None to inherit the current name.
correlation_id:str or NoneExplicit correlation identifier, or None to inherit one.
expected:boolWhether the execution owner classifies this as an expected failure.
metadata:collections.abc.Mapping[str, object] or NoneAdditional incident metadata to sanitize, or None for no metadata.
parent_event_id:str or None, optionalExplicit causal incident transferred across an asynchronous boundary.
Returns
FailureContextImmutable, sanitized context enriched by the current matching operation.
def _emergency(exception: BaseException | None, context: FailureContext, secondary: BaseException | None = None): (source)

Write fallback diagnostics without exposing exception messages.

Parameters
exception:BaseException or NoneFailure whose type is reported, or None for a failed result.
context:FailureContextIncident metadata supplying the event identifier.
secondary:BaseException or None, optionalReporting failure whose type is included in the diagnostic.
Returns
NoneNo return value.
def _find_runtime(app: object | None = None) -> FailureRuntime | None: (source)

Find an owned runtime without resolving a global facade.

Parameters
app:object or None, optionalApplication to inspect; use the current operation only when None.
Returns
FailureRuntime or NoneRuntime attached to the application or current operation, regardless of activation state, or None if unavailable.
def _handler_dependencies() -> Generator[None]: (source)

Detach request and operation scopes while resolving shared handlers.

Yields
NoneEnter a scope-free context and restore the previous contexts on exit.
def _parent_context(exception: BaseException, context: FailureContext, current: _Operation | None) -> FailureContext: (source)

Link a secondary failure to an already observed cause.

Parameters
exception:BaseExceptionFailure whose explicit cause or implicit context may have been observed.
context:FailureContextMetadata to enrich when no parent event is already set.
current:_Operation or NoneOperation used to look up the causal failure.
Returns
FailureContextContext with the cause's event identifier, or the original context when no link can be added.
def _pending_incident(runtime: 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:FailureRuntimeRuntime owning the pending report and its claim lock.
exception:BaseExceptionOriginal exception whose identity must be claimed before scheduling.
context:FailureContextMetadata 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.
def _previous_receipt(exception: BaseException, current: _Operation | None, incident: _Incident | None) -> FailureReceipt | None: (source)

Reuse a direct incident receipt or an already observed group's receipt.

Parameters
exception:BaseExceptionException or exception group to look up.
current:_Operation or NoneOperation supplying the ledger when no direct incident is available.
incident:_Incident or NonePreviously located incident, if any.
Returns
FailureReceipt or NoneExisting incident or ledger receipt, or None when neither is available.
def _runtime_operation(runtime: FailureRuntime) -> _Operation | None: (source)

Return the live operation only when it belongs to the supplied runtime.

Parameters
runtime:FailureRuntimeRuntime whose current operation is required.
Returns
_Operation or NoneLive operation associated with this runtime, or None.
def _submit_loop(runtime: 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:FailureRuntimeRuntime that owns the report and incident ledger.
loop:asyncio.AbstractEventLoopRunning event loop accepting the reporting coroutine.
exception:BaseExceptionOriginal failure to observe.
context:FailureContextMetadata allocated before admission.
incident:_IncidentClaimed incident to abandon if admission fails.
Returns
asyncio.Task or NoneOwned reporting task, or None after an ordinary admission failure.
Raises
BaseExceptionIf admission raises a control-flow signal after cleanup.
async def capture(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, 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:BaseExceptionOriginal exception instance to observe.
app:object or None, optionalApplication used to locate a runtime when none is supplied.
runtime:FailureRuntime or None, optionalExplicit runtime; otherwise resolve one from the application or operation.
flow:str, optionalExecution-flow label; inherit the current flow when "runtime".
phase:str, optionalFailure phase. Defaults to "execution".
operation:str or None, optionalLogical operation name; inherit the current name when None.
correlation_id:str or None, optionalCorrelation identifier; inherit the current value when None.
parent_event_id:str or None, optionalCausal incident identifier supplied by an owner transferring cleanup across a task boundary without modifying the exception's Python chain.
expected:bool, default FalseMark the failure as expected for reporting policy.
metadata:collections.abc.Mapping[str, object] or None, optionalAdditional incident metadata to copy, bound, and redact.
Returns
FailureReceipt or NoneDelivery status, or None when no runtime is active or the failure represents cancellation or process control.
Raises
BaseExceptionIf observation is interrupted by cancellation or a reporting-path control-flow exception.
def capture_nowait(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:BaseExceptionOriginal exception instance to observe.
app:object or None, optionalApplication used to locate a runtime when none is supplied.
runtime:FailureRuntime or None, optionalExplicit runtime; otherwise resolve one from the application or operation.
flow:str, optionalExecution-flow label; inherit the current flow when "runtime".
phase:str, optionalFailure phase. Defaults to "execution".
operation:str or None, optionalLogical operation name; inherit the current name when None.
correlation_id:str or None, optionalCorrelation identifier; inherit the current value when None.
expected:bool, default FalseMark the failure as expected for reporting policy.
metadata:collections.abc.Mapping[str, object] or None, optionalAdditional incident metadata to copy, bound, and redact.
Returns
asyncio.Task or asyncio.Future or concurrent.futures.Future or NoneSupervised 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.
async def capture_result(value: 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:objectOriginal result classified as a failure by its execution owner.
app:object or None, optionalApplication used to locate a runtime when none is supplied.
runtime:FailureRuntime or None, optionalExplicit runtime; otherwise resolve one from the application or operation.
flow:str, optionalExecution-flow label; inherit the current flow when "runtime".
phase:str, optionalFailure phase. Defaults to "result".
operation:str or None, optionalLogical operation name; inherit the current name when None.
correlation_id:str or None, optionalCorrelation identifier; inherit the current value when None.
expected:bool, default TrueMark the result as expected for reporting policy.
metadata:collections.abc.Mapping[str, object] or None, optionalAdditional incident metadata to copy, bound, and redact.
Returns
FailureReceipt or NoneDelivery and reporting status, or None when no runtime is active.
Raises
BaseExceptionIf cancellation or a control-flow error escapes application policy.
def current_operation() -> _Operation | None: (source)

Return the live operation bound to the current context.

Returns
_Operation or NoneCurrent operation, or None when no live operation is bound.
def get_runtime(app: object | None = None) -> FailureRuntime | None: (source)

Return the active runtime for an application or current operation.

Parameters
app:object or None, optionalApplication to inspect; use the current operation only when None.
Returns
FailureRuntime or NoneResolved runtime if active, otherwise None.
def handoff(exception: 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:BaseExceptionOriginal exception whose delivery record is being transferred.
target:_Operation or NoneDestination operation; reject unavailable or closed targets.
receipt:FailureReceipt or None, optionalKnown receipt; otherwise look up the receipt in the current operation.
Returns
boolTrue when a receipt can be handed to the live, compatible target, otherwise False.
def is_reporting() -> bool: (source)

Check whether the current context is executing a failure reporter.

Returns
boolTrue if a reporting runtime is bound, otherwise False.
def operation(app: 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, optionalApplication owning the runtime; use the current operation when omitted.
runtime:FailureRuntime or None, optionalExplicit runtime taking precedence over application-based resolution.
flow:str, optionalExecution-flow label. Defaults to "runtime".
operation:str or None, optionalLogical operation name, if known.
correlation_id:str or None, optionalCorrelation identifier shared by related incidents, if supplied.
isolated:bool, default FalseOwn a separate incident ledger instead of sharing the parent ledger.
Returns
_Operation or _InactiveOperation or _BorrowedOperationOwned or borrowed context manager, or a no-op context if observation is inactive.
async def prepare(app: object) -> FailureRuntime | None: (source)

Resolve an application's failure runtime without activating observation.

Parameters
app:objectApplication whose configured exception handler should be prepared.
Returns
FailureRuntime or NonePrepared runtime, or None if no runtime exists and the application is uncreated or lacks a catch binding.
def reporting_from(runtime: FailureRuntime) -> Generator[None]: (source)

Bind a reporter identity while processing its queued log record.

Parameters
runtime:FailureRuntimeRuntime whose reporter identity should be restored for the sink.
Yields
NoneKeep the runtime bound for the block and restore the previous identity on exit.
def reporting_runtime() -> FailureRuntime | None: (source)

Return the reporter identity bound to the current context.

Returns
FailureRuntime or NoneCurrent reporting runtime, or None outside reporter execution.
_CONTROL_EXCEPTIONS = (source)

Control-flow signals excluded from application failure reporting.

Value
(asyncio.CancelledError, KeyboardInterrupt, SystemExit, GeneratorExit)
_borrowed_operation = (source)

Shared context manager for an identical nested operation.

Current operation carrying the application-local incident ledger.

_inactive_operation = (source)

Shared no-op boundary used when observation is inactive.

Runtime executing reporting effects, used to prevent recursive delivery.