modmex 1.0.0__py3-none-any.whl

modmex/__init__.py

@@ -0,0 +1,15 @@
+from .base_model import (
+    BaseModel,
+    field_validator,
+    model_validator,
+)
+from .errors import ValidationError
+from .fields import Field
+
+__all__ = [
+    "BaseModel",
+    "Field",
+    "ValidationError",
+    "field_validator",
+    "model_validator",
+]

modmex/base_model.py

@@ -0,0 +1,166 @@
+"""Dataclass-backed model base with validation and serialization helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from typing import Any, Callable
+
+import orjson
+
+from .fields import should_exclude_field
+from .serialization import ExcludeSpec, TypeSerializers, custom_serializer, normalize_exclude, serialize_value
+from .validation import validate_model_fields
+
+
+def field_validator(field_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorate a method that validates or transforms one field."""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        func._validator_field = field_name  # type: ignore[attr-defined]
+        return func
+
+    return decorator
+
+
+def model_validator(mode: str = "before") -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorate a method that validates or transforms the full model."""
+
+    if mode not in {"before", "after"}:
+        raise ValueError("model validator mode must be 'before' or 'after'")
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        func._validator_mode = mode  # type: ignore[attr-defined]
+        return func
+
+    return decorator
+
+
+class BaseModelMeta(type):
+    def __new__(mcls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]) -> type:
+        model_cls = super().__new__(mcls, name, bases, namespace)
+        dataclass(model_cls, kw_only=True)
+
+        original_init = model_cls.__init__
+
+        def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+            valid_fields = {field.name for field in fields(model_cls)}
+            filtered_kwargs = {key: value for key, value in kwargs.items() if key in valid_fields}
+            original_init(self, *args, **filtered_kwargs)
+
+        model_cls.__init__ = new_init
+        return model_cls
+
+
+class BaseModel(metaclass=BaseModelMeta):
+    """Base class for lightweight validated models."""
+
+    def __post_init__(self) -> None:
+        self._validate_model_before()
+        self._validate_types()
+        self._validate_fields()
+        self._validate_model_after()
+
+    def _validate_types(self) -> None:
+        validate_model_fields(self)
+
+    def _validate_model_before(self) -> None:
+        self._run_model_validators("before")
+
+    def _validate_model_after(self) -> None:
+        self._run_model_validators("after")
+
+    def _run_model_validators(self, mode: str) -> None:
+        for attr_name in dir(self):
+            if isinstance(getattr(type(self), attr_name, None), property):
+                continue
+
+            attr = getattr(self, attr_name)
+            if callable(attr) and getattr(attr, "_validator_mode", None) == mode:
+                updated_values = attr(self.__dict__.copy())
+                if updated_values is not None:
+                    self.__dict__.update(updated_values)
+
+    def _validate_fields(self) -> None:
+        for attr_name in dir(self):
+            if isinstance(getattr(type(self), attr_name, None), property):
+                continue
+
+            attr = getattr(self, attr_name)
+            field_name = getattr(attr, "_validator_field", None)
+            if callable(attr) and field_name:
+                setattr(self, field_name, attr(getattr(self, field_name, None)))
+
+    def _append_properties(
+        self,
+        data: dict[str, Any],
+        exclude: Mapping[str, Any],
+        profile: str | None,
+        type_serializers: TypeSerializers,
+    ) -> dict[str, Any]:
+        for attr_name in dir(self):
+            if attr_name in exclude:
+                continue
+            if isinstance(getattr(type(self), attr_name, None), property):
+                data[attr_name] = serialize_value(
+                    getattr(self, attr_name),
+                    exclude=None,
+                    profile=profile,
+                    type_serializers=type_serializers,
+                )
+        return data
+
+    def _serialize(
+        self,
+        exclude: ExcludeSpec = None,
+        profile: str | None = None,
+        include_excluded: bool = False,
+        type_serializers: TypeSerializers = None,
+    ) -> dict[str, Any]:
+        exclude_map = normalize_exclude(exclude)
+        result = {
+            field.name: serialize_value(
+                getattr(self, field.name),
+                exclude=exclude_map.get(field.name),
+                profile=profile,
+                include_excluded=include_excluded,
+                type_serializers=type_serializers,
+            )
+            for field in fields(self)
+            if not should_exclude_field(field, exclude_map.get(field.name), profile, include_excluded)
+        }
+        return self._append_properties(result, exclude_map, profile, type_serializers)
+
+    def model_dump(
+        self,
+        *,
+        exclude: ExcludeSpec = None,
+        profile: str | None = None,
+        include_excluded: bool = False,
+        type_serializers: TypeSerializers = None,
+    ) -> dict[str, Any]:
+        return self._serialize(
+            exclude=exclude,
+            profile=profile,
+            include_excluded=include_excluded,
+            type_serializers=type_serializers,
+        )
+
+    def model_dump_json(
+        self,
+        *,
+        exclude: ExcludeSpec = None,
+        profile: str | None = None,
+        include_excluded: bool = False,
+        type_serializers: TypeSerializers = None,
+    ) -> str:
+        return orjson.dumps(
+            self.model_dump(
+                exclude=exclude,
+                profile=profile,
+                include_excluded=include_excluded,
+                type_serializers=type_serializers,
+            ),
+            option=orjson.OPT_PASSTHROUGH_DATETIME,
+            default=custom_serializer,
+        ).decode("utf-8")

modmex/datetime_parser.py

@@ -0,0 +1,239 @@
+"""Parse date, time, datetime, and duration values."""
+import re
+from datetime import date, datetime, time, timedelta, timezone
+from typing import Optional, Union
+
+
+date_expr = r'(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})'
+time_expr = (
+    r'(?P<hour>\d{1,2}):(?P<minute>\d{1,2})'
+    r'(?::(?P<second>\d{1,2})(?:\.(?P<microsecond>\d{1,6})\d{0,6})?)?'
+    r'(?P<tzinfo>Z|[+-]\d{2}(?::?\d{2})?)?$'
+)
+
+date_re = re.compile(f'{date_expr}$')
+time_re = re.compile(time_expr)
+datetime_re = re.compile(f'{date_expr}[T ]{time_expr}')
+
+standard_duration_re = re.compile(
+    r'^'
+    r'(?:(?P<days>-?\d+) (days?, )?)?'
+    r'((?:(?P<hours>-?\d+):)(?=\d+:\d+))?'
+    r'(?:(?P<minutes>-?\d+):)?'
+    r'(?P<seconds>-?\d+)'
+    r'(?:\.(?P<microseconds>\d{1,6})\d{0,6})?'
+    r'$'
+)
+
+# Support the sections of ISO 8601 date representation that are accepted by timedelta
+iso8601_duration_re = re.compile(
+    r'^(?P<sign>[-+]?)'
+    r'P'
+    r'(?:(?P<days>\d+(.\d+)?)D)?'
+    r'(?:T'
+    r'(?:(?P<hours>\d+(.\d+)?)H)?'
+    r'(?:(?P<minutes>\d+(.\d+)?)M)?'
+    r'(?:(?P<seconds>\d+(.\d+)?)S)?'
+    r')?'
+    r'$'
+)
+
+EPOCH = datetime(1970, 1, 1)
+# if greater than this, the number is in ms, if less than or equal it's in seconds
+# (in seconds this is 11th October 2603, in ms it's 20th August 1970)
+MS_WATERSHED = int(2e10)
+# slightly more than datetime.max in ns - (datetime.max - EPOCH).total_seconds() * 1e9
+MAX_NUMBER = int(3e20)
+StrBytesIntFloat = Union[str, bytes, int, float]
+
+
+def get_numeric(value: StrBytesIntFloat, native_expected_type: str) -> Union[None, int, float]:
+    if isinstance(value, (int, float)):
+        return value
+    try:
+        return float(value)
+    except ValueError:
+        return None
+    except TypeError:
+        raise TypeError(f'invalid type; expected {native_expected_type}, string, bytes, int or float')
+
+
+def from_unix_seconds(seconds: Union[int, float]) -> datetime:
+    if seconds > MAX_NUMBER:
+        return datetime.max
+    elif seconds < -MAX_NUMBER:
+        return datetime.min
+
+    while abs(seconds) > MS_WATERSHED:
+        seconds /= 1000
+    dt = EPOCH + timedelta(seconds=seconds)
+    return dt.replace(tzinfo=timezone.utc)
+
+
+def _parse_timezone(value: Optional[str]) -> timezone | None:
+    if value == 'Z':
+        return timezone.utc
+    elif value is not None:
+        offset_mins = int(value[-2:]) if len(value) > 3 else 0
+        offset = 60 * int(value[1:3]) + offset_mins
+        if value[0] == '-':
+            offset = -offset
+        try:
+            return timezone(timedelta(minutes=offset))
+        except ValueError as exc:
+            raise ValueError("invalid timezone") from exc
+    return None
+
+
+def parse_date(value: Union[date, StrBytesIntFloat]) -> date:
+    """
+    Parse a date/int/float/string and return a datetime.date.
+
+    Raise ValueError if the input is well formatted but not a valid date.
+    Raise ValueError if the input isn't well formatted.
+    """
+    if isinstance(value, date):
+        if isinstance(value, datetime):
+            return value.date()
+        else:
+            return value
+
+    number = get_numeric(value, 'date')
+    if number is not None:
+        return from_unix_seconds(number).date()
+
+    if isinstance(value, bytes):
+        value = value.decode()
+
+    match = date_re.match(value)  # type: ignore
+    if match is None:
+        # Fallback: try parsing as a datetime string and extract the date part
+        dt_match = datetime_re.match(value)
+        if dt_match is None:
+            raise ValueError("invalid date")
+        try:
+            # Validate that the time and timezone sections are also valid.
+            return parse_datetime(value).date()
+        except ValueError as exc:
+            raise ValueError("invalid date") from exc
+
+    kw = {k: int(v) for k, v in match.groupdict().items()}
+
+    try:
+        return date(**kw)
+    except ValueError as exc:
+        raise ValueError("invalid date") from exc
+
+
+def parse_time(value: Union[time, StrBytesIntFloat]) -> time:
+    """
+    Parse a time/string and return a datetime.time.
+
+    Raise ValueError if the input is well formatted but not a valid time.
+    Raise ValueError if the input isn't well formatted, in particular if it contains an offset.
+    """
+    if isinstance(value, time):
+        return value
+
+    number = get_numeric(value, 'time')
+    if number is not None:
+        if number >= 86400:
+            # doesn't make sense since the time time loop back around to 0
+            raise ValueError("invalid time")
+        return (datetime.min + timedelta(seconds=number)).time()
+
+    if isinstance(value, bytes):
+        value = value.decode()
+
+    match = time_re.match(value)  # type: ignore
+    if match is None:
+        raise ValueError("invalid time")
+
+    kw = match.groupdict()
+    if kw['microsecond']:
+        kw['microsecond'] = kw['microsecond'].ljust(6, '0')
+
+    tzinfo = _parse_timezone(kw.pop('tzinfo'))
+    kw_: dict[str, Union[None, int, timezone]] = {k: int(v) for k, v in kw.items() if v is not None}
+    kw_['tzinfo'] = tzinfo
+
+    try:
+        return time(**kw_)  # type: ignore
+    except ValueError as exc:
+        raise ValueError("invalid time") from exc
+
+
+def parse_datetime(value: Union[datetime, StrBytesIntFloat]) -> datetime:
+    """
+    Parse a datetime/int/float/string and return a datetime.datetime.
+
+    This function supports time zone offsets. When the input contains one,
+    the output uses a timezone with a fixed offset from UTC.
+
+    Raise ValueError if the input is well formatted but not a valid datetime.
+    Raise ValueError if the input isn't well formatted.
+    """
+    if isinstance(value, datetime):
+        return value
+
+    number = get_numeric(value, 'datetime')
+    if number is not None:
+        return from_unix_seconds(number)
+
+    if isinstance(value, bytes):
+        value = value.decode()
+
+    match = datetime_re.match(value)  # type: ignore
+    if match is None:
+        raise ValueError("invalid datetime")
+
+    kw = match.groupdict()
+    if kw['microsecond']:
+        kw['microsecond'] = kw['microsecond'].ljust(6, '0')
+
+    tzinfo = _parse_timezone(kw.pop('tzinfo'))
+    kw_: dict[str, Union[None, int, timezone]] = {k: int(v) for k, v in kw.items() if v is not None}
+    kw_['tzinfo'] = tzinfo
+
+    try:
+        return datetime(**kw_)  # type: ignore
+    except ValueError as exc:
+        raise ValueError("invalid datetime") from exc
+
+
+def parse_duration(value: StrBytesIntFloat) -> timedelta:
+    """
+    Parse a duration int/float/string and return a datetime.timedelta.
+
+    The preferred format for durations in Django is '%d %H:%M:%S.%f'.
+
+    Also supports ISO 8601 representation.
+    """
+    if isinstance(value, timedelta):
+        return value
+
+    if isinstance(value, (int, float)):
+        # below code requires a string
+        value = f'{value:f}'
+    elif isinstance(value, bytes):
+        value = value.decode()
+
+    try:
+        match = standard_duration_re.match(value) or iso8601_duration_re.match(value)
+    except TypeError:
+        raise TypeError('invalid type; expected timedelta, string, bytes, int or float')
+
+    if not match:
+        raise ValueError("invalid duration")
+
+    kw = match.groupdict()
+    sign = -1 if kw.pop('sign', '+') == '-' else 1
+    if kw.get('microseconds'):
+        kw['microseconds'] = kw['microseconds'].ljust(6, '0')
+
+    if kw.get('seconds') and kw.get('microseconds') and kw['seconds'].startswith('-'):
+        kw['microseconds'] = '-' + kw['microseconds']
+
+    kw_ = {k: float(v) for k, v in kw.items() if v is not None}
+
+    return sign * timedelta(**kw_)

modmex/errors.py

@@ -0,0 +1,16 @@
+
+"""Exception types raised by modmex."""
+
+
+class ValidationError(Exception):
+    def __init__(self, errors: list[dict], message: str = "Validation errors occurred"):
+        super().__init__(message)
+        self.errors = errors
+
+    def _format_error_message(self) -> str:
+        return "\n".join(
+            f"Error at {'.'.join(map(str, error['loc']))}: {error['msg']}" for error in self.errors
+        )
+
+    def __str__(self) -> str:
+        return self._format_error_message()

modmex/fields.py

@@ -0,0 +1,57 @@
+"""Field helpers for dataclass-backed models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import MISSING, Field as DataclassField
+from dataclasses import field as dataclass_field
+from typing import Any, Callable
+
+_EXCLUDE = "__modmex_exclude__"
+_EXCLUDE_FROM = "__modmex_exclude_from__"
+
+
+def Field(
+    default: Any = MISSING,
+    *,
+    default_factory: Callable[[], Any] | Any = MISSING,
+    exclude: bool = False,
+    exclude_from: Iterable[str] | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Create a dataclass field with modmex serialization options."""
+    field_metadata = dict(metadata or {})
+    field_metadata[_EXCLUDE] = exclude
+    field_metadata[_EXCLUDE_FROM] = _normalize_profiles(exclude_from)
+
+    if default is not MISSING and default_factory is not MISSING:
+        raise ValueError("cannot specify both default and default_factory")
+    if default is not MISSING:
+        return dataclass_field(default=default, metadata=field_metadata, **kwargs)
+    if default_factory is not MISSING:
+        return dataclass_field(default_factory=default_factory, metadata=field_metadata, **kwargs)
+    return dataclass_field(metadata=field_metadata, **kwargs)
+
+
+def should_exclude_field(
+    field: DataclassField[Any],
+    explicit_exclude: Any,
+    profile: str | None,
+    include_excluded: bool,
+) -> bool:
+    if explicit_exclude is True:
+        return True
+    if include_excluded:
+        return False
+    if field.metadata.get(_EXCLUDE, False):
+        return True
+    return profile is not None and profile in field.metadata.get(_EXCLUDE_FROM, frozenset())
+
+
+def _normalize_profiles(profiles: Iterable[str] | None) -> frozenset[str]:
+    if profiles is None:
+        return frozenset()
+    if isinstance(profiles, str):
+        return frozenset({profiles})
+    return frozenset(profiles)

modmex/serialization.py

@@ -0,0 +1,123 @@
+"""Serialization helpers for model dumps and JSON encoding."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from typing import Any, Callable
+
+ExcludeSpec = str | Iterable[str] | Mapping[str, Any] | None
+TypeSerializer = Callable[[Any], Any]
+TypeSerializers = Mapping[type[Any], TypeSerializer] | None
+
+
+def _serialize_by_type(value: Any, type_serializers: TypeSerializers) -> Any:
+    if not type_serializers:
+        return value
+
+    for expected_type, serializer in type_serializers.items():
+        if isinstance(value, expected_type):
+            return serializer(value)
+    return value
+
+
+def normalize_exclude(exclude: ExcludeSpec) -> dict[str, Any]:
+    if exclude is None:
+        return {}
+    if isinstance(exclude, str):
+        return {exclude: True}
+    if isinstance(exclude, Mapping):
+        return dict(exclude)
+    return {field_name: True for field_name in exclude}
+
+
+def excludes_entire_value(exclude: Any) -> bool:
+    return exclude is True
+
+
+def serialize_value(
+    value: Any,
+    exclude: ExcludeSpec = None,
+    profile: str | None = None,
+    include_excluded: bool = False,
+    type_serializers: TypeSerializers = None,
+) -> Any:
+    value = _serialize_by_type(value, type_serializers)
+
+    if hasattr(value, "model_dump") and callable(value.model_dump):
+        nested_exclude = None if exclude is True else exclude
+        return value.model_dump(
+            exclude=nested_exclude,
+            profile=profile,
+            include_excluded=include_excluded,
+            type_serializers=type_serializers,
+        )
+    if isinstance(value, list):
+        nested_exclude = None if exclude is True else exclude
+        return [
+            serialize_value(
+                item,
+                exclude=nested_exclude,
+                profile=profile,
+                include_excluded=include_excluded,
+                type_serializers=type_serializers,
+            )
+            for item in value
+        ]
+    if isinstance(value, tuple):
+        nested_exclude = None if exclude is True else exclude
+        return tuple(
+            serialize_value(
+                item,
+                exclude=nested_exclude,
+                profile=profile,
+                include_excluded=include_excluded,
+                type_serializers=type_serializers,
+            )
+            for item in value
+        )
+    if isinstance(value, dict):
+        exclude_map = normalize_exclude(exclude)
+        return {
+            key: serialize_value(
+                item,
+                exclude=exclude_map.get(key),
+                profile=profile,
+                include_excluded=include_excluded,
+                type_serializers=type_serializers,
+            )
+            for key, item in value.items()
+            if not excludes_entire_value(exclude_map.get(key))
+        }
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, time):
+        return value.isoformat()
+    if isinstance(value, timedelta):
+        return value.total_seconds()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Decimal):
+        return float(value)
+    return value
+
+
+def custom_serializer(obj: Any) -> Any:
+    """Serialize values that orjson does not handle by default."""
+    if isinstance(obj, Enum):
+        return obj.value
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, date):
+        return obj.isoformat()
+    if isinstance(obj, time):
+        return obj.isoformat()
+    if isinstance(obj, timedelta):
+        return obj.total_seconds()
+    if isinstance(obj, Decimal):
+        return float(obj)
+    raise TypeError(f"Type {type(obj)} not serializable")

