py-buzz

That's not flying, it's falling with style: Exceptions with extras

Long ago, I found myself writing the same boilerplate for condition checks and exception wrappers over and over. So I gathered some helpers together to cut down on repetitive error-handling code. When I switched projects later, I wanted those helpers there, too! That's how py-buzz came to be.

Now, I have a collection of really useful exception helpers that I can use in all my projects, and I'm sharing them with you!

Getting started

Python 3.11 or newer is required, and installation takes one line:

uv add py-buzz

Here's a small example with a project-specific exception:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from buzz import Buzz


class ConfigError(Buzz):
    pass


def read_port(value: object) -> int:
    port = ConfigError.ensure_type(value, int, "Port must be an integer")
    ConfigError.require_condition(1 <= port <= 65535, "Port must be between 1 and 65535")
    return port


def parse_port(value: str) -> int:
    with ConfigError.handle_errors("Couldn't parse the configured port"):
        port = int(value)
    return read_port(port)

Here, ensure_type() checks the value at runtime and returns it with a narrowed type, while require_condition() raises ConfigError if the port is out of range. handle_errors() gives parsing failures a bit more context by wrapping the original ValueError in a ConfigError.

What's in the box

Most helpers come in two flavors: standalone functions that work with regular exception types and methods on a Buzz subclass that raise that class. reformat_exception() is a standalone helper for formatting exception messages.

• require_condition() checks a condition.
• enforce_defined() rejects None and narrows the value's type.
• ensure_type() checks a runtime type and narrows the result.
• verify_literal() checks a Literal value.
• handle_errors() and handle_errors_async() add context to exceptions from a block.
• Buzz.retry() and Buzz.retry_async() retry synchronous and asynchronous operations.
• check_expressions() reports multiple failed checks together.
• raise_from() adds context while preserving the original exception as the cause.
• reformat_exception() formats an exception message with more context.
• get_traceback() fetches the current traceback.

The standalone retry() and retry_async() decorators live in buzz.tools; the retry guide shows both styles.

The demos

The optional demo extra bundles executable examples of the features. With uv, the demos can run in an isolated environment:

uvx --from='py-buzz[demo]' py-buzz-demo

The demo guide has a few more ways to run individual examples.