pedantic

78class ConversionError(ValidateException):
79    """Is raised if a type cast failed."""

 8class DateTimeUnixTimestamp(Validator): # noqa: D101
 9    @overrides(Validator)
10    def validate(self, value: float | str) -> datetime: # noqa: D102
11        if not isinstance(value, (int, float, str)):
12            self.raise_exception(msg=f'Invalid seconds since 1970: {value}', value=value)
13
14        try:
15            seconds = float(value)
16        except ValueError:
17            return self.raise_exception(msg=f'Could parse {value} to float.', value=value)
18
19        try:
20            return datetime(year=1970, month=1, day=1, tzinfo=UTC) + timedelta(seconds=seconds)
21        except OverflowError:
22            return self.raise_exception(
23                msg=f'Date value out of range. Make sure you send SECONDS since 1970. Got: {value}', value=value)

 8class DatetimeIsoFormat(Validator): # noqa: D101
 9    @overrides(Validator)
10    def validate(self, value: str) -> datetime: # noqa: D102
11        try:
12            value = datetime.fromisoformat(value)
13        except (TypeError, ValueError, AttributeError):
14            self.raise_exception(msg=f'invalid value: {value} is not a datetime in ISO format', value=value)
15
16        return value

10class DecoratorType(StrEnum):
11    """
12    The interface that defines all possible decorators types.
13
14    The values of this enum are used as property names and the properties are added to the decorated functions.
15    So I would recommend naming them with a leading underscore to keep them private and also write it lowercase.
16
17    Example:
18        >>> class Decorators(DecoratorType):
19        ...     FOO = '_foo'
20    """

 6class Deserializable(ABC):
 7    """A tiny interface which has a static from_json() method which acts like a named constructor."""
 8
 9    @staticmethod
10    @abstractmethod
11    def from_json(data: dict[str, Any]) -> 'Deserializable':
12        """A named constructor which creates an object from JSON."""

11class Email(Validator): # noqa: D101
12    def __init__(self, email_pattern: str = REGEX_EMAIL, post_processor: Callable[[str], str] = lambda x: x) -> None: # noqa: D107
13        self._pattern = email_pattern
14        self._post_processor = post_processor
15
16    @overrides(Validator)
17    def validate(self, value: str) -> str: # noqa: D102
18        if not re.fullmatch(pattern=self._pattern, string=value):
19            self.raise_exception(msg=f'invalid email address: {value}', value=value)
20
21        return self._post_processor(value)

12class EnvironmentVariableParameter(ExternalParameter):   # noqa: D101
13    def __init__(  # noqa: D107, PLR0913
14        self,
15        name: str,
16        env_var_name: str | None = None,
17        value_type: type[str | bool | int | float] = str,
18        validators: Iterable[Validator] | None = None,
19        required: bool = True,
20default: Any = NoValue,
21     ) -> None:
22        super().__init__(name=name, validators=validators, default=default, value_type=value_type, required=required)
23
24        if value_type not in [str, bool, int, float]:
25            raise AssertionError('value_type needs to be one of these: str, bool, int & float')
26
27        if env_var_name is None:
28            self._env_var_name = name
29        else:
30            self._env_var_name = env_var_name
31
32    @overrides(ExternalParameter)
33    def has_value(self) -> bool:   # noqa: D102
34        return self._env_var_name in os.environ
35
36    @overrides(ExternalParameter)
37    def load_value(self) -> Any:   # noqa: D102
38        return os.environ[self._env_var_name].strip()

5class ExceptionDictKey: # noqa: D101
6    VALUE = 'VALUE'
7    MESSAGE = 'MESSAGE'
8    PARAMETER = 'PARAMETER'
9    VALIDATOR = 'VALIDATOR'

 8class ExternalParameter(Parameter, ABC):
 9    """The interface for all external parameters."""
10
11    @abstractmethod
12    def has_value(self) -> bool:
13        """Returns True if the value can be fetched."""
14
15    @abstractmethod
16    def load_value(self) -> Any:
17        """Loads a value and returns it."""

