impl¶

Enhanced Python Enum implementation with explicit API for validation and retrieval.

This module provides improved enum classes that extend Python’s built-in enum functionality with convenient methods for getting enum members by name or value, along with validation utilities. The classes are designed to be drop-in replacements for standard int and str enums while providing additional safety and convenience methods.

class enum_mate.impl.EnumMixin[source]¶

Base mixin class providing common utility methods for enhanced enum classes.

This mixin provides name-based operations that are common to all enum types, including retrieval by name, name validation, and name listing functionality.

Important

Both enum member names and values must be unique within the same enum class.

classmethod get_by_name(name: str)[source]¶

Get the enum member by its name.

Parameters:: name – The name of the enum member to retrieve
Returns:: The enum member object
Raises:: KeyError – If the name is not a valid enum member name

Example: >>> class MyEnum(BetterIntEnum): … VALUE_ONE = 1 >>> MyEnum.get_by_name(“VALUE_ONE”) <MyEnum.VALUE_ONE: 1>

classmethod is_valid_name(name: str) → bool[source]¶

Check if the given name is a valid enum member name.

Parameters:: name – The name to validate
Returns:: True if the name is valid, False otherwise

Example: >>> class MyEnum(BetterIntEnum): … VALUE_ONE = 1 >>> MyEnum.is_valid_name(“VALUE_ONE”) True >>> MyEnum.is_valid_name(“INVALID”) False

classmethod get_names() → List[str][source]¶

Get a list of all enum member names.

Returns:: List of all enum member names

Example:

>>> class MyEnum(BetterIntEnum):
...     VALUE_ONE = 1
...     VALUE_TWO = 2
>>> MyEnum.get_names()
['VALUE_ONE', 'VALUE_TWO']

class enum_mate.impl.BetterIntEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Enhanced integer enum with explicit API for validation and retrieval operations.

Example:

>>> class CodeEnum(BetterIntEnum):
...     succeeded = 1
...     failed = 0
>>> CodeEnum.get_by_name("succeeded")
<CodeEnum.succeeded: 1>
>>> CodeEnum.get_by_value(1)
<CodeEnum.succeeded: 1>
>>> CodeEnum.is_valid_name("succeeded")
True
>>> CodeEnum.is_valid_name("SUCCEEDED")
False
>>> CodeEnum.is_valid_name(1)
False
>>> CodeEnum.is_valid_value("succeeded")
False
>>> CodeEnum.is_valid_value("SUCCEEDED")
False
>>> CodeEnum.is_valid_value(1)
True
>>> CodeEnum.ensure_is_valid_value(1)
>>> CodeEnum.ensure_is_valid_value("succeeded")
Traceback (most recent call last):
...
ValueError: Invalid CodeEnum: 'succeeded'
>>> CodeEnum.ensure_int(1)
1
>>> CodeEnum.ensure_int(CodeEnum.succeeded)
1
>>> isinstance(CodeEnum.ensure_int(1), int)
True

Important

Both enum member names and values must be unique within the same enum class.

classmethod get_by_value(value: int)[source]¶

Get the enum member by its integer value.

Parameters:: value – The integer value of the enum member to retrieve
Returns:: The enum member object
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class StatusCode(BetterIntEnum): … SUCCESS = 200 >>> StatusCode.get_by_value(200) <StatusCode.SUCCESS: 200>

classmethod is_valid_value(value: int) → bool[source]¶

Check if the given integer value is a valid enum member value.

Parameters:: value – The integer value to validate
Returns:: True if the value is valid, False otherwise

Example: >>> class StatusCode(BetterIntEnum): … SUCCESS = 200 >>> StatusCode.is_valid_value(200) True >>> StatusCode.is_valid_value(999) False

classmethod ensure_is_valid_value(value)[source]¶

Ensure the given value is a valid enum member value.

This method performs validation and raises an exception if the value is not valid, making it useful for input validation scenarios.

Parameters:: value – The value to validate
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class StatusCode(BetterIntEnum): … SUCCESS = 200 >>> StatusCode.ensure_is_valid_value(200) # No exception >>> StatusCode.ensure_is_valid_value(999) # Raises ValueError Traceback (most recent call last): … ValueError: Invalid StatusCode: 999

classmethod ensure_int(value: int | BetterIntEnum) → int[source]¶

Ensure the value is converted to its integer representation.