modmex/validation.py

@@ -0,0 +1,339 @@
+"""Type coercion and validation helpers for dataclass-backed models."""
+
+from __future__ import annotations
+
+import dataclasses
+import sys
+import types
+import typing
+from collections.abc import Callable as CallableABC
+from collections.abc import Mapping
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal, DecimalException
+from enum import Enum
+from typing import Any, Callable, Literal, get_args, get_origin
+
+from .datetime_parser import parse_date, parse_datetime, parse_duration, parse_time
+from .errors import ValidationError
+
+GlobalNS_T = dict[str, Any]
+Loc = list[str | int]
+
+NoneType = type(None)
+_NONE_TYPES: tuple[Any, ...] = (None, NoneType, Literal[None])
+
+
+def is_none_type(tp: Any) -> bool:
+    """Return whether ``tp`` represents ``None`` in a type annotation."""
+    return tp in _NONE_TYPES
+
+
+def str_validator(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, Enum):
+        return str(value.value)
+    if isinstance(value, (float, int, Decimal)):
+        return str(value)
+    if isinstance(value, (bytes, bytearray)):
+        return value.decode()
+    raise ValueError("invalid str")
+
+
+def int_validator(value: Any) -> int:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    try:
+        return int(value)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValueError(f"'{value}' is not a valid integer") from exc
+
+
+BOOL_FALSE = {0, "0", "off", "f", "false", "n", "no"}
+BOOL_TRUE = {1, "1", "on", "t", "true", "y", "yes"}
+
+
+def bool_validator(value: Any) -> bool:
+    if value is True or value is False:
+        return value
+    if isinstance(value, bytes):
+        value = value.decode()
+    if isinstance(value, str):
+        value = value.lower()
+    try:
+        if value in BOOL_TRUE:
+            return True
+        if value in BOOL_FALSE:
+            return False
+    except TypeError as exc:
+        raise ValueError("invalid bool") from exc
+    raise ValueError("invalid bool")
+
+
+def float_validator(value: Any) -> float:
+    if isinstance(value, float):
+        return value
+    try:
+        return float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("invalid float") from exc
+
+
+def decimal_validator(value: Any) -> Decimal:
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, (bytes, bytearray)):
+        value = value.decode()
+
+    try:
+        decimal_value = Decimal(str(value).strip())
+    except DecimalException as exc:
+        raise ValueError("invalid decimal") from exc
+
+    if not decimal_value.is_finite():
+        raise ValueError("decimal is not finite")
+    return decimal_value
+
+
+def callable_validator(value: Any) -> Callable[..., Any]:
+    if callable(value):
+        return value
+    raise ValueError("invalid callable")
+
+
+_VALIDATORS: dict[Any, Callable[[Any], Any]] = {
+    str: str_validator,
+    int: int_validator,
+    bool: bool_validator,
+    float: float_validator,
+    datetime: parse_datetime,
+    date: parse_date,
+    time: parse_time,
+    timedelta: parse_duration,
+    Decimal: decimal_validator,
+    Callable: callable_validator,
+}
+
+
+def _error(loc: Loc, message: str, error_type: str = "value_error") -> ValidationError:
+    return ValidationError(errors=[{"loc": loc, "msg": message, "type": error_type}])
+
+
+def _merge_nested_errors(loc: Loc, exc: ValidationError) -> ValidationError:
+    return ValidationError(
+        errors=[
+            {
+                "loc": loc + list(error.get("loc", [])),
+                "msg": error.get("msg", str(error)),
+                "type": error.get("type", "type_error"),
+            }
+            for error in exc.errors
+        ]
+    )
+
+
+def _evaluate_forward_reference(ref_type: typing.ForwardRef, globalns: GlobalNS_T) -> Any:
+    if sys.version_info < (3, 9):
+        return ref_type._evaluate(globalns, None)
+    return ref_type._evaluate(globalns, None, recursive_guard=set())
+
+
+def _validate_simple_type(expected_type: type[Any], value: Any, loc: Loc) -> Any:
+    if expected_type in _VALIDATORS:
+        try:
+            return _VALIDATORS[expected_type](value)
+        except ValueError as exc:
+            raise _error(loc, str(exc)) from exc
+
+    if expected_type is Any:
+        return value
+
+    if isinstance(expected_type, type) and issubclass(expected_type, Enum):
+        if isinstance(value, expected_type):
+            return value
+        try:
+            return expected_type(value)
+        except ValueError as exc:
+            raise _error(loc, str(exc)) from exc
+
+    if isinstance(value, expected_type):
+        return value
+
+    if dataclasses.is_dataclass(expected_type) and isinstance(value, Mapping):
+        try:
+            return expected_type(**value)
+        except ValidationError as exc:
+            raise _merge_nested_errors(loc, exc) from exc
+        except TypeError as exc:
+            raise _error(loc, str(exc), "type_error") from exc
+
+    try:
+        return expected_type(value)
+    except ValueError as exc:
+        raise _error(loc, str(exc)) from exc
+    except TypeError as exc:
+        raise _error(loc, f"Error instantiating {expected_type.__name__}: {exc}", "type_error") from exc
+
+
+def _validate_list(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc) -> list[Any]:
+    if not isinstance(value, list):
+        raise _error(loc, "must be a list", "type_error.list")
+
+    item_type = _first_arg(expected_type, Any)
+    return [
+        _validate_types(item_type, item, strict, globalns, loc + [index])
+        for index, item in enumerate(value)
+    ]
+
+
+def _validate_tuple(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc) -> tuple[Any, ...]:
+    if not isinstance(value, tuple):
+        raise _error(loc, "must be a tuple", "type_error.tuple")
+
+    args = get_args(expected_type)
+    if not args:
+        return value
+    if len(args) == 2 and args[1] is Ellipsis:
+        return tuple(
+            _validate_types(args[0], item, strict, globalns, loc + [index])
+            for index, item in enumerate(value)
+        )
+    if len(args) != len(value):
+        raise _error(loc, f"expected {len(args)} items, received {len(value)}", "value_error.tuple.length")
+    return tuple(
+        _validate_types(item_type, item, strict, globalns, loc + [index])
+        for index, (item_type, item) in enumerate(zip(args, value))
+    )
+
+
+def _validate_dict(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc) -> dict[Any, Any]:
+    if not isinstance(value, dict):
+        raise _error(loc, "must be a dict", "type_error.dict")
+
+    key_type, value_type = _dict_args(expected_type)
+    return {
+        _validate_types(key_type, key, strict, globalns, loc + [key]): _validate_types(
+            value_type,
+            item,
+            strict,
+            globalns,
+            loc + [key],
+        )
+        for key, item in value.items()
+    }
+
+
+def _validate_set(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc) -> set[Any]:
+    if not isinstance(value, set):
+        raise _error(loc, "must be a set", "type_error.set")
+
+    item_type = _first_arg(expected_type, Any)
+    return {
+        _validate_types(item_type, item, strict, globalns, loc + [index])
+        for index, item in enumerate(value)
+    }
+
+
+def _validate_literal(expected_type: Any, value: Any, loc: Loc) -> Any:
+    allowed = get_args(expected_type)
+    if value not in allowed:
+        values = ", ".join(map(str, allowed))
+        raise _error(loc, f"must be one of [{values}] but received {value}", "value_error.literal")
+    return value
+
+
+def _validate_union(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc) -> Any:
+    errors: list[dict[str, Any]] = []
+    for item_type in get_args(expected_type):
+        try:
+            return _validate_types(item_type, value, strict, globalns, loc)
+        except ValidationError as exc:
+            errors.extend(exc.errors)
+
+    if errors:
+        raise ValidationError(errors=errors)
+    raise _error(loc, f"must be an instance of {expected_type}, but received {value}", "type_error.union")
+
+
+def _first_arg(expected_type: Any, default: Any) -> Any:
+    args = get_args(expected_type)
+    return args[0] if args else default
+
+
+def _dict_args(expected_type: Any) -> tuple[Any, Any]:
+    args = get_args(expected_type)
+    if len(args) == 2:
+        return args
+    return Any, Any
+
+
+def _validate_types(expected_type: Any, value: Any, strict: bool, globalns: GlobalNS_T, loc: Loc | None = None) -> Any:
+    loc = loc or []
+
+    if isinstance(expected_type, str):
+        expected_type = typing.ForwardRef(expected_type)
+
+    if isinstance(expected_type, typing.ForwardRef):
+        expected_type = _evaluate_forward_reference(expected_type, globalns)
+
+    if is_none_type(expected_type):
+        if value is None:
+            return None
+        raise _error(loc, f"{value} is not a valid none value", "value_error.none")
+
+    origin = get_origin(expected_type)
+    if origin is None:
+        if isinstance(expected_type, type):
+            return _validate_simple_type(expected_type, value, loc)
+        if expected_type is Any:
+            return value
+        if strict:
+            raise RuntimeError(f"Unknown type of {expected_type}")
+        return value
+
+    if origin is list:
+        return _validate_list(expected_type, value, strict, globalns, loc)
+    if origin is tuple:
+        return _validate_tuple(expected_type, value, strict, globalns, loc)
+    if origin is dict:
+        return _validate_dict(expected_type, value, strict, globalns, loc)
+    if origin is set:
+        return _validate_set(expected_type, value, strict, globalns, loc)
+    if origin is frozenset:
+        if not isinstance(value, frozenset):
+            raise _error(loc, "must be a frozenset", "type_error.frozenset")
+        return frozenset(_validate_set(expected_type, set(value), strict, globalns, loc))
+    if origin is Literal:
+        return _validate_literal(expected_type, value, loc)
+    if origin in (typing.Union, types.UnionType):
+        return _validate_union(expected_type, value, strict, globalns, loc)
+    if origin in (Callable, CallableABC):
+        return callable_validator(value)
+
+    if strict:
+        raise RuntimeError(f"Unknown type of {expected_type}")
+    return value
+
+
+def validate_model_fields(target: Any, strict: bool = False) -> None:
+    """Coerce and validate all dataclass fields on ``target`` in place."""
+    globalns = sys.modules[target.__module__].__dict__.copy()
+    try:
+        type_hints = typing.get_type_hints(target.__class__, globalns=globalns, include_extras=True)
+    except Exception:
+        type_hints = {}
+    errors: list[dict[str, Any]] = []
+
+    for field in dataclasses.fields(target):
+        value = getattr(target, field.name)
+        expected_type = type_hints.get(field.name, field.type)
+        try:
+            validated = _validate_types(expected_type, value, strict, globalns, loc=[field.name])
+            setattr(target, field.name, validated)
+        except ValidationError as exc:
+            errors.extend(exc.errors)
+        except Exception as exc:
+            errors.append({"loc": [field.name], "msg": str(exc), "type": "unexpected_error"})
+
+    if errors:
+        raise ValidationError(errors=errors)

