Types Module

The types module provides a comprehensive set of classes and utilities for working with various data types, including version strings, numerical types, identifiers, and serialization formats. It focuses on enforcing validation rules and providing robust error handling.

Key Features

Version validation and parsing (SemVer, CalVer, Date Versioning)
Validated numeric types with constraints
UUID and ULID handling with versioning
Scientific number validation
Serialization support (JSON, YAML, TOML)
Type hints and generic utilities

Version Types

Version Base Classes

class VersionValidatorMixin: A mixin that provides version validation functionality.

class Version

Base class for version objects.

PATTERNS: ClassVar[set]: Set of supported version patterns.

major: str: Major version number.

minor: str: Minor version number.

patch: str = Optional: Patch version number.

tag: str = Optional: Version tag (e.g., alpha, beta).

Version Implementation Classes

class SemVersion: Semantic Versioning implementation (MAJOR.MINOR.PATCH[-TAG]).

class DateVersion: Date-based versioning implementation (YYYY.MM.DD[-TAG]).

class CalVersion: Calendar versioning implementation (YY.MM[-TAG]).

class MajorMinorVersion: Simple major.minor versioning without patch numbers.

Numeric Types

Base Classes

class ValidatedNumber(Generic[T])

Base class for validated numeric types.

classmethod validate(cls, value: int | float) → bool: Validate the input value.

classmethod get_error_message(cls, value: int | float) → str: Get the error message for invalid values.

Integer Types

class ValidatedInt(ValidatedNumber[int]): Base class for validated integer types.

class PositiveInt(ValidatedInt): Integer type that must be positive.

class NegativeInt(ValidatedInt): Integer type that must be negative.

class UnsignedInt(ValidatedInt): Integer type that must be non-negative.

class BigInt

Class for handling large integers with architecture-aware bounds.

Parameters:

value – Integer value
strict – Enable strict validation
context – Validation context (“Positive”, “Negative”, “Unsigned”)

Float Types

class ValidatedFloat(ValidatedNumber[float]): Base class for validated float types.

class PositiveFloat(ValidatedFloat): Float type that must be positive.

class NegativeFloat(ValidatedFloat): Float type that must be negative.

class UnsignedFloat(ValidatedFloat): Float type that must be non-negative.

class BigDecimal

Class for handling large decimal numbers.

Parameters:

value – Decimal value
strict – Enable strict validation
context – Validation context (“Positive”, “Negative”, “Unsigned”)
stop_warnings – Suppress warnings

Scientific Numbers

class ScientificNumber

Class for handling numbers in scientific notation.

classmethod is_scientific_notation(num_str: str) → bool: Check if a string represents scientific notation.

Special Number Types

class NaN: Not-a-Number type with validation.

Infinity: NewType('Infinity', float): Type for representing infinity.

PositiveInfinity = Infinity(float("inf"))

NegativeInfinity = Infinity(float("-inf"))

Identifier Types

UUID Types

class UUIDType: Base class for UUID handling.

class StrUUIDType(UUIDType): String-based UUID with validation.

class IntUUIDType(UUIDType): Integer-based UUID with validation.

Versioned UUID Types

class UUIDVersionMixin: Mixin for versioned UUID support.

class UUIDV1: UUID version 1 implementation (time-based).

class UUIDV2: UUID version 2 implementation (DCE Security).

class UUIDV3: UUID version 3 implementation (MD5 hash-based).

class UUIDV4: UUID version 4 implementation (random).

class UUIDV5: UUID version 5 implementation (SHA-1 hash-based).

class StrUUIDV1: String-based UUID version 1.

class StrUUIDV2: String-based UUID version 2.

class StrUUIDV3: String-based UUID version 3.

class StrUUIDV4: String-based UUID version 4.

class StrUUIDV5: String-based UUID version 5.

class IntUUIDV1: Integer-based UUID version 1.

class IntUUIDV2: Integer-based UUID version 2.

class IntUUIDV3: Integer-based UUID version 3.

class IntUUIDV4: Integer-based UUID version 4.

class IntUUIDV5: Integer-based UUID version 5.

ULID Types

class ULIDType: Base class for ULID handling.

class StrULIDType(ULIDType): String-based ULID with validation.

class IntULIDType(ULIDType): Integer-based ULID with validation.

Serialization Types

class JsonMixin

Mixin for JSON serialization support.

classmethod to_json(cls, value)

classmethod from_json(cls, value)

class YamlMixin

Mixin for YAML serialization support.

classmethod to_yaml(cls, value)

classmethod from_yaml(cls, value)

class TomlMixin

Mixin for TOML serialization support.

classmethod to_toml(cls, value)

classmethod from_toml(cls, value)

Type Aliases

JsonType: NewType('JsonType', dict)

XmlType: NewType('XmlType', dict)

YamlType: NewType('YamlType', dict)

TomlType: NewType('TomlType', dict)

Examples

Version Handling:

# Create a semantic version
version = SemVersion("1.2.3-beta")

# Create a calendar version
cal_version = CalVersion("23.04")

Numeric Validation:

# Create a positive integer
pos_int = PositiveInt(42)

# Create a big integer with constraints
big_int = BigInt(1000000, strict=True, context="Positive")

# Create a scientific number
sci_num = ScientificNumber("1.23e-4")

UUID Handling:

# Create a string UUID
uuid_str = StrUUIDType("550e8400-e29b-41d4-a716-446655440000")

# Create a version 4 UUID
uuid_v4 = UUIDV4("550e8400-e29b-41d4-a716-446655440000")

ULID Handling:

# Create a string ULID
ulid_str = StrULIDType("01ARZ3NDEKTSV4RRFFQ69G5FAV")

# Create an integer ULID
ulid_int = IntULIDType(1234567890)

Serialization:

class MyType(JsonMixin):
    def __init__(self, data):
        self.data = data

# Convert to/from JSON
obj = MyType({"key": "value"})
json_data = obj.to_json()
new_obj = MyType.from_json(json_data)

Notes

All numeric types include validation to ensure values meet specified constraints.
UUID and ULID implementations support both string and integer representations.
Version classes support various versioning schemes with proper validation.
Serialization mixins provide consistent interfaces for different formats.
All classes include proper type hints for better IDE support.