10class ForEach(Validator):  # noqa: D101
11    def __init__(self, validators: Validator | Iterable[Validator]) -> None:  # noqa: D107
12        if isinstance(validators, Validator):
13            self._validators = [validators]
14        else:
15            self._validators = validators
16
17    @overrides(Validator)
18    def validate(self, value: Iterable[Any]) -> list[Any]:  # noqa: D102
19        if not isinstance(value, collections.abc.Iterable):
20            self.raise_exception(msg=f'{value} is not iterable.', value=value)
21
22        results = []
23
24        for item in value:
25            for validator in self._validators:
26                item = validator.validate(item)  # noqa: PLW2901
27
28            results.append(item)
29
30        return results

  5class GenericMixin:
  6    """
  7    A mixin that provides easy access to given type variables.
  8
  9    Example:
 10        >>> from typing import Generic, TypeVar
 11        >>> T = TypeVar('T')
 12        >>> U = TypeVar('U')
 13        >>> class Foo(Generic[T, U], GenericMixin):
 14        ...     values: list[T]
 15        ...     value: U
 16        >>> f = Foo[str, int]()
 17        >>> f.type_vars
 18        {~T: <class 'str'>, ~U: <class 'int'>}
 19    """
 20
 21    @property
 22    def type_vars(self) -> dict[TypeVar, type]:
 23        """
 24        Returns the mapping of type variables to types.
 25
 26        DO NOT call this inside __init__()!
 27
 28        Example:
 29            >>> from typing import Generic, TypeVar
 30            >>> T = TypeVar('T')
 31            >>> U = TypeVar('U')
 32            >>> class Foo(Generic[T, U], GenericMixin):
 33            ...     values: list[T]
 34            ...     value: U
 35            >>> f = Foo[str, int]()
 36            >>> f.type_vars
 37            {~T: <class 'str'>, ~U: <class 'int'>}
 38        """
 39
 40        return self._get_resolved_typevars()
 41
 42    def _get_resolved_typevars(self) -> dict[TypeVar, type]:  # noqa: C901
 43        """
 44        Returns the resolved type vars.
 45
 46        Do not call this inside the __init__() method, because at that point the relevant information are not present.
 47        See also https://github.com/python/cpython/issues/90899'
 48        """
 49
 50        mapping: dict[TypeVar, type] = {}
 51        class_name = type(self).__name__
 52
 53        if not hasattr(self, '__orig_bases__'):
 54            raise AssertionError(
 55                f'{class_name} is not a generic class. To make it generic, declare it like: '
 56                f'class {class_name}(Generic[T], GenericMixin):...',
 57            )
 58
 59        def collect(base: type, substitutions: dict[TypeVar, type]) -> None:
 60            """Recursively collect type var mappings from a generic base."""
 61            origin = get_origin(base) or base
 62            args = get_args(base)
 63
 64            params = getattr(origin, '__parameters__', ())
 65            # copy substitutions so each recursion has its own view
 66            resolved = substitutions.copy()
 67
 68            for param, arg in zip(params, args, strict=False):
 69                if isinstance(arg, TypeVar):
 70                    processed_arg = substitutions.get(arg, arg)
 71                else:
 72                    processed_arg = arg
 73
 74                mapping[param] = processed_arg
 75                resolved[param] = processed_arg
 76
 77            # Recurse into base classes, applying current substitutions
 78            for super_base in getattr(origin, '__orig_bases__', []):
 79                super_origin = get_origin(super_base) or super_base
 80                super_args = get_args(super_base)
 81
 82                if super_args:
 83                    # Substitute any TypeVars in the super_base's args using resolved
 84                    substituted_args = tuple(
 85                        resolved.get(a, a) if isinstance(a, TypeVar) else a
 86                        for a in super_args
 87                    )
 88                    # Build a new parametrized base so get_args() inside collect sees substituted_args
 89                    try:
 90                        substituted_base = super_origin[substituted_args]  # type: ignore[index]
 91                    except TypeError:
 92                        # Some origins won't accept subscription; fall back to passing the origin and trusting resolved
 93                        substituted_base = super_base
 94                    collect(base=substituted_base, substitutions=resolved)
 95                else:
 96                    collect(base=super_base, substitutions=resolved)
 97
 98        # Start from __orig_class__ if present, else walk the declared MRO bases
 99        cls = getattr(self, '__orig_class__', None)
