API Reference

Enums

Base Enum Utilities.

This module provides custom base classes for StrEnum and IntEnum to handle common case-insensitive, separator-insensitive matching, and alias support for creating enum members. It leverages modern Python 3.11+ features.

class gunz_utils.enums.BaseIntEnum(value)

Bases: IntEnum

A base class for IntEnum that provides string-based lookup and alias support.

Examples

>>> class ErrorCode(BaseIntEnum):
...     __ALIASES__ = {"missing": 404}
...     NOT_FOUND = 404
...
>>> ErrorCode.from_fuzzy_int_string("missing") is ErrorCode.NOT_FOUND
True

classmethod choices() → list[Any]

classmethod from_fuzzy_int_string(value_str: str) → Self

Attempts to find a member by alias (string->int), case-insensitive name, or string-to-int conversion.

classmethod get_or_none(value: object) → Self | None

classmethod items() → list[tuple[str, int]]

classmethod names() → list[str]

classmethod values() → list[int]

class gunz_utils.enums.BaseStrEnum(value)

Bases: StrEnum

A base class for StrEnum that provides robust matching and alias support.

Features: - Case-insensitive matching. - Separator-insensitive matching (treats spaces, dashes, underscores as same). - Alias support via the __ALIASES__ class attribute. - Introspection helpers (names, values, items). - Safe lookup (get_or_none).

Examples

>>> class Color(BaseStrEnum):
...     __ALIASES__ = {"dark": "dark_blue"}
...     DARK_BLUE = "dark_blue"
...     LIGHT_GREEN = "light green"
...
>>> Color.from_fuzzy_string("DARK_BLUE") is Color.DARK_BLUE
True
>>> Color.from_fuzzy_string("dark-blue") is Color.DARK_BLUE
True
>>> Color.from_fuzzy_string("dark") is Color.DARK_BLUE
True

classmethod choices() → list[str]

classmethod from_fuzzy_string(value_str: str) → Self

Attempts to find a member by alias, normalized value, or case-insensitive name. Raises ValueError if no match is found.

classmethod get_or_none(value: object) → Self | None

Safely attempts to get an enum member. Returns None if invalid.

classmethod items() → list[tuple[str, str]]

Returns a list of (name, value) tuples.

classmethod names() → list[str]

Returns a list of all member names.

classmethod values() → list[str]

Returns a list of all member values.

class gunz_utils.enums.OptionalBaseStrEnum(value)

Bases: BaseStrEnum

A base class for StrEnum that treats None as the NONE enum member.

Validation

Validation utilities.

This module provides decorators and helpers to improve data validation and error reporting, wrapping underlying libraries like Pydantic.

gunz_utils.validation.type_checked(func: Callable | None = None, **kwargs: Any) → Callable

A wrapper around pydantic.validate_call that provides cleaner, user-friendly error messages.

It catches pydantic.ValidationError and re-raises it as a TypeError with a formatted message indicating exactly which argument failed and why.

Parameters:

• func (Callable, optional) – The function to decorate.

• **kwargs – Additional arguments passed to pydantic.validate_call (e.g., config).

Returns:

The decorated function with validation logic.

Return type:

Callable

Examples

>>> @type_checked
... def my_func(a: int):
...     pass
...
>>> my_func("string")
TypeError: Validation error in 'my_func':
Argument 'a': Input should be a valid integer, unable to parse string as an integer (got type 'str')