pyg90alarm.dataclass.validation

Validation descriptors for dataclass fields.

This module provides descriptor-based validation for dataclass fields, supporting integer range validation and string length validation.

Example usage:

from dataclasses import dataclass from pyg90alarm.dataclass.validation import (

validated_int_field, validated_string_field,

)

@dataclass class Config:

# Integer field with range validation count: int = validated_int_field(min_value=0, max_value=100)

# String field with length validation name: str = validated_string_field(min_length=1, max_length=50)

Functions

get_field_validation_constraints(...[, ...])

Retrieve validation constraints for a specific dataclass field.

validated_int_field(*[, min_value, ...])

Create a dataclass field with integer range validation.

validated_string_field(*[, min_length, ...])

Create a dataclass field with string length validation.

Classes

IntRangeValidator(*[, min_value, max_value])

Descriptor for validating integer field values against min/max constraints.

IntValidationConstraints([min_value, max_value])

Container for integer validation constraints.

StrValidationConstraints([min_length, ...])

Container for string validation constraints.

StringLengthValidator(*[, min_length, ...])

Descriptor for validating string field values against length constraints.

ValidationConstraintsAbsent()

Sentinel/marker type indicating that no validation constraints are defined.

ValidatorBase([default, trust_initial_value])

Base dataclass descriptor for validating field values.
class pyg90alarm.dataclass.validation.ValidationConstraintsAbsent

Bases: object

Sentinel/marker type indicating that no validation constraints are defined.

This is used in type annotations and metadata to distinguish the absence of constraints from an explicit constraints container.

class pyg90alarm.dataclass.validation.IntValidationConstraints(min_value=None, max_value=None)

Bases: object

Container for integer validation constraints.

class pyg90alarm.dataclass.validation.StrValidationConstraints(min_length=None, max_length=None)

Bases: object

Container for string validation constraints.

class pyg90alarm.dataclass.validation.ValidatorBase(default=<pyg90alarm.dataclass.validation._DefaultNotSet object>, trust_initial_value=False)

Bases: Generic[T]

Base dataclass descriptor for validating field values.

Parameters:

  • default (TypeVar(T) | _DefaultNotSet) – Default value to return upon read if not provided during initialization. Use _DEFAULT_NOT_SET to mark the field as required.

  • trust_initial_value (bool) – If True, skips validation during dataclass initialization assuming init value is valid.

class pyg90alarm.dataclass.validation.IntRangeValidator(*, min_value=None, max_value=None, **kwargs)

Bases: ValidatorBase[int]

Descriptor for validating integer field values against min/max constraints.

The field value is validated when set. A ValueError is raised if the value is outside the specified range.

Example usage:

@dataclass class Example:

value: int = validated_int_field(min_value=0, max_value=100)

ex = Example(value=50) # OK ex.value = 100 # OK ex.value = 101 # Raises ValueError

Parameters:

  • min_value (int | None) – Minimum allowed value (inclusive), or None for no minimum.

  • max_value (int | None) – Maximum allowed value (inclusive), or None for no maximum.

  • * – Rest of the params are passed to base class.

class pyg90alarm.dataclass.validation.StringLengthValidator(*, min_length=None, max_length=None, **kwargs)

Bases: ValidatorBase[str]

Descriptor for validating string field values against length constraints.

The field value is validated when set. A ValueError is raised if the string length is outside the specified range.

Example usage:

@dataclass class Example:

name: str = validated_string_field(min_length=1, max_length=50)

ex = Example(name=”hello”) # OK ex.name = “a” # OK ex.name = “” # Raises ValueError

Parameters:

  • min_length (int | None) – Minimum string length (inclusive), or None for no minimum.

  • max_length (int | None) – Maximum string length (inclusive), or None for no maximum.

  • * – Rest of the params are passed to base class.

pyg90alarm.dataclass.validation.validated_int_field(*, min_value=None, max_value=None, default=<pyg90alarm.dataclass.validation._DefaultNotSet object>, trust_initial_value=False, **kwargs)

Create a dataclass field with integer range validation.

The field value will be validated when set, raising ValueError if outside the specified range. Validation constraints are stored in field metadata for later retrieval.

Parameters:

  • min_value (int | None) – Minimum allowed value (inclusive), or None for no minimum.

  • max_value (int | None) – Maximum allowed value (inclusive), or None for no maximum.

  • default (int | None | _DefaultNotSet) – Default value for the field when not provided. Omit to make the field required (raises ValueError when missing). Pass None explicitly to use None as the default.

  • trust_initial_value (bool) – If True, skips validation during dataclass initialization assuming init value is valid.

  • kwargs (Any) – Additional keyword arguments to pass to dataclasses.field().

Return type:

int

Returns:

A dataclass field with IntRangeValidator descriptor and metadata.

Example:

@dataclass class Config:

count: int = validated_int_field(

min_value=0, max_value=100, default=50

)

pyg90alarm.dataclass.validation.validated_string_field(*, min_length=None, max_length=None, default=<pyg90alarm.dataclass.validation._DefaultNotSet object>, trust_initial_value=False, **kwargs)

Create a dataclass field with string length validation.

The field value will be validated when set, raising ValueError if the string length is outside the specified range. Validation constraints are stored in field metadata for later retrieval.

Parameters:

  • min_length (int | None) – Minimum string length (inclusive), or None for no minimum.

  • max_length (int | None) – Maximum string length (inclusive), or None for no maximum.

  • default (str | None | _DefaultNotSet) – Default value for the field when not provided. Omit to make the field required (raises ValueError when missing). Pass None explicitly to use None as the default.

  • trust_initial_value (bool) – If True, skips validation during dataclass initialization assuming init value is valid.

  • kwargs (Any) – Additional keyword arguments to pass to dataclasses.field().

Return type:

str

Returns:

A dataclass field with StringLengthValidator descriptor and metadata.

Example:

@dataclass class Config:

name: str = validated_string_field(

min_length=1, max_length=50, default=”default”

)

pyg90alarm.dataclass.validation.get_field_validation_constraints(dataclass_type, field_name, expected_type=None)

Retrieve validation constraints for a specific dataclass field.

Parameters:

  • dataclass_type (DataclassInstance | type[DataclassInstance]) – The dataclass type or instance to inspect.

  • field_name (str) – The name of the field to get constraints for.

  • expected_type (Optional[type]) – Expected type of the field to determine which constraints to retrieve.

Return type:

Any

Returns:

Validation constraints container, or ValidationConstraintsAbsent if none found. The latter is to avoid returning None and free callers from having to check for it.

Example:

constraints = get_field_validation_constraints(Config, ‘count’, int) # Returns: object with constraints.min_value, constraints.max_value