This method accepts either an integer value or an enum object and returns the corresponding integer value, with validation to ensure it’s a valid enum member value.

Parameters:: value – Either an integer value or an enum object
Returns:: The integer value of the enum member
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class StatusCode(BetterIntEnum): … SUCCESS = 200 >>> StatusCode.ensure_int(200) 200 >>> StatusCode.ensure_int(StatusCode.SUCCESS) 200 >>> isinstance(StatusCode.ensure_int(StatusCode.SUCCESS), int) True

classmethod get_values() → List[int][source]¶

Get a list of all enum member integer values.

Returns:: List of all enum member integer values

Example: >>> class StatusCode(BetterIntEnum): … SUCCESS = 200 … NOT_FOUND = 404 >>> StatusCode.get_values() [200, 404]

class enum_mate.impl.BetterStrEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Enhanced string enum with explicit API for validation and retrieval operations.

Example:

>>> class StatusEnum(BetterStrEnum):
...     succeeded = "SUCCEEDED"
...     failed = "FAILED"
>>> StatusEnum.get_by_name("succeeded")
<StatusEnum.succeeded: 'SUCCEEDED'>
>>> StatusEnum.get_by_value("SUCCEEDED")
<StatusEnum.succeeded: 'SUCCEEDED'>
>>> StatusEnum.is_valid_name("succeeded")
True
>>> StatusEnum.is_valid_name("SUCCEEDED")
False
>>> StatusEnum.is_valid_value("succeeded")
False
>>> StatusEnum.is_valid_value("SUCCEEDED")
True
>>> StatusEnum.ensure_is_valid_value("SUCCEEDED")
>>> StatusEnum.ensure_is_valid_value("succeeded")
Traceback (most recent call last):
...
ValueError: Invalid StatusEnum: 'succeeded'
>>> StatusEnum.ensure_str("SUCCEEDED")
'SUCCEEDED'
>>> StatusEnum.ensure_str(StatusEnum.succeeded)
'SUCCEEDED'
>>> isinstance(StatusEnum.ensure_str("SUCCEEDED"), str)
True

Important

Both enum member names and values must be unique within the same enum class.

classmethod get_by_value(value: str)[source]¶

Get the enum member by its string value.

Parameters:: value – The string value of the enum member to retrieve
Returns:: The enum member object
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class Environment(BetterStrEnum): … DEVELOPMENT = “dev” >>> Environment.get_by_value(“dev”) <Environment.DEVELOPMENT: ‘dev’>

classmethod is_valid_value(value: str) → bool[source]¶

Check if the given string value is a valid enum member value.

Parameters:: value – The string value to validate
Returns:: True if the value is valid, False otherwise

Example: >>> class Environment(BetterStrEnum): … DEVELOPMENT = “dev” >>> Environment.is_valid_value(“dev”) True >>> Environment.is_valid_value(“invalid”) False

classmethod ensure_is_valid_value(value)[source]¶

Ensure the given value is a valid enum member value.

This method performs validation and raises an exception if the value is not valid, making it useful for input validation scenarios.

Parameters:: value – The value to validate
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class Environment(BetterStrEnum): … DEVELOPMENT = “dev” >>> Environment.ensure_is_valid_value(“dev”) # No exception >>> Environment.ensure_is_valid_value(“invalid”) # Raises ValueError Traceback (most recent call last): … ValueError: Invalid Environment: ‘invalid’

classmethod ensure_str(value: str | BetterStrEnum) → str[source]¶

Ensure the value is converted to its string representation.

This method accepts either a string value or an enum object and returns the corresponding string value, with validation to ensure it’s a valid enum member value.

Parameters:: value (Union[str, BetterStrEnum]) – Either a string value or an enum object
Returns:: The string value of the enum member
Return type:: str
Raises:: ValueError – If the value is not a valid enum member value

Example: >>> class Environment(BetterStrEnum): … DEVELOPMENT = “dev” >>> Environment.ensure_str(“dev”) ‘dev’ >>> Environment.ensure_str(Environment.DEVELOPMENT) ‘dev’ >>> isinstance(Environment.ensure_str(Environment.DEVELOPMENT), str) True

classmethod get_values() → List[str][source]¶

Get a list of all enum member string values.

Returns:: List of all enum member string values

Example: >>> class Environment(BetterStrEnum): … DEVELOPMENT = “dev” … PRODUCTION = “prod” >>> Environment.get_values() [‘dev’, ‘prod’]