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

Select logging and protocol presentation through one failure hook.

Method __init__ Initialize the BaseExceptionHandler instance.
Async Method __log Log an exception and its traceback as a single error record.
Async Method __present Present the exception only when its HTTP or CLI owner requests it.
Async Method handleCLI Render an exception immediately using the supplied console.
Async Method handleFailure Select default effects without logging or rendering during observation.
Async Method handleHTTP Render an exception immediately as an HTTP response.
Async Method handleResult Observe a declared failed result without creating an exception.
Method isExceptionIgnored Determine whether the given exception should be ignored.
Async Method report Log an exception immediately using the supplied logger.
Method toThrowable Convert an exception to a structured Throwable object.
Class Variable dont_catch Exceptions that should not be caught by the handler.
Instance Variable __application The application instance containing configuration and context.
Instance Variable __default_responses Default responses for HTTP error handling.
def __init__(self, default_responses: DefaultResponses, application: IApplication): (source)

Initialize the BaseExceptionHandler instance.

Parameters
default_responses:orionis.http.default.responses.DefaultResponsesDefault responses for HTTP error handling.
application:orionis.IApplicationThe application instance containing configuration and context.
Returns
NoneThis method does not return a value.
async def __log(self, exception: BaseException): (source)

Log an exception and its traceback as a single error record.

Preserve chained exceptions and notes using the original exception information, even when reporting outside an active except block.

Parameters
exception:BaseExceptionThe exception instance that was caught.
Returns
NoneNo return value.
async def __present(self, exception: BaseException, *, flow: str, request: Request | TransportAdapter | None = None) -> Response | None: (source)

Present the exception only when its HTTP or CLI owner requests it.

Parameters
exception:BaseExceptionThe exception instance that was caught.
flow:strProtocol whose execution owner requested presentation.
request:Request | TransportAdapter | NoneThe HTTP request instance or transport adapter that was being processed.
Returns
orionis.http.Response | NoneThe HTTP response if handled, otherwise None.
async def handleCLI(self, exception: BaseException, console: Console): (source)

Render an exception immediately using the supplied console.

Warning

Deprecated and will be removed in a future version. Override handleFailure and return a FailureHandling plan instead. Calling this method emits DeprecationWarning.

Parameters
exception:BaseExceptionThe exception instance that was caught.
console:orionis.console.output.console.ConsoleThe console instance for output.
Returns
NoneThis method does not return a value.
async def handleFailure(self, exception: BaseException, context: FailureContext) -> FailureHandling: (source)

Select default effects without logging or rendering during observation.

Notes

Return this plan from application overrides to preserve default effects. Logging runs after the hook returns; presentation runs only when the protocol owner requests it. Neither operation invokes this hook again.

Parameters
exception:BaseExceptionOriginal exception, including expected failures.
context:FailureContextImmutable origin, phase and correlation of the failure.
Returns
FailureHandlingLogging and presentation owned by this incident's execution.
async def handleHTTP(self, exception: BaseException, request: Request | TransportAdapter) -> Response | None: (source)

Render an exception immediately as an HTTP response.

Warning

Deprecated and will be removed in a future version. Override handleFailure and return a FailureHandling plan instead. Calling this method emits DeprecationWarning.

Parameters
exception:BaseExceptionThe exception instance that was caught.
request:Request | TransportAdapterThe HTTP request instance or transport adapter that was being processed.
Returns
orionis.http.Response | NoneThe HTTP response if handled, otherwise None when ignored.
async def handleResult(self, value: object, context: FailureContext) -> FailureHandling | None: (source)

Observe a declared failed result without creating an exception.

Notes

This default hook does not log or render. Application handlers may override it to apply policy without observing the outcome a second time.

Parameters
value:objectFailed outcome supplied by its execution owner.
context:FailureContextImmutable origin, phase and correlation of the outcome.
Returns
NoneNo return value.
def isExceptionIgnored(self, exception: BaseException) -> bool: (source)

Determine whether the given exception should be ignored.

Parameters
exception:BaseExceptionThe exception instance to check.
Returns
boolTrue if the exception should be ignored, otherwise False.
Raises
TypeErrorIf the supplied value is not an exception instance.
async def report(self, exception: BaseException, log: ILogger) -> Throwable | None: (source)

Log an exception immediately using the supplied logger.

Warning

Deprecated and will be removed in a future version. Override handleFailure and return a FailureHandling plan instead. Calling this method emits DeprecationWarning.

Parameters
exception:BaseExceptionThe exception instance that was caught.
log:orionis.logging.contracts.ILoggerThe logger instance for error reporting.
Returns
orionis.failure.entities.Throwable or NoneThe structured exception if reported, otherwise None when ignored.
def toThrowable(self, exception: BaseException) -> Throwable: (source)

Convert an exception to a structured Throwable object.

Parameters
exception:BaseExceptionException instance to be converted.
Returns
orionis.failure.entities.ThrowableStructured Throwable object containing class, message, arguments, and traceback.
dont_catch: ClassVar[frozenset[type[BaseException]]] = (source)

Exceptions that should not be caught by the handler.

__application = (source)

The application instance containing configuration and context.

__default_responses = (source)

Default responses for HTTP error handling.