models

Enum utilities, sequential counter, JSON parsing, validation helpers, and data model utilities.

The models module provides utilities for working with enums, sequential integer generation, JSON/list validation, and field checking — useful for building Pydantic models, dataclasses, and other structured data types.

Auto

A callable counter that generates sequential integers starting from a configurable value. Designed to be used with Python’s Enum to automatically assign sequential integer values to enum members.

from alexber.utils.models import Auto, create_auto

auto = Auto(start=1)
print(auto())  # 1
print(auto())  # 2
print(auto())  # 3

Usage with Enum

from enum import Enum
from alexber.utils.models import create_auto

_auto = create_auto(start=0)

class Color(Enum):
    RED = _auto()    # 0
    GREEN = _auto()  # 1
    BLUE = _auto()   # 2

start · int · default: "0"

The first integer value returned on the first call. Subsequent calls increment by 1.

Returns: int on each call.

---

create_auto

Factory function that creates a new Auto instance.

from alexber.utils.models import create_auto

counter = create_auto(start=10)
counter()  # 10
counter()  # 11

start · int · default: "0"

Starting value for the counter.

Returns: A new Auto instance.

---

parse_json

Parses a JSON string or passes through a list directly. Useful when a field can be supplied as either a JSON-encoded list or a native Python list.

from alexber.utils.models import parse_json

parse_json('[1, 2, 3]', 'items')   # [1, 2, 3]
parse_json([1, 2, 3], 'items')     # [1, 2, 3]

json_d · Any · required

The value to parse. Must be a JSON string encoding a list, or an already-constructed list.

field_name · str · required

Name of the field being parsed, used in error messages.

Returns: List[Any] — the parsed or passed-through list.

Raises:

• ValueError — if json_d is None, if the JSON string does not parse to a list, or if json_d is neither a string nor a list.

---

validate_same_length

Asserts that all provided iterables have the same length.

from alexber.utils.models import validate_same_length

names = ['Alice', 'Bob']
scores = [95, 87]

validate_same_length(names, scores, field_names='names, scores')  # OK

validate_same_length(names, [1, 2, 3], field_names='names, values')
# ValueError: The length of names, values must be the same

*args · Iterable · required

The iterables to compare. All must support len().

field_names · str · required

Comma-separated field names used in the error message. Must be provided.

Returns: None

Raises:

• ValueError — if field_names is not provided, or if the iterables have different lengths.

Returns immediately (without error) if all arguments are empty iterables.

---

check_not_empty

Validates that a value is not falsy. Raises ValueError if it is.

from alexber.utils.models import check_not_empty

class Field:
    field_name = 'username'

check_not_empty('alice', Field())   # returns 'alice'
check_not_empty('', Field())        # raises ValueError: username must not be empty
check_not_empty(None, Field())      # raises ValueError: username must not be empty

v · Any · required

The value to check.

field · object · required

An object with a field_name attribute used in the error message.

Returns: v unchanged if it is truthy.

Raises:

• ValueError — if v is falsy (None, "", 0, [], etc.).

---

convert_value_to_enum

Converts an integer, string, or existing enum instance to an enum member.

from enum import Enum
from alexber.utils.models import convert_value_to_enum

class Status(Enum):
    ACTIVE = 1
    INACTIVE = 2

convert_value_to_enum(1, Status)         # Status.ACTIVE
convert_value_to_enum('ACTIVE', Status)  # Status.ACTIVE
convert_value_to_enum(Status.ACTIVE, Status)  # Status.ACTIVE (passthrough)

value · int | str | Enum · required

The value to convert. Integers are matched against enum values. Strings are matched against enum names. Existing enum instances are returned as-is.

enum_class · Type[Enum] · required

The target enum class.

Returns: An instance of enum_class.

Raises:

• ValueError — if the value cannot be mapped to any member of enum_class.

---

enum_field_validator

Returns a Pydantic-compatible validator function that converts a list of raw values to a list of enum members.

from enum import Enum
from alexber.utils.models import enum_field_validator

class Color(Enum):
    RED = 1
    GREEN = 2

validator = enum_field_validator(field, Color)
validator([1, 2])         # [Color.RED, Color.GREEN]
validator(['RED', 'GREEN'])  # [Color.RED, Color.GREEN]

field · object · required

The Pydantic field object (carries field_name for error messages).

enum_class · Type[Enum] · required

The enum class to convert values to.

Returns: A validator callable (v: Any) -> List[Enum].

Raises:

• ValueError — if the input is not a list, or if any element cannot be converted.