bagof-validators 0.1__tar.gz

bagof_validators-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bagofseeds
+
+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.

bagof_validators-0.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: bagof-validators
+Version: 0.1
+Summary: Hint-based runtime validators.
+Author-email: Yael Balbastre <yael.balbastre@gmail.com>
+Maintainer-email: Yael Balbastre <yael.balbastre@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bagofseeds/bagof-validators
+Project-URL: Documentation, https://github.com/bagofseeds/bagof-validators#readme
+Project-URL: Issues, https://github.com/bagofseeds/bagof-validators/issues
+Project-URL: Repository, https://github.com/bagofseeds/bagof-validators
+Keywords: bagof,validators,python
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.13
+Requires-Dist: bagof-hints~=0.1
+Requires-Dist: bagof-core-magic~=0.1
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Dynamic: license-file
+
+# bagof-validators
+
+Hint-based validators that operate at runtime.
+
+## Example
+
+```pycon
+>>> from collections import abc
+>>> from bagof.validators import get_validator
+>>> validate = get_validator(abc.Sequence[int])
+>>> validate([1, 2, 3])
+>>> validate(1)
+TypeValidationError: IsSequence(collections.abc.Sequence[int]): Not a valid instance.
+|> value = 1
+>>> validate(["a", "b", "c"])
+ValueValidationError: IsSequence(collections.abc.Sequence[int]): Iterable's 0th element is not valid.
+|> value = ['a', 'b', 'c']
+```

bagof_validators-0.1/README.md

@@ -0,0 +1,18 @@
+# bagof-validators
+
+Hint-based validators that operate at runtime.
+
+## Example
+
+```pycon
+>>> from collections import abc
+>>> from bagof.validators import get_validator
+>>> validate = get_validator(abc.Sequence[int])
+>>> validate([1, 2, 3])
+>>> validate(1)
+TypeValidationError: IsSequence(collections.abc.Sequence[int]): Not a valid instance.
+|> value = 1
+>>> validate(["a", "b", "c"])
+ValueValidationError: IsSequence(collections.abc.Sequence[int]): Iterable's 0th element is not valid.
+|> value = ['a', 'b', 'c']
+```

