Diagnostics Errors

Error management utilities.

Error Handling Module

Error handling utilities with retry, catching, and formatting.

This submodule provides utilities for handling errors gracefully: retry decorators, exception context managers, traceback formatting, and exception chain analysis.

Examples

from rite.diagnostics.errors import errors_retry, errors_catch @errors_retry(max_attempts=3) ... def flaky_function(): ... pass with errors_catch(): ... risky_operation()

Modules

errors_catch

Exception Context Manager

Context manager to catch and handle exceptions gracefully.

Examples

from rite.diagnostics.errors import errors_catch with errors_catch(): ... risky_operation()

Functions

errors_catch(exceptions: tuple[type[Exception], ...] = (Exception,), handler: Callable[[Exception], Any] | None = None, reraise: bool = False, logger: logging.Logger | None = None) -> Generator[None, None, None]

Context manager to catch and handle exceptions.

Parameters:

Name	Type	Description	Default
exceptions	tuple[type[Exception], ...]	Tuple of exceptions to catch.	(Exception,)
handler	Callable[[Exception], Any] | None	Optional handler function called with exception.	None
reraise	bool	If True, reraise exception after handling.	False
logger	Logger | None	Optional logger to log exceptions.	None

Yields:

Type	Description
None	None.

Examples:

>>> with errors_catch():
...     1 / 0
>>> with errors_catch(handler=lambda e: print(f"Error: {e}")):
...     risky_operation()
>>> with errors_catch((ValueError, KeyError), reraise=True):
...     parse_data()

errors_format_traceback

Traceback Formatter

Format exception tracebacks for better readability.

Examples

from rite.diagnostics.errors import errors_format_traceback try: ... 1 / 0 ... except Exception as e: ... print(errors_format_traceback(e))

Functions

errors_format_traceback(exception: BaseException, include_locals: bool = False) -> str

Format exception traceback as string.

Parameters:

Name	Type	Description	Default
exception	BaseException	Exception to format.	required
include_locals	bool	If True, include local variables.	False

Returns:

Type	Description
str	Formatted traceback string.

Examples:

>>> try:
...     raise ValueError("test error")
... except ValueError as e:
...     tb = errors_format_traceback(e)
...     "ValueError" in tb
True

errors_get_chain

Exception Chain

Get exception chain (cause hierarchy).

Examples

from rite.diagnostics.errors import errors_get_chain try: ... try: ... 1 / 0 ... except ZeroDivisionError as e: ... raise ValueError("Wrapped") from e ... except ValueError as e: ... chain = errors_get_chain(e)

Functions

errors_get_chain(exception: BaseException) -> list[BaseException]

Get exception chain (cause hierarchy).

Parameters:

Name	Type	Description	Default
exception	BaseException	Exception to get chain for.	required

Returns:

Type	Description
list[BaseException]	List of exceptions from root cause to final exception.

Examples:

>>> try:
...     try:
...         raise ValueError("root")
...     except ValueError as e:
...         raise KeyError("wrapped") from e
... except KeyError as e:
...     chain = errors_get_chain(e)
...     len(chain)
2

errors_retry

Retry Decorator

Decorator to retry function calls on failure.

Examples

from rite.diagnostics.errors import errors_retry @errors_retry(max_attempts=3, delay=1.0) ... def unstable_function(): ... pass

Functions

errors_retry(max_attempts: int = 3, delay: float = 1.0, backoff: float = 2.0, exceptions: tuple[type[Exception], ...] = (Exception,)) -> Callable[[Callable[..., T]], Callable[..., T]]

Decorator to retry function on failure.

Parameters:

Name	Type	Description	Default
max_attempts	int	Maximum retry attempts.	3
delay	float	Initial delay between retries (seconds).	1.0
backoff	float	Multiplier for delay on each retry.	2.0
exceptions	tuple[type[Exception], ...]	Tuple of exceptions to catch.	(Exception,)

Returns:

Type	Description
Callable[[Callable[..., T]], Callable[..., T]]	Decorated function with retry logic.

Examples:

>>> @errors_retry(max_attempts=3)
... def flaky_api_call():
...     pass
>>> @errors_retry(max_attempts=5, delay=0.5, backoff=1.5)
... def database_query():
...     pass

options: show_root_heading: true show_source: false heading_level: 2