{"id":4582,"library":"izulu","title":"izulu: The Exceptional Library","description":"izulu is a Python library designed to bring Object-Oriented Programming (OOP) principles into exception and error management. It eliminates the need for manual error message formatting by allowing developers to define exception templates within class definitions. This approach centralizes static error data and uses keyword arguments for variable data, generating final error messages dynamically. The library is actively maintained, with version 0.75.0 being the latest stable release.","status":"active","version":"0.75.0","language":"en","source_language":"en","source_url":"https://github.com/pyctrl/izulu","tags":["error","exception","oop","izulu"],"install":[{"cmd":"pip install izulu","lang":"bash","label":"For Python 3.11+"},{"cmd":"pip install izulu izulu[compatibility]","lang":"bash","label":"For Python 3.8-3.10"}],"dependencies":[{"reason":"Required for compatibility features on Python versions prior to 3.11.","package":"typing-extensions","optional":true}],"imports":[{"symbol":"Error","correct":"from izulu.root import Error"},{"note":"The main 'Error' class resides in the 'root' submodule, not directly under 'izulu'.","wrong":"from izulu import Error","symbol":"root","correct":"from izulu import root"}],"quickstart":{"code":"from izulu.root import Error\n\nclass DataError(Error):\n    __template__ = \"Invalid data: {reason}\"\n\nclass MissingField(DataError):\n    __template__ = \"Missing required field: '{field_name}'\"\n    field_name: str\n\nclass OutOfRange(DataError):\n    __template__ = \"Value for '{field_name}' is out of range. Expected: {min_val}-{max_val}, Got: {actual_val}\"\n    field_name: str\n    min_val: int\n    max_val: int\n    actual_val: int\n\ndef process_data(data: dict):\n    if not data:\n        raise DataError(reason=\"empty input\")\n    \n    if 'name' not in data:\n        raise MissingField(field_name='name')\n    \n    age = data.get('age')\n    if not isinstance(age, int):\n        raise DataError(reason=\"age must be an integer\")\n    \n    min_age, max_age = 18, 99\n    if not (min_age <= age <= max_age):\n        raise OutOfRange(field_name='age', min_val=min_age, max_val=max_age, actual_val=age)\n    \n    print(f\"Data processed successfully for {data['name']} (Age: {age})\")\n\n# Example Usage:\ntry:\n    process_data({\"name\": \"Alice\", \"age\": 25})\nexcept DataError as e:\n    print(f\"Error processing data: {e}\")\n\ntry:\n    process_data(None)\nexcept DataError as e:\n    print(f\"Error processing data: {e}\")\n\ntry:\n    process_data({\"name\": \"Bob\"})\nexcept MissingField as e:\n    print(f\"Error processing data: {e}. Field: {e.field_name}\")\n\ntry:\n    process_data({\"name\": \"Charlie\", \"age\": 150})\nexcept OutOfRange as e:\n    print(f\"Error processing data: {e}. Details: field={e.field_name}, actual={e.actual_val}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `izulu[compatibility]` is installed if using Python < 3.11.","message":"For 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.","severity":"gotcha","affected_versions":"<0.75.0 (and potentially future versions depending on Python runtime)"},{"fix":"Update `__template__` strings to use only named format fields.","message":"The `__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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Implement explicit validation logic if runtime type checking is required for attributes.","message":"Type 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly read and understand the 'Features' section in the documentation when customizing error behavior to predict runtime exceptions.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider establishing a project-specific base exception class that inherits from `izulu.root.Error` and then inherit all other custom exceptions from this base class.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}