Reference

Core

exception izulu.root.Error(**kwargs: Any)

Base class for your exception trees.

Example:

class MyError(root.Error):
    __template__ = "{smth} has happened at {ts}"

    smth: str
    ts: root.factory(datetime.now)

Provides 4 main features:

• Instead of manual error message formatting (and copying it all over the codebase) provide just kwargs:

  • before: raise MyError(f"{smth} has happened at {datetime.now()}")

  • after: raise MyError(smth=smth)

  Provide __template__ class attribute with your error message template string. New style formatting is used:

  • str.format()

  • https://pyformat.info/

  • https://docs.python.org/3/library/string.html#formatspec

• Automatic kwargs conversion into error instance attributes

• You can attach static and dynamic default values: this is why datetime.now() was omitted above

• Out-of-box validation for provided kwargs (individually enable/disable checks with __toggles__ attribute)

as_dict(*, wide: bool = False) → Dict[str, Any]

Represent error as dict of fields including default values.

By default, only instance data and defaults are provided.

Parameters:

wide – if True class defaults will be included in result

as_kwargs() → Dict[str, Any]

Return the copy of original kwargs used to initialize the error.

as_str() → str

Represent error as an exception type with message.

class izulu.root.Toggles(*values)

DEFAULT = 31

FORBID_KWARG_CONSTS = 4

FORBID_MISSING_FIELDS = 1

FORBID_NON_NAMED_FIELDS = 8

FORBID_UNANNOTATED_FIELDS = 16

FORBID_UNDECLARED_FIELDS = 2

NONE = 0

izulu.root.factory(*, default_factory: Callable[[], FactoryReturnType], self: Literal[False] = False) → FactoryReturnType

izulu.root.factory(*, default_factory: Callable[[Error], FactoryReturnType], self: Literal[True]) → FactoryReturnType

Attaches factory for dynamic default values.

Parameters:

• default_factory – callable factory receiving 0 or 1 argument (see self param)

• self – controls callable factory argument if True factory will receive single argument of error instance otherwise factory will be invoked without argument

Reraise

class izulu._reraise.FatalMixin

Mark exception as non-recoverable.

Should be directly inherited. You can’t inherit from fatal exception. Fatal exceptions are by-passed by ReraisingMixin tools.

class izulu._reraise.ReraisingMixin

classmethod async_reraise(reraising: Tuple[Tuple[Type[Exception] | Tuple[Type[Exception], ...], str | Type[Exception] | Callable[[Type[Exception], Exception, Dict[str, Any]], Exception | None] | None], ...] | bool | None = None, remap_kwargs: Dict[str, Any] | None = None)

Async version of reraise.

Parameters:

• reraising – manual overriding reraising rules

• remap_kwargs – provide kwargs for reraise exception

classmethod remap(exc: Exception, *, reraising: Tuple[Tuple[Type[Exception] | Tuple[Type[Exception], ...], str | Type[Exception] | Callable[[Type[Exception], Exception, Dict[str, Any]], Exception | None] | None], ...] | bool | None = None, remap_kwargs: Dict[str, Any] | None = None, original_over_none: bool = False) → Exception | None

Return remapped exception instance.

Remapping rules:

1. if the result of remapping is to leave the original exception method will return

   1. None for original_over_none=False,

   2. original exception for original_over_none=True.

2. early-return rule works first to abort remapping process for:

   1. exception with FatalMixin,

   2. descendant exceptions for used class.

3. Default behaviour is not to remap exception.

4. Rules: …

Parameters:

• exc – original exception to be remapped

• reraising – manual overriding reraising rules

• remap_kwargs – provide kwargs for reraise exception

• original_over_none – if True return original exception instead of None

Returns:

reraising context manager

classmethod reraise(reraising: Tuple[Tuple[Type[Exception] | Tuple[Type[Exception], ...], str | Type[Exception] | Callable[[Type[Exception], Exception, Dict[str, Any]], Exception | None] | None], ...] | bool | None = None, remap_kwargs: Dict[str, Any] | None = None)

Context Manager & Decorator to raise class exception over original.

Parameters:

• reraising – manual overriding reraising rules

• remap_kwargs – provide kwargs for reraise exception

izulu._reraise.catch(target: Type[Exception] = <class 'Exception'>, *, exclude: Type[Exception] | None = None, new: Any = typing.Self) → Tuple[Tuple[Type[Exception] | Tuple[Type[Exception], ...], str | Type[Exception] | Callable[[Type[Exception], Exception, Dict[str, Any]], Exception | None] | None], ...]

class izulu._reraise.chain(kls: ReraisingMixin, *klasses: ReraisingMixin)

classmethod from_names(name: str, *names: str) → chain

classmethod from_subtree(klass: Type[ReraisingMixin]) → chain

izulu._reraise.skip(target: Type[Exception]) → Tuple[Tuple[Type[Exception] | Tuple[Type[Exception], ...], str | Type[Exception] | Callable[[Type[Exception], Exception, Dict[str, Any]], Exception | None] | None], ...]