bagof_validators-0.1/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "bagof-validators"
+authors = [
+    {name = "Yael Balbastre", email = "yael.balbastre@gmail.com"},
+]
+maintainers = [
+    {name = "Yael Balbastre", email = "yael.balbastre@gmail.com"},
+]
+description = "Hint-based runtime validators."
+readme = "README.md"
+license = {text = "MIT"}
+keywords = ["bagof", "validators", "python"]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+dynamic = ["version"]
+requires-python = ">=3.8"
+dependencies = [
+    "typing_extensions >= 4.13",
+    "bagof-hints ~= 0.1",
+    "bagof-core-magic ~= 0.1"
+]
+
+[project.urls]
+Homepage = "https://github.com/bagofseeds/bagof-validators"
+Documentation = "https://github.com/bagofseeds/bagof-validators#readme"
+Issues = "https://github.com/bagofseeds/bagof-validators/issues"
+Repository = "https://github.com/bagofseeds/bagof-validators"
+
+[project.optional-dependencies]
+test = [
+    "pytest >= 7",
+    "pytest-cov >= 4",
+    # Optional runtime dependency: the numpy validators are only tested
+    # when it is installed (see tests/test_numpy.py).
+    "numpy",
+]
+
+[build-system]
+requires = [
+    "setuptools >= 59.0",
+    "wheel >= 0.45.1",
+    "versioningit >= 1.0",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["bagof*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"bagof.validators" = ["py.typed"]
+
+[tool.versioningit]
+default-version = "0+unknown"
+
+[tool.versioningit.vcs]
+default-tag = "0.1"
+
+[tool.versioningit.format]
+distance = "{base_version}+{distance}.{vcs}{rev}"
+dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
+distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
+
+[tool.versioningit.write]
+file = "src/bagof/validators/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["bagof.validators"]
+
+[tool.coverage.report]
+exclude_also = [
+    # Type-checking blocks are never executed at runtime.
+    "if tx.TYPE_CHECKING:",
+    "if tx.TYPE_CHECKING or",
+]
+
+[tool.ruff]
+line-length = 79
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["ANN", "B", "E", "F", "I", "UP", "W"]
+ignore = [
+    "ANN002",   # Do not type *args
+    "ANN003",   # Do not type *kwargs
+    "ANN401",   # Allow typing with Any
+    "UP006",    # Old-style collections hints (List instead of list)
+    "UP035",    # Use `typing_extensions` instead of `typing`
+]
+
+[tool.codespell]
+check-filenames = true
+skip = ".git,*.egg-info,build,dist,*.pdf,*.svg"

bagof_validators-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bagof_validators-0.1/src/bagof/validators/__init__.py

@@ -0,0 +1,75 @@
+"""
+Automatic type-based validators.
+
+Modules
+-------
+base
+    Base class for magic validators.
+collections
+    Validators for collection types (list, tuple, dict, etc.).
+common
+    Common validators (any, union, etc.).
+exceptions
+    Exceptions raised by validators on validation error.
+misc
+    Miscellaneous validators (forbidden values, etc.).
+numbers
+    Validators for numeric types (int, float, etc.).
+numpy
+    Validators for numpy types (dtype, etc.).
+strings
+    Validators for string types (regex patterns, etc.).
+"""
+
+__all__ = [
+    "__version__",
+    "base",
+    "collections",
+    "common",
+    "exceptions",
+    "misc",
+    "numbers",
+    "numpy",
+    "strings",
+]
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0+unknown"
+
+from . import (
+    base,
+    collections,
+    common,
+    exceptions,
+    misc,
+    numbers,
+    numpy,
+    strings,
+)
+from .base import *  # noqa: F401, F403
+from .base import __all__ as __all_base
+from .collections import *  # noqa: F401, F403
+from .collections import __all__ as __all_collections
+from .common import *  # noqa: F401, F403
+from .common import __all__ as __all_common
+from .exceptions import *  # noqa: F401, F403
+from .exceptions import __all__ as __all_exceptions
+from .misc import *  # noqa: F401, F403
+from .misc import __all__ as __all_misc
+from .numbers import *  # noqa: F401, F403
+from .numbers import __all__ as __all_numbers
+from .numpy import *  # noqa: F401, F403
+from .numpy import __all__ as __all_numpy
+from .strings import *  # noqa: F401, F403
+from .strings import __all__ as __all_strings
+
+__all__ += __all_base
+__all__ += __all_collections
+__all__ += __all_common
+__all__ += __all_exceptions
+__all__ += __all_misc
+__all__ += __all_numbers
+__all__ += __all_numpy
+__all__ += __all_strings

bagof_validators-0.1/src/bagof/validators/_compat.py

@@ -0,0 +1,35 @@
+import typing_extensions as tx
+
+# optional
+if tx.TYPE_CHECKING:
+    from types import NoneType, UnionType
+
+    UNION_TYPES = (tx.Union, UnionType)
+
+else:
+    try:
+        from types import NoneType
+    except ImportError:  # pragma: no cover
+        NoneType = type(None)  # type: ignore[assignment]
+
+    try:
+        from types import UnionType
+        UNION_TYPES = (tx.Union, UnionType)
+    except ImportError:  # pragma: no cover
+        UnionType = tx.Union  # type: ignore[assignment]
+        UNION_TYPES = (tx.Union,)
+
+if tx.TYPE_CHECKING:
+    import numpy as np
+    import numpy.typing as npt
+
+else:
+    try:
+        import numpy as np
+    except ImportError:  # pragma: no cover
+        np = None  # type: ignore[assignment]
+
+    try:
+        import numpy.typing as npt
+    except ImportError:  # pragma: no cover
+        npt = None  # type: ignore[assignment]

bagof_validators-0.1/src/bagof/validators/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1"

bagof_validators-0.1/src/bagof/validators/base.py

@@ -0,0 +1,335 @@
+"""Base class for all validators."""
+
+__all__ = [
+    "Validator",
+    "register_validator",
+    "get_validator",
+    "get_validator_class"
+]
+
+# dependencies
+import typing_extensions as tx  # noqa: I001
+
+# bags
+from bagof.core.magic import (
+    UNSET,
+    MagicHint,
+    get_from_registry,
+    ishintstance,
+    safe_isinstance,
+    safe_issubclass,
+)
+from bagof.hints.typevars.co import TYPE, T
+
+# locals
+from .exceptions import (
+    TypeValidationError,
+    ValidationError,
+    ValueValidationError,
+)
+
+# typing
+
+ClassDecorator: tx.TypeAlias = tx.Callable[[TYPE], TYPE]
+"""A class decorator (that takes a class and returns a class)."""
+
+ValidatorRegistry = tx.Dict[tx.Hashable, tx.Type["Validator"]]
+"""A registry of validators, mapping type hints to validator classes."""
+
+# constants
+VALIDATORS: ValidatorRegistry = {}
+"""The global registry of validators."""
+
+
+class ValidatorMetaclass(type(MagicHint)):
+    """Metaclass for all validators."""
+
+    def __new__(
+        metacls,
+        name: str,
+        bases: tx.Tuple[type, ...],
+        namespace: tx.Mapping[str, tx.Any],
+        **kwargs
+    ) -> tx.Self:
+        register = kwargs.pop("register", UNSET)
+        cls = super().__new__(metacls, name, bases, namespace, **kwargs)
+        if register is not UNSET:
+            if register is True:
+                register = (cls.DEFAULT,)
+            if not isinstance(register, tuple):
+                register = (register,)
+            Validator.register(cls, *register)
+        return cls
+
+
+class Validator(MagicHint[T], metaclass=ValidatorMetaclass):
+    """
+    Base class for magic validators.
+
+    The default validator falls back to a rather crude heuristic to check
+    whether the type of the validated object is compatible with the type
+    hint.
+
+    !!! warning
+        This heuristic does not work well for generic types, so it is
+        recommended to implement a custom validator for generic types.
+    """
+
+    DEFAULT = tx.Any
+
+    def __init__(self, hint: tx.Any = UNSET, compose: bool = False) -> None:
+        """
+        Parameters
+        ----------
+        hint : Any, optional
+            The type hint to use for this magic object.
+            If not provided, the default hint for the class is used.
+        compose : bool
+            Whether to compose this validator with others, when they are
+            found in [`Annotated`][typing.Annotated] metadata.
+        """
+        super().__init__(hint)
+        self.compose = compose
+
+    def __call__(self, value: T) -> None:
+        """
+        Validate the given value.
+
+        Parameters
+        ----------
+        value : T
+            The value to validate.
+
+        Raises
+        ------
+        ValidationError
+            If the value is not valid for this validator.
+        """
+        if not ishintstance(value, self.hint):
+            raise self.type_error(value, "Not a valid instance.")
+
+    def error(
+        self, value: tx.Any, message: tx.Optional[str] = None, **kwargs
+    ) -> ValidationError:
+        """Return a [`ValidationError`][] with the given value and message."""
+        type = kwargs.pop("type", ValidationError)
+        type = {
+            "value": ValueValidationError,
+            "type": TypeValidationError
+        }.get(type, type)
+        kwargs.setdefault("this", self)
+        kwargs.setdefault("value", value)
+        if message is None:
+            message = "Invalid value."
+        return type(message, **kwargs)
+
+    def type_error(
+        self, value: tx.Any, message: tx.Optional[str] = None
+    ) -> TypeValidationError:
+        """Return a [`TypeValidationError`][] with the given value."""
+        if message is None:
+            message = f"Invalid value type: {type(value)}"
+        return self.error(value, message, type=TypeValidationError)
+
+    def value_error(
+        self, value: tx.Any, message: tx.Optional[str] = None
+    ) -> ValueValidationError:
+        """Return a [`ValueValidationError`][] with the given value."""
+        if message is None:
+            message = "Invalid value."
+        return self.error(value, message, type=ValueValidationError)
+
+    def _wrap_validator(self, validator: tx.Callable) -> tx.Callable:
+        """
+        Wrap a validator so that a plain [`TypeError`][] or
+        [`ValueError`][] raised inside it surfaces as a
+        [`ValidationError`][], with the original attached as its cause.
+
+        A [`ValidationError`][] raised by the wrapped validator passes
+        through unchanged.
+        """
+        return _trywrap_validator(validator, self.value_error)
+
+    @tx.overload
+    @staticmethod
+    def register(
+        validator: tx.Type["Validator"],
+        *hints: tx.Unpack[tx.Tuple[tx.Any, ...]],
+        registry: ValidatorRegistry = ...
+    ) -> tx.Type["Validator"]:
+        ...
+
+    @tx.overload
+    @staticmethod
+    def register(
+        *hints: tx.Unpack[tx.Tuple[tx.Any, ...]],
+        registry: ValidatorRegistry = ...
+    ) -> ClassDecorator:
+        ...
+
+    @staticmethod
+    def register(*hints, registry=VALIDATORS):
+        """
+        Decorator to register a validator class for one or more type hints.
+
+        Can be used as a bare decorator (its first argument is then the
+        validator class itself, as in the example below), or called with
+        one or more type hints to obtain a decorator factory instead.
+
+        !!! example
+            ```python
+            @Validator.register
+            class IntValidator(Validator[int]):
+
+                DEFAULT = int
+
+                def __call__(self, value: int) -> None:
+                    try:
+                        int(value)
+                    except (TypeError, ValueError) as e:
+                        raise self.type_error(value) from e
+            ```
+
+        Parameters
+        ----------
+        *hints
+            One or more type hints to register the validator class for.
+            Defaults to the validator class's `DEFAULT` hint if none are
+            given. When used as a bare decorator, the first "hint" is
+            actually the validator class to register.
+        registry : ValidatorRegistry
+            The registry to register the validator class in.
+            Defaults to the global registry.
+
+        Returns
+        -------
+        tx.Type["Validator"] | ClassDecorator
+            When used as a bare decorator, the same validator class, now
+            registered. Otherwise, a decorator that registers the
+            validator class it is applied to.
+
+        """
+        if hints and safe_issubclass(hints[0], Validator):
+            validator, *hints = hints
+            return Validator.register(*hints, registry=registry)(validator)
+
+        def decorator(cls: tx.Type[Validator]) -> tx.Type[Validator]:
+            hints_ = hints or (cls.DEFAULT,)
+            for hint in hints_:
+                registry[hint] = cls
+            return cls
+
+        return decorator
+
+    @staticmethod
+    def get(
+        hint: tx.Any,
+        registry: ValidatorRegistry = VALIDATORS,
+        fallback: tx.Optional[tx.Type["Validator"]] = UNSET
+    ) -> tx.Optional["Validator"]:
+        """
+        Get the best-matching conversion function for a given type hint.
+
+        The returned validator is a callable that returns `None` on success
+        and raises a [`ValidationError`][] on failure:
+
+        !!! example
+            ```pycon
+            >>> from bagof.validators import get_validator
+            >>> validate = get_validator(int)
+            >>> validate(3)
+            >>> validate("x")
+            TypeValidationError: IsNumber(<class 'int'>): Not a valid instance.
+            |> value = 'x'
+            ```
+
+        Parameters
+        ----------
+        hint
+            The type hint for which to get a validator.
+        registry : ValidatorRegistry
+            The registry to look up the validator in.
+            Defaults to the global registry.
+        fallback : tx.Optional[Type[Validator]]
+            The fallback validator class to use if no matching validator
+            is found. Defaults to [`Validator`][].
+            Pass `None` explicitly to get `None` instead of a fallback.
+
+        Returns
+        -------
+        tx.Optional[Validator]
+            The best-matching validator for the given type hint, or `None`
+            if no matching validator is found and no fallback is provided.
+        """
+        cls = Validator.get_class(hint, registry, fallback)
+        if cls is None:
+            return None
+        return cls(hint)
+
+    @staticmethod
+    def get_class(
+        hint: tx.Any,
+        registry: ValidatorRegistry = VALIDATORS,
+        fallback: tx.Optional[tx.Type["Validator"]] = UNSET
+    ) -> tx.Optional[tx.Type["Validator"]]:
+        """
+        Get the best-matching conversion class for a given type hint.
+
+        Parameters
+        ----------
+        hint
+            The type hint for which to get a validator.
+        registry : ValidatorRegistry
+            The registry to look up the validator in.
+            Defaults to the global registry.
+        fallback : tx.Optional[Type[Validator]]
+            The fallback validator class to use if no matching validator
+            is found. Defaults to [`Validator`][].
+            Pass `None` explicitly to get `None` instead of a fallback.
+
+        Returns
+        -------
+        tx.Optional[Type[Validator]]
+            The best-matching validator class for the given type hint,
+            or `None` if no matching validator is found and no fallback
+            is provided.
+        """
+        if fallback is UNSET:
+            fallback = Validator
+        return get_from_registry(hint, registry) or fallback
+
+
+register_validator = Validator.register
+"""Backward-compatible alias for [`Validator.register`][]"""
+
+get_validator = Validator.get
+"""Backward-compatible alias for [`Validator.get`][]"""
+
+get_validator_class = Validator.get_class
+"""Backward-compatible alias for [`Validator.get_class`][]"""
+
+
+def _trywrap_validator(
+    validator: tx.Callable[[T], None],
+    error: tx.Union[Exception, tx.Type[Exception], tx.Callable[[T], Exception]]
+) -> tx.Callable[[T], None]:
+    """
+    Wrap a validator to catch errors and raise a [`ValidationError`][] instead.
+    """
+    def wrapped(value: T) -> None:
+        try:
+            return validator(value)
+        except ValidationError:
+            # Already the right kind of error: re-raise it untouched, so
+            # its specific type and its `causes` survive. `TypeError` and
+            # `ValueError` are the base classes of `TypeValidationError`
+            # and `ValueValidationError`, so without this the `except`
+            # below would swallow and downgrade every real failure.
+            raise
+        except (TypeError, ValueError) as e:
+            _error = error
+            if not safe_isinstance(_error, BaseException):
+                # Either an exception class or a factory (e.g. `value_error`).
+                _error = _error(value)
+            raise _error from e
+    return wrapped