errortools¶

errortools logo

errortools is a lightweight Python toolkit for exception handling, warnings, and structured logging. It offers both high-level convenience APIs and zero-overhead helpers for performance-critical code paths.

Something need change or refactor? Contact email errortools.docs@proton.me

At a glance¶

from errortools import ignore, retry, BaseErrorCodes
from errortools.logging import logger

# Suppress exceptions with metadata
with ignore(KeyError) as err:
    _ = {}["missing"]
print(err.exception)        # KeyError('missing')

# Automatic retry on failure
@retry(times=3, on=ConnectionError, delay=1.0)
def connect(host: str): ...

# Structured exceptions with error codes
raise BaseErrorCodes.not_found("user #42")   # NotFoundError [3001]

# Structured logging — no external dependencies
logger.info("Server started on port {}", 8080)

Key features¶

Exception handling. Context managers and decorators for graceful error suppression — see Exception Handling.
Batch raising. Raise one or many exceptions at once with raises() and raises_all() — see Raising Exceptions.
Decorators. Automatic retry (@retry), async timeout (@timeout), and error-caching (@error_cache) — see Decorators.
Custom exceptions. Structured exception classes with error codes, trace IDs, and rich context — see Custom Exceptions.
Future module. Zero-overhead exception handling for hot paths — see Future Module.
Logging. A Loguru-inspired structured logger with no external dependencies — see Logging.
Warnings. A small library of Warning subclasses for common deprecation / performance scenarios — see Warnings.
Type safety. Full type hints and typing aliases for IDE-friendly code — see API Reference.

Why errortools?¶

Concern	Standard library	errortools
Suppress an exception with metadata	`try / except` boilerplate	`with ignore(KeyError) as err:`
Retry on failure	DIY loop	`@retry(times=3, on=ConnectionError)`
Structured error code	subclass `Exception` by hand	`BaseErrorCodes.not_found("user")`
Zero-overhead `suppress`	`contextlib.suppress`	`super_fast_ignore(ValueError)`
Structured logging	`logging` dictConfig	`logger.info("port {}", 8080)`

Installation¶

pip install errortools

For development installs and contributing see Installation.

Where to go next¶

Contents