100        if cls is not None:
101            collect(base=cls, substitutions={})
102        else:
103            # Walk the full MRO to catch indirect generic ancestors
104            for c in self.__class__.__mro__:
105                for base in getattr(c, '__orig_bases__', []):
106                    collect(base=base, substitutions=mapping)
107
108        # Ensure no unresolved TypeVars remain
109        all_params = set()
110        for c in self.__class__.__mro__:
111            all_params.update(getattr(c, '__parameters__', ()))
112
113        unresolved = {p for p in all_params if p not in mapping or isinstance(mapping[p], TypeVar)}
114        if unresolved:
115            raise AssertionError(
116                f'You need to instantiate this class with type parameters! Example: {class_name}[int]()\n'
117                f'Also make sure that you do not call this in the __init__() method of your class!\n'
118                f'Unresolved type variables: {unresolved}\n'
119                f'See also https://github.com/python/cpython/issues/90899',
120            )
121
122        return mapping

70class InvalidHeader(ParameterException):
71    """Is raised if there is a validation error in a FlaskHeaderParameter."""

 9class IsEnum(Validator): # noqa: D101
10    def __init__(self, enum: EnumMeta, convert: bool = True, to_upper_case: bool = True) -> None: # noqa: D107
11        self._enum = enum
12        self._convert = convert
13        self._to_upper_case = to_upper_case
14
15    @overrides(Validator)
16    def validate(self, value: Any) -> Any: # noqa: D102
17        try:
18            if isinstance(value, str) and self._to_upper_case:
19                value = value.upper()
20
21            if issubclass(self._enum, IntEnum):
22                enum_value = self._enum(int(value))
23            else:
24                enum_value = self._enum(value)
25        except (ValueError, TypeError):
26            return self.raise_exception(msg=f'Incorrect value {value} for enum {self._enum}.', value=value)
27
28        if self._convert:
29            return enum_value
30
31        return value

 8class IsUuid(Validator): # noqa: D101
 9    def __init__(self, convert: bool = False) -> None: # noqa: D107
10        self._convert = convert
11
12    @overrides(Validator)
13    def validate(self, value: str) -> str: # noqa: D102
14        try:
15            converted_value = UUID(str(value))
16        except ValueError:
17            return self.raise_exception(msg=f'{value} is not a valid UUID', value=value)
18
19        return converted_value if self._convert else value

 8class MatchPattern(Validator):  # noqa: D101
 9    def __init__(self, pattern: str) -> None:  # noqa: D107
10        self._pattern = re.compile(pattern=pattern)
11
12    @overrides(Validator)
13    def validate(self, value: str) -> str: # noqa: D102
14        if not self._pattern.search(string=str(value)):
15            self.raise_exception(msg=f'Value "{value}" does not match pattern {self._pattern.pattern}.', value=value)
16
17        return value

 6class Max(Validator):  # noqa: D101
 7    def __init__(self, value: float, include_boundary: bool = True) -> None:
 8        """
 9        >>> Max(7, True).validate(7)
10        7
11        >>> Max(7, False).validate(7)  # doctest: +IGNORE_EXCEPTION_DETAIL
12        Traceback (most recent call last):
13        ValidatorException: ...
14        >>> Max(7, False).validate(6.999)
15        6.999
16        """
17        self._value = value
18        self._include_boundary = include_boundary
19
20    @overrides(Validator)
21    def validate(self, value: float) -> int | float:  # noqa: D102
22        if value > self._value and self._include_boundary:
23            self.raise_exception(msg=f'greater then allowed: {value} is not <= {self._value}', value=value)
24        elif value >= self._value and not self._include_boundary:
25            self.raise_exception(msg=f'greater then allowed: {value} is not < {self._value}', value=value)
26
27        return value

