API Reference#

This page contains technical details about the interface of core failures elements, this was directly and automatically generated from the source code, and contains links to switch between source code and documentation.

class failures.Failure(source: str, error: Exception, details: Dict[str, Any])[source]#

Failure is an object that encapsulates the error together with its source and additional details.

Parameters:

source – The dot separated labels leading to where the failure occurred,
error – The actual exception that caused the failure,
details – Additional user added metadata.

Create new instance of Failure(source, error, details)

source: str#: Alias for field number 0

error: Exception#: Alias for field number 1

details: Dict[str, Any]#: Alias for field number 2

class failures.FailureException(failure: Failure, reporter: Reporter)[source]#

FailureException is an exception that wraps failure details to be raised and captured by the caller without passing reporter objects between functions

The exception also keeps reference to the reporter object that raised it to get any registered failures and also avoid name duplication when the outer layer reporter captures the exception, as a rule the reporter that captures it only prepends its label if it wasn’t already prepended, this is done by checking if the source reporter shares the same root.

Parameters:

failure – Failure object containing the source, error and details
reporter – The reporter that raised this exception

class failures.Reporter(name: str, /, **details)[source]#

Reporters are objects used to collect failures (errors) between function calls and add context metadata and details, and pinpoint the source by labels.

Parameters:

name – The label for the current reporter (mandatory)
details – Additional details bound to the reporter

__call__(name: str, /, **details) → _ReporterChild[source]#

Creates a reporter child bound to the current one.

Parameters:

name – The label for the current reporter (mandatory)
details – Additional details bound to the reporter

Returns:

New reporter object

property parent: Reporter | None#: Gets the reporter’s parent if this was derived from one, or None instead

property root: Reporter#: Gets this reporter as it’s the first one

property name: str#: Gets the reporter’s name (without parent names)

property label: str#: Gets the name of the current reporter

property details: Dict[str, Any]#: Gets additional details bound to the reporter

property failures: List[Failure]#: Gets the failures’ list (mutable)

failure(error: Exception, **details) → Failure[source]#: Creates a failure from error, details and reporter’s information

report(error: Exception, **details) → None[source]#

Registers the failure into the shared failures list

Parameters:

error – Regular Exception or FailureException
details – Any additional details to be reported with the failure

Returns:

None

safe(func: ~typing.Callable[[~P], ~failures.core.T], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T | None[source]#: Calls func with args and kwargs inside a safe block and returns its result if it succeeds, or returns None and report the failure otherwise.

async safe_async(func: ~typing.Callable[[~P], ~typing.Awaitable[~failures.core.T]], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T | None[source]#: Calls await func with args and kwargs inside a safe block and returns its result if it succeeds, or returns None and report the failure otherwise.

static optional(func: ~typing.Callable[[~P], ~failures.core.T], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T | None[source]#: Calls func with args and kwargs inside a safe block and returns its result if it succeeds, or returns None and ignores the failure otherwise.

async static optional_async(func: ~typing.Callable[[~P], ~typing.Awaitable[~failures.core.T]], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T | None[source]#: Calls await func with args and kwargs inside a safe block and returns its result if it succeeds, or returns None and ignores the failure otherwise.

required(func: ~typing.Callable[[~P], ~failures.core.T], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T[source]#: Calls func with args and kwargs inside a safe block and returns its result if it succeeds, or raises a labeled failure otherwise.

async required_async(func: ~typing.Callable[[~P], ~typing.Awaitable[~failures.core.T]], /, *args: ~typing.~P, **kwargs: ~typing.~P) → T[source]#: Calls await func with args and kwargs inside a safe block and returns its result if it succeeds, or raises a labeled failure otherwise.

failures.scoped(func: Callable[[P], T], /) → Callable[[P], T][source]#

failures.scoped(name: str = ..., /) → Callable[[Callable[[P], T]], Callable[[P], T]]

Decorates functions to intercept any inner failures and add the function name to its label, and also add the function’s name to any reporter passed as argument to that function.

This decorator can be either parametrized or not.

>>> @scoped
... def function(*args, **kwargs):
...     pass

>>> @scoped('my_function')
... def function(*args, **kwargs):
...     pass

Handler object combines multiple filtered or unfiltered failure handlers together as a single failure handler, allowing the creation of complex failure handlers.

The handler is also a context manager, used with the with statement, it captures and automatically handles any raised FailureException.

The handler constructor optionally takes one or multiple failure handing functions (with signature (Failure)->None), the handlers also can be filtered to handle only a targeted group of failures.

To pass a filtered handler, put it inside a tuple followed with one or multiple filter like (func, (filter1, filter2, …)), so func will be called only if the failure matches any of filter1, filter2, …

Filtered handlers can also be more specific by combining filters like (func, (f1, f2), f3, (f4, f5, f6)), so func will only handle failures that match the filters: (f1 AND f2) OR f3 OR (f4 AND f5 AND f6)

Parameters:: args – A sequence of either func, (func, (filter, filter, …)) or (func, ((filter, filter), (…), …))

__call__(failure: Failure, /) → None[source]#: Handles the failure by calling the internal handler

from_reporter(reporter: Reporter) → None[source]#

Handles every failure registered by the reporter.

Parameters:: reporter – Reporter that holds failures
Returns:: None

failures.print_failure(failure: Failure, /) → None[source]#: Logs the failure to the standard output