modmex-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modmex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modmex-1.0.0.dist-info/METADATA

@@ -0,0 +1,407 @@
+Metadata-Version: 2.3
+Name: modmex
+Version: 1.0.0
+Summary: Lightweight Python models built on dataclasses with validation, serialization, and type-safe data mapping
+License: MIT
+Author: clandro89@gmail.com
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: orjson (>=3.11.9,<4.0.0)
+Description-Content-Type: text/markdown
+
+# modmex
+
+Lightweight Python models built on dataclasses with validation, serialization, and type-safe data mapping.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/modmex/modmex/ci.yml?branch=main&logo=github&label=CI)](https://github.com/modmex/modmex/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/modmex/modmex?label=coverage)](https://codecov.io/gh/modmex/modmex)
+[![PyPI](https://img.shields.io/pypi/v/modmex.svg)](https://pypi.org/project/modmex/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/modmex.svg)](https://pypi.org/project/modmex/)
+[![License](https://img.shields.io/github/license/modmex/modmex.svg)](https://github.com/modmex/modmex/blob/main/LICENSE)
+
+modmex gives you a small but powerful toolkit for:
+
+- Typed models with minimal boilerplate.
+- Automatic coercion and validation at initialization time.
+- Recursive serialization to Python primitives and JSON.
+- Per-field and per-model validation hooks.
+- Type-based custom serializers to adapt output for different consumers.
+
+
+## Why modmex
+
+If you want stricter models than plain dataclasses, but without the weight of a large framework, modmex is designed for that middle ground.
+
+It focuses on:
+
+- Simplicity: small API surface.
+- Predictability: explicit model lifecycle.
+- Flexibility: configurable serialization without changing your model definitions.
+
+
+## Installation
+
+With pip:
+
+```bash
+pip install modmex
+```
+
+With Poetry:
+
+```bash
+poetry add modmex
+```
+
+
+
+
+## Quick Start
+
+```python
+from decimal import Decimal
+
+from modmex import BaseModel, Field
+
+
+class User(BaseModel):
+    id: int
+    name: str
+    balance: Decimal = Decimal("0")
+    password: str = Field("", exclude=True)
+
+
+user = User(id="1", name=123, balance="10.50")
+
+# Type coercion happens during initialization.
+assert user.id == 1
+assert user.name == "123"
+assert user.balance == Decimal("10.50")
+
+# model_dump returns primitive/serializable values.
+assert user.model_dump() == {
+    "id": 1,
+    "name": "123",
+    "balance": 10.5,
+}
+
+# model_dump_json returns a JSON string.
+assert user.model_dump_json() == '{"id":1,"name":"123","balance":10.5}'
+```
+
+## Field Configuration
+
+Use `Field(...)` to add serialization metadata to a model field.
+
+Main options:
+
+- `exclude=True`
+  - Always excludes this field from `model_dump` and `model_dump_json`.
+- `exclude_from={"profile_name"}`
+  - Excludes this field only for selected serialization profiles.
+
+Example:
+
+```python
+from modmex import BaseModel, Field
+
+
+class Session(BaseModel):
+    id: str
+    secret: str = Field("", exclude_from={"public"})
+
+
+class User(BaseModel):
+    id: int
+    private_note: str = Field("x", exclude=True)
+    sessions: list[Session] = Field(default_factory=list)
+
+
+user = User(id=1, sessions=[Session(id="s1", secret="abc")])
+
+assert user.model_dump(profile="public") == {
+    "id": 1,
+    "sessions": [{"id": "s1"}],
+}
+```
+
+Tip:
+
+- Use `exclude=True` for values that should never leave the model.
+- Use `exclude_from={...}` when omission depends on the output profile.
+
+
+
+## Everyday Usage
+
+### 1) Parse and normalize input data
+
+```python
+from modmex import BaseModel
+
+
+class Product(BaseModel):
+    id: int
+    name: str
+    active: bool
+
+
+product = Product(id="10", name=123, active="true")
+
+assert product.id == 10
+assert product.name == "123"
+assert product.active is True
+```
+
+### 2) Work with nested models
+
+```python
+from modmex import BaseModel
+
+
+class Address(BaseModel):
+    zipcode: int
+
+
+class User(BaseModel):
+    id: int
+    address: Address
+
+
+user = User(id="1", address={"zipcode": "90210"})
+assert user.address.zipcode == 90210
+```
+
+### 3) Prepare different payloads from the same model
+
+```python
+api_payload = account.model_dump(profile="public")
+internal_payload = account.model_dump()
+```
+
+### 4) Build JSON directly
+
+```python
+json_payload = account.model_dump_json(profile="public")
+```
+
+
+## Validators
+
+### Field validators
+
+Use `@field_validator("field_name")` to transform or validate a single field.
+
+```python
+from modmex import BaseModel, field_validator
+
+
+class Product(BaseModel):
+    name: str
+
+    @field_validator("name")
+    def normalize_name(self, value: str) -> str:
+        return value.strip().title()
+```
+
+
+### Model validators
+
+Use `@model_validator(mode="before" | "after")` to work with full model state.
+
+- `before`: runs before type coercion.
+- `after`: runs after field-level validation.
+
+```python
+from modmex import BaseModel, model_validator
+
+
+class Product(BaseModel):
+    name: str
+    slug: str = ""
+
+    @model_validator(mode="before")
+    def build_slug(self, values: dict) -> dict:
+        values["slug"] = values["name"].lower().replace(" ", "-")
+        return values
+```
+
+
+## Serialization
+
+### `model_dump(...)`
+
+Use `model_dump` when you need a dictionary payload.
+
+Most common options:
+
+- `exclude={...}` to omit fields for a specific call.
+- `profile="..."` to apply `exclude_from` rules.
+- `include_excluded=True` to force metadata-excluded fields into the payload.
+- `type_serializers={...}` to control how specific Python types are represented.
+
+
+### `model_dump_json(...)`
+
+Use `model_dump_json` when you need a JSON string output.
+
+It supports the same practical options as `model_dump` (`exclude`, `profile`, `include_excluded`, `type_serializers`).
+
+## Omitting Fields During Serialization
+
+Use this feature when the same model must produce different payloads depending on where the data is going.
+
+- `exclude_from` defines where a field should be omitted.
+- `profile` selects which omission rules to apply in a specific dump call.
+
+### What each option does
+
+- `exclude_from={"public"}`
+    - Omit this field when serializing with `profile="public"`.
+- `profile="public"`
+    - Apply all field rules tagged for `public` during serialization.
+
+### Common pattern
+
+You may want one shape for API responses and another for internal flows (logs, queues, exports, persistence payloads, etc.).
+
+- API payload (`profile="public"`): hide internal fields.
+- Internal payload (no profile, or another profile): keep those fields.
+
+### Example
+
+```python
+from modmex import BaseModel, Field
+
+
+class Account(BaseModel):
+    id: int
+    email: str = Field("", exclude_from={"public"})
+    internal_note: str = Field("", exclude=True)
+
+
+account = Account(id=1, email="a@x.com", internal_note="secret")
+
+# No profile: only always-excluded fields are removed.
+assert account.model_dump() == {
+    "id": 1,
+    "email": "a@x.com",
+}
+
+# public profile: profile-based exclusions are applied.
+assert account.model_dump(profile="public") == {
+    "id": 1,
+}
+
+# include_excluded=True: ignore Field exclusion metadata.
+assert account.model_dump(profile="public", include_excluded=True) == {
+    "id": 1,
+    "email": "a@x.com",
+    "internal_note": "secret",
+}
+
+# Dynamic omission for one call (without metadata changes).
+assert account.model_dump(exclude={"email"}) == {
+    "id": 1,
+}
+```
+
+
+## Type-Based Custom Serializers
+
+You can override serialization behavior by type with `type_serializers`.
+
+Shape:
+
+```python
+type_serializers = {
+    SomeType: serializer_function,
+}
+```
+
+### Keep Decimal values as Decimal in `model_dump`
+
+```python
+from decimal import Decimal
+
+dumped = model.model_dump(
+    type_serializers={
+        Decimal: lambda value: value,
+    }
+)
+```
+
+### Convert float to Decimal for a specific output contract
+
+```python
+from decimal import Decimal
+
+from modmex import BaseModel
+
+
+class Price(BaseModel):
+    amount: float
+
+
+p = Price(amount=10.25)
+dumped = p.model_dump(
+    type_serializers={
+        float: lambda value: Decimal(str(value)),
+    }
+)
+
+assert dumped["amount"] == Decimal("10.25")
+```
+
+### Emit Decimal as string in JSON
+
+```python
+from decimal import Decimal
+
+dumped_json = model.model_dump_json(
+    type_serializers={
+        Decimal: lambda value: str(value),
+    }
+)
+```
+
+Note: some client libraries expect `Decimal` instead of `float` values (for example, common `boto3` workflows). Type serializers let you adapt output contracts cleanly, without hard-coding backend-specific behavior into your models.
+
+
+
+
+
+## Error Handling
+
+Validation issues raise `ValidationError`.
+
+Each error includes:
+
+- `loc`: location path (supports nested structures).
+- `msg`: human-readable message.
+- `type`: error category.
+
+Example locations:
+
+- `["address", "zipcode"]`
+- `["tags", 1]`
+
+
+## Practical Usage Pattern
+
+Use this rule of thumb:
+
+- Keep rich Python types in the in-memory model instance.
+- Use `model_dump` / `model_dump_json` to produce transport-friendly payloads.
+- Use `type_serializers` when a specific consumer requires a different type format.
+
+
+## Compatibility
+
+- Python 3.10+
+

modmex-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+modmex/__init__.py,sha256=iOrjDJLI4VToonWBCb99KAwO-ATRg2Q2mr6Xbm85n5Y,261
+modmex/base_model.py,sha256=Ry_px8JJZFoqB3XBYyqR0SrI9vrGscvMRSeZ9t-YpS0,5787
+modmex/datetime_parser.py,sha256=flZYy3YwKiKQuPJ-hyTKewDKjdxy_906Krsu0sBM5y0,7568
+modmex/errors.py,sha256=0P_oG4BAc4ITD11a0iFjvtNbYW5hxm51Y_bgJaTelLs,485
+modmex/fields.py,sha256=5UFVDYagLGpY8vjMDWT5E1G3BidAjhyxAJh_vbYzwOk,1916
+modmex/serialization.py,sha256=NfRp179z3pVnnbd9fmaeLGtKWSEPIyD3hhOJVLjMFCI,3894
+modmex/validation.py,sha256=FjX1M3QHCmEAmqoFFxDSDwKJ6R6qfrCNLF0Az_S7P4A,11368
+modmex-1.0.0.dist-info/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
+modmex-1.0.0.dist-info/METADATA,sha256=qHwH9Ri_c2YqkW19Os6Wk8TO7Io8aqS82MGORKyXj5g,9280
+modmex-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+modmex-1.0.0.dist-info/RECORD,,

modmex-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any