10class MaxLength(Validator):  # noqa: D101
11    def __init__(self, length: int) -> None:  # noqa: D107
12        self._length = length
13
14    @overrides(Validator)
15    def validate(self, value: Sized) -> Any:  # noqa: D102
16        if not isinstance(value, collections.abc.Sized):
17            self.raise_exception(msg=f'{value} has no length.', value=value)
18
19        if len(value) > self._length:
20            self.raise_exception(msg=f'{value} is too long with length {len(value)}.', value=value)
21
22        return value

 7class Min(Validator):  # noqa: D101
 8    def __init__(self, value: float, include_boundary: bool = True) -> None:
 9        """
10        >>> Min(7, True).validate(7)
11        7
12        >>> Min(7, False).validate(7)  # doctest: +IGNORE_EXCEPTION_DETAIL
13        Traceback (most recent call last):
14        ValidatorException: ...
15        >>> Min(7, False).validate(7.001)
16        7.001
17        """
18        self._value = value
19        self._include_boundary = include_boundary
20
21    @overrides(Validator)
22    def validate(self, value: float) -> int | float:  # noqa: D102
23        if value < self._value and self._include_boundary:
24            self.raise_exception(msg=f'smaller then allowed: {value} is not >= {self._value}', value=value)
25        elif value <= self._value and not self._include_boundary:
26            self.raise_exception(msg=f'smaller then allowed: {value} is not > {self._value}', value=value)
27
28        return value

10class MinLength(Validator):  # noqa: D101
11    def __init__(self, length: int) -> None:  # noqa: D107
12        self._length = length
13
14    @overrides(Validator)
15    def validate(self, value: Sized) -> Any:  # noqa: D102
16        if not isinstance(value, collections.abc.Sized):
17            self.raise_exception(msg=f'{value} has no length.', value=value)
18
19        if len(value) < self._length:
20            self.raise_exception(msg=f'{value} is too short with length {len(value)}.', value=value)
21
22        return value

 9class NotEmpty(Validator):
10    """Validates that the given value is not empty."""
11
12    def __init__(self, strip: bool = True) -> None:
13        """If strip is True, the leading and trailing whitespace will be removed."""
14        self.strip = strip
15
16    @overrides(Validator)
17    def validate(self, value: Sequence) -> Sequence:
18        """
19        Throws a ValidationError if the sequence is empty.
20        If the sequence is a string, it removes all leading and trailing whitespace.
21        """
22
23        if isinstance(value, str):
24            if not value.strip():
25                self.raise_exception(msg='Got empty String which is invalid.', value=value)
26
27            return value.strip() if self.strip else value
28        if isinstance(value, collections.abc.Sequence):
29            if len(value) == 0:
30                raise self.raise_exception(msg='Got empty  which is invalid.', value=value)
31
32            return value
33
34        return self.raise_exception(msg=f'Got {type(value)} which is not a Sequence.', value=value)

14class Parameter:  # noqa: D101
15    exception_type: type[ParameterException] = ParameterException
16
17    def __init__(  # noqa: D107
18        self,
19        name: str,
20        value_type: type[bool | int | float | str | dict | list] | None = None,
21        validators: Iterable[Validator] | None = None,
22        default: Any = NoValue,
23        required: bool = True,
24     ) -> None:
25        self.name = name
26        self.validators = validators or []
27        self.default_value = default
28        self.value_type = value_type
29        self.is_required = False if default != NoValue else required
30
31        if value_type not in [str, bool, int, float, dict, list, None]:
32            raise AssertionError('value_type needs to be one of these: str, bool, int, float, dict & list')
33
34    def validate(self, value: Any) -> Any:
35        """Apply all validators to the given value and collect all ValidationErrors."""
36
37        if value is None:
38            if self.is_required:
39                self.raise_exception(msg=f'Value for key {self.name} is required.')
40
41            return None
42
43        if self.value_type is not None:
44            try:
45                result_value = convert_value(value=value, target_type=self.value_type)
46            except ConversionError as ex:
47                return self.raise_exception(value=value, msg=ex.message)
48        else:
49            result_value = value
50
51        for validator in self.validators:
52            try:
53                result_value = validator.validate(result_value)
54            except ValidatorException as e:
55                raise self.exception_type.from_validator_exception(exception=e, parameter_name=self.name) from e
56
57        return result_value
58
59    def raise_exception(self, msg: str, value: Any = None, validator: Validator | None = None) -> NoReturn:  # noqa: D102
60        raise self.exception_type(
61            value=value,
62            parameter_name=self.name,
63            msg=msg,
64            validator_name=validator.name if validator else None,
65        )
66
67    def __str__(self) -> str:
68        return self.__class__.__name__ + ' name=' + self.name