Install & Compatibility
Where this runs
tested against v0.75.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.061s · 18.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.056s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Error
✓ from izulu.root import Error
root
✓ from izulu import root
✗ from izulu import Error
The main 'Error' class resides in the 'root' submodule, not directly under 'izulu'.
Define custom exception classes by inheriting from `izulu.root.Error`. Use the `__template__` class attribute to specify the error message format, incorporating placeholders for dynamic data. Instantiate exceptions with keyword arguments that match the template placeholders and any type-hinted attributes for automatic population. Handle these custom exceptions with standard `try-except` blocks.
from izulu.root import Error
class DataError(Error):
__template__ = "Invalid data: {reason}"
class MissingField(DataError):
__template__ = "Missing required field: '{field_name}'"
field_name: str
class OutOfRange(DataError):
__template__ = "Value for '{field_name}' is out of range. Expected: {min_val}-{max_val}, Got: {actual_val}"
field_name: str
min_val: int
max_val: int
actual_val: int
def process_data(data: dict):
if not data:
raise DataError(reason="empty input")
if 'name' not in data:
raise MissingField(field_name='name')
age = data.get('age')
if not isinstance(age, int):
raise DataError(reason="age must be an integer")
min_age, max_age = 18, 99
if not (min_age <= age <= max_age):
raise OutOfRange(field_name='age', min_val=min_age, max_val=max_age, actual_val=age)
print(f"Data processed successfully for {data['name']} (Age: {age})")
# Example Usage:
try:
process_data({"name": "Alice", "age": 25})
except DataError as e:
print(f"Error processing data: {e}")
try:
process_data(None)
except DataError as e:
print(f"Error processing data: {e}")
try:
process_data({"name": "Bob"})
except MissingField as e:
print(f"Error processing data: {e}. Field: {e.field_name}")
try:
process_data({"name": "Charlie", "age": 150})
except OutOfRange as e:
print(f"Error processing data: {e}. Details: field={e.field_name}, actual={e.actual_val}")
Debug
Known issues
gotchaFor Python versions prior to 3.11, the 'compatibility' extra must be installed (e.g., `pip install izulu izulu[compatibility]`). For Python 3.11 and newer, `pip install izulu` is sufficient.fixEnsure `izulu[compatibility]` is installed if using Python < 3.11.
affects: <0.75.0 (and potentially future versions depending on Python runtime)
breakingThe `__template__` attribute for custom error classes only supports named format fields (e.g., `{reason}`, `{amount}`). Positional (e.g., `{0}`) or empty (e.g., `{}`) format fields are forbidden and will result in a `ValueError` during class definition or instantiation.fixUpdate `__template__` strings to use only named format fields.
affects: All versions
gotchaType hints (e.g., `amount: int`) on class attributes are not validated or enforced by izulu at runtime. They serve purely as documentation or for static analysis tools.fixImplement explicit validation logic if runtime type checking is required for attributes.
affects: All versions
gotchaThe library's validation behavior is dependent on the 'features' enabled for an error class. Modifying the feature set can lead to different or raw exceptions being raised than expected.fixThoroughly read and understand the 'Features' section in the documentation when customizing error behavior to predict runtime exceptions.
affects: All versions
gotchaWhile direct inheritance from `izulu.root.Error` is possible, the documentation recommends creating an intermediate base class (e.g., `class BaseError(Error):`) to centrally control default behavior and features for your application's exceptions.fixConsider establishing a project-specific base exception class that inherits from `izulu.root.Error` and then inherit all other custom exceptions from this base class.
affects: All versions
Errors
Common errors & fixes
ValueError: Field names can't be empty.
The `__template__` attribute in an `izulu` error class was defined using empty (`{}`) or positional (`{0}`) format fields, which are forbidden. Only named format fields are allowed.
fixModify the `__template__` string to use only named format fields, for example: `__template__ = "Error: {reason}"`. ModuleNotFoundError: No module named 'izulu'
The `izulu` library is not installed in your current Python environment.
fixInstall the library using pip: `pip install izulu`. If you are using Python versions prior to 3.11, you may need to install the compatibility extra: `pip install izulu[compatibility]`.
KeyError: 'field_name'
You instantiated an `izulu` error class but did not provide a keyword argument for a named field (`{field_name}`) that is present in its `__template__` string.
fixEnsure all named format fields in the `__template__` string have corresponding keyword arguments passed during the error instantiation, for example: `MyError(field_name='some_value')`.
Upgrade
Version history
0.75.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
typing-extensionsoptionalRequired for compatibility features on Python versions prior to 3.11.