---
id: izulu
version: "0.75.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# izulu — The exceptional library

License: permissive · Maintenance: active · Downloads: 662.3K/mo

## What it is and what it does

izulu is a library for defining exception classes with template-based message formatting and typed instance attributes. Instead of manually constructing error messages with string formatting scattered throughout your code, you define an exception class once with a `__template__` attribute and provide only the variable data as keyword arguments when raising it. The library automatically populates annotated instance attributes from those kwargs, allowing you to access structured error data programmatically rather than parsing strings.

The package targets developers who want to centralize exception message logic and treat exceptions as first-class data objects with fields. It supports class-level defaults, instance-level defaults (both static and dynamic via a `factory` helper), and inheritance hierarchies for exception specialization. With no runtime dependencies and support for modern Python versions, it integrates into existing projects with minimal friction.

Use it for:

- Validation error hierarchies where different validation failures need distinct messages and carry specific context.
- API error responses where you want to serialize exception attributes into JSON without parsing the message string.
- Logging systems where structured exception data should be captured as attributes, not extracted from text.
- Domain-specific exception frameworks where each error type has a fixed message template but variable context parameters.
- Testing and debugging where you need to inspect exception state programmatically rather than relying on string matching.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

izulu provides a template-based, object-oriented approach to defining and raising exceptions with structured attributes and automatic message formatting.

Yes. izulu is actively maintained, has no dependencies, installs easily, and solves a real problem—centralizing exception message templates and structuring exception data. It's particularly valuable in codebases with many custom exceptions or where exception attributes need to be accessed programmatically. The permissive license and stable API make it safe for production use.

## Install

pip install izulu
uv add izulu
poetry add izulu

## Installing izulu

Before you install: Low friction: pure Python wheel with no runtime dependencies. Active maintenance with recent commits and stable release cadence since initial release.

License in practice: Permissive license (MIT) allows use in commercial and proprietary projects with minimal restrictions.

Quickstart:

pip install izulu

from izulu.root import Error

class ValidationError(Error):
    __template__ = "Data is invalid: {reason}"

raise ValidationError(reason="no data")

Requires Python 3.9 or higher; earlier Python versions must install izulu[compatibility].

Verify before relying:

- Whether template field validation or type checking occurs at exception instantiation time
- Performance characteristics when raising many exception instances in tight loops
- Compatibility with exception chaining and traceback preservation across Python versions

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 662.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

exception class templates, structured error messages, oop exception handling, custom exception attributes, error message templating, exception inheritance patterns, typed exception classes, exception-handling, oop-patterns, error-management

[View on SkillFed](https://skillfed.io/packages/izulu) · [View on PyPI](https://pypi.org/project/izulu/)