jsonschema-extras 0.2.0__py3-none-any.whl

jsonschema_extras/VERSION

@@ -0,0 +1 @@
+0.2.0

jsonschema_extras/__init__.py

@@ -0,0 +1,96 @@
+"""Utilities for working with the JSON Schema Python library
+`jsonschema <https://pypi.org/project/jsonschema/>`__.
+
+Features:
+
+- :doc:`Schemas bundled with the library </schemas>`
+
+- :doc:`Formats bundled with the library </formats>`
+
+- :doc:`Utilities for accessing schemas on a filesystem </filesystem>`
+
+- :doc:`Other generally useful utilities </misc>`
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+import importlib.resources
+from importlib.resources.abc import Traversable
+from typing import Any, Final
+
+from referencing.typing import Retrieve
+
+from .registries import build_schemas_from_filesystem_retriever
+from .registries.retrieval import CacheFn, CacheSpecDefault
+from .registries.retrieval.json import LOADS_FN_JSON_DEFAULT
+
+
+__all__ = (
+    'bundled_schemas_files',
+    'BUNDLED_SCHEMAS_URI_BASE',
+    'bundled_schemas_retriever',
+)
+
+
+def bundled_schemas_files() -> Traversable:
+    """Returns a :class:`~importlib.resources.abc.Traversable` object
+    containing resources for bundled schemas.
+
+    Built upon :func:`importlib.resources.files`.
+    """
+    return (importlib.resources.files('jsonschema_extras') / 'schemas')
+
+
+#: Base URI for schemas bundled with this library.
+#:
+#: See Also:
+#:     :func:`bundled_schemas_retriever`
+BUNDLED_SCHEMAS_URI_BASE: Final[str] = 'file:/jsonschema_extras/schemas'
+
+_BUNDLED_SCHEMAS_ENCODING: Final = 'utf-8'
+
+
+@contextmanager
+def bundled_schemas_retriever(
+    *, open_buffering: int = -1, cache: CacheFn[Any] | CacheSpecDefault | None = None,
+) -> Iterator[Retrieve]:
+    """**Context manager** producing a retrieval callable for this library's
+    bundled schemas.
+
+    Warning:
+        The produced retriever is only valid within duration of an explicit
+        lifecycle, hence the context manager.
+
+    Args:
+        cache (CacheFn | CacheSpecDefault, optional):
+            Caching decorator for :class:`~referencing.typing.Retrieve`,
+            or ``'default'`` to use the default caching implementation
+            (see description of :mod:`jsonschema_extras.registries.retrieval`
+            for details). Defaults to ``None``, meaning no caching.
+        open_buffering (int, optional):
+            Optional integer used to set the buffering policy.
+            See the Python built-in function :func:`open`.
+
+    Yields:
+        A retrieval callable for this library's bundled schemas.
+        The retriever is only valid until the context is exited.
+
+    Raises:
+        ValueError: On invalid `uri_base`.
+
+    Note:
+        The implementation uses :mod:`importlib.resources` which conceptually
+        cannot provide a persistent path to a directory which could be accessed
+        by common code at any time. The lifecycle has to be explicit
+        due to using package resources.
+    """
+    with importlib.resources.as_file(bundled_schemas_files()) as bundled_schemas_path:
+        yield build_schemas_from_filesystem_retriever(
+            BUNDLED_SCHEMAS_URI_BASE,
+            bundled_schemas_path,
+            open_kwargs=dict(
+                buffering=open_buffering, encoding=_BUNDLED_SCHEMAS_ENCODING,
+            ),
+            cache=cache,
+            loads=LOADS_FN_JSON_DEFAULT,
+        )

jsonschema_extras/_common.py

@@ -0,0 +1,31 @@
+from collections.abc import Collection, Mapping
+from typing import Any, TypeAlias
+
+
+__all__ = ()
+
+
+type Kwargs = Mapping[str, Any]
+
+
+# NOTE: returns kwargs without changes
+def validate_kwargs(
+    kwargs: Kwargs, *, allowed: Collection[str] = (), required: Collection[str] = (),
+) -> Kwargs:
+    # NOTE: using lists instead of sets to preserve order
+    allowed = list(allowed)
+    allowed += [s for s in required if s not in allowed]
+    unexpected = [s for s in kwargs if s not in allowed]
+    if len(unexpected) > 0:
+        raise TypeError(
+            'got unexpected keyword argument(s): {0}'.format(', '.join(unexpected))
+        )
+    missing = [s for s in required if s not in kwargs]
+    if len(missing) > 0:
+        raise TypeError(
+            'missing required keyword argument(s): {0}'.format(', '.join(missing))
+        )
+    return kwargs
+
+
+EncodingId: TypeAlias = str

jsonschema_extras/_util/__init__.py

@@ -0,0 +1,21 @@
+from collections.abc import Collection, Hashable, Mapping
+from typing import TypeVar
+
+
+_K = TypeVar('_K', bound=Hashable)
+_V = TypeVar('_V')
+
+
+COLLECTION_PRIMITIVE_TYPES_DEFAULT: Collection[type] = (
+    str, bytes, bytearray, memoryview,
+)
+
+SEQUENCE_PRIMITIVE_TYPES_DEFAULT: Collection[type] = (
+    *COLLECTION_PRIMITIVE_TYPES_DEFAULT,
+)
+
+
+def coerce_to_dict(mapping: Mapping[_K, _V]) -> dict[_K, _V]:
+    if isinstance(mapping, dict):
+        return mapping
+    return dict(mapping.items())

jsonschema_extras/_util/tests/test_uri.py

@@ -0,0 +1,210 @@
+from pathlib import PurePosixPath
+from urllib.parse import urlsplit, urlunsplit
+
+import pytest
+
+from jsonschema_extras._util.uri import (
+    RPURIBValidateURIValueErrorCode,
+    RPURIBValidateURIValueError,
+    is_uri_absolute,
+    rpurib_validate_uri_base_split,
+    rpurib_validate_uri_split,
+    RPURIBNotRelativeValueError,
+    relative_path_from_uri_by_base_splits_validated,
+    translate_uri_base_splits_validated,
+)
+
+
+class TestIsUriAbsolute:
+
+    @pytest.mark.parametrize(
+        ('uri', 'is_absolute'),
+        [
+            ('https://example.com/path?q=1#frag', True),
+            ('//example.com/path', True),
+            ('mailto:someone@example.com', True),
+            ('http://', True),
+            ('//user:pass@example.com', True),
+            ('/absolute/path', False),
+            ('relative/path', False),
+            ('../parent', False),
+            ('#fragment', False),
+            ('?query=val', False),
+            ('', False),
+        ],
+    )
+    @staticmethod
+    def test_absolute_returns_true(uri, is_absolute):
+        assert is_uri_absolute(uri) == is_absolute
+
+    @pytest.mark.parametrize(
+        ('uri', 'is_absolute'), [('https://a.b', True), ('/x', False)],
+    )
+    @staticmethod
+    def test_accepts_pre_parsed_split_result(uri, is_absolute):
+        assert is_uri_absolute(urlsplit(uri)) == is_absolute
+
+
+class TestRPURIBValidateURIBaseSplit:
+
+    _VALID_BASE = urlsplit('https://example.com/base')
+
+    @classmethod
+    def test_returns_input_for_valid_absolute_base(cls):
+        result = rpurib_validate_uri_base_split(cls._VALID_BASE)
+        assert result == cls._VALID_BASE
+
+    @pytest.mark.parametrize(
+        ('uri_base_split', 'code_exp'),
+        [
+            (
+                _VALID_BASE._replace(scheme='', netloc=''),
+                RPURIBValidateURIValueErrorCode.IS_RELATIVE,
+            ),
+            (
+                _VALID_BASE._replace(query='a=1'),
+                RPURIBValidateURIValueErrorCode.HAS_QUERY,
+            ),
+            (
+                _VALID_BASE._replace(fragment='section-1'),
+                RPURIBValidateURIValueErrorCode.HAS_FRAGMENT,
+            ),
+        ],
+    )
+    @staticmethod
+    def test_rpurib_validate_uri_base_split_rejects_invalid_base_uris(
+        uri_base_split, code_exp,
+    ):
+        with pytest.raises(RPURIBValidateURIValueError) as exc_info:
+            rpurib_validate_uri_base_split(uri_base_split)
+        assert exc_info.value.code == code_exp
+
+
+class TestRPURIBValidateURISplit:
+
+    _VALID_URI = urlsplit('https://example.com/path')
+
+    @classmethod
+    def test_returns_input_for_valid_absolute_uri(cls):
+        result = rpurib_validate_uri_split(cls._VALID_URI)
+        assert result == cls._VALID_URI
+
+    @pytest.mark.parametrize(
+        ('uri_split', 'code_exp'),
+        [
+            (
+                _VALID_URI._replace(scheme='', netloc=''),
+                RPURIBValidateURIValueErrorCode.IS_RELATIVE,
+            ),
+            (
+                _VALID_URI._replace(query='a=1'),
+                RPURIBValidateURIValueErrorCode.HAS_QUERY,
+            ),
+            (
+                _VALID_URI._replace(fragment='section-1'),
+                RPURIBValidateURIValueErrorCode.HAS_FRAGMENT,
+            ),
+        ],
+    )
+    @staticmethod
+    def test_rpurib_validate_uri_split_rejects_invalid_uris(
+        uri_split, code_exp,
+    ):
+        with pytest.raises(RPURIBValidateURIValueError) as exc_info:
+            rpurib_validate_uri_split(uri_split)
+        assert exc_info.value.code == code_exp
+
+
+class TestRelativePathFromURIByBaseSplitsValidated:
+
+    @pytest.mark.parametrize(
+        ('uri', 'base', 'expected'),
+        [
+            ('https://ex.com/a/b/c', 'https://ex.com/a/b/', PurePosixPath('c')),
+            ('https://ex.com/a/b/c/d', 'https://ex.com/a/b/', PurePosixPath('c/d')),
+            ('https://ex.com/a/b', 'https://ex.com/a/b', PurePosixPath('.')),
+            ('https://ex.com/a/b/', 'https://ex.com/a/b', PurePosixPath('.')),
+            ('https://ex.com/', 'https://ex.com/', PurePosixPath('.')),
+            ('https://ex.com/x', 'https://ex.com/', PurePosixPath('x')),
+        ],
+    )
+    @staticmethod
+    def test_relative_path_success(uri, base, expected):
+        assert (
+            relative_path_from_uri_by_base_splits_validated(
+                urlsplit(uri), urlsplit(base),
+            )
+            == expected
+        )
+
+    @staticmethod
+    def test_raises_not_relative():
+        with pytest.raises(RPURIBNotRelativeValueError):
+            relative_path_from_uri_by_base_splits_validated(
+                urlsplit('https://ex.com/a/b/'), urlsplit('https://ex.com/a/c/d'),
+            )
+
+
+def test_uri_not_under_old_base_propagates_error():
+    with pytest.raises(RPURIBNotRelativeValueError):
+        translate_uri_base_splits_validated(
+            urlsplit('https://old.example.com/other/file'),
+            urlsplit('https://old.example.com/base/'),
+            urlsplit('https://new.example.com/base/'),
+        )
+
+
+@pytest.mark.parametrize(
+    ('uri', 'old_base', 'new_base', 'expected'),
+    [
+        (
+            'https://old.example.com/base/file.txt',
+            'https://old.example.com/base/',
+            'https://new.example.com/newbase/',
+            'https://new.example.com/newbase/file.txt',
+        ),
+        (
+            'https://old.example.com/base/sub/deep/file.txt',
+            'https://old.example.com/base/',
+            'https://new.example.com/newbase/',
+            'https://new.example.com/newbase/sub/deep/file.txt',
+        ),
+        (
+            'https://old.example.com/base/file',
+            'https://old.example.com/base/',
+            'http://new.example.com/base/',
+            'http://new.example.com/base/file',
+        ),
+        (
+            'https://old.example.com/base/file',
+            'https://old.example.com/base/',
+            'https://new-domain.com/base/',
+            'https://new-domain.com/base/file',
+        ),
+        (
+            'https://old.example.com/base/file',
+            'https://old.example.com/base/',
+            'https://user:pass@new.example.com/base/',
+            'https://user:pass@new.example.com/base/file',
+        ),
+        (
+            'https://old.example.com/base/file',
+            'https://old.example.com/base/',
+            'https://new.example.com:8080/base/',
+            'https://new.example.com:8080/base/file',
+        ),
+        (
+            'https://old.example.com/base/file',
+            'https://old.example.com/base/',
+            'https://new.example.com/a/b/c/base/',
+            'https://new.example.com/a/b/c/base/file',
+        ),
+    ],
+)
+def test_translation_uri_base_splits_validated(uri, old_base, new_base, expected):
+    assert (
+        urlunsplit(translate_uri_base_splits_validated(
+            urlsplit(uri), urlsplit(old_base), urlsplit(new_base),
+        ))
+        == expected
+    )

jsonschema_extras/_util/uri.py

@@ -0,0 +1,125 @@
+from enum import StrEnum
+from pathlib import PurePosixPath
+from urllib.parse import SplitResult, unquote, urlsplit
+
+
+def is_uri_absolute(uri: str | SplitResult) -> bool:
+    # here scheme is a default value:
+    if not isinstance(uri, SplitResult):
+        uri_split = urlsplit(uri, scheme='')
+    else:
+        uri_split = uri
+    return (
+        bool(uri_split.scheme)
+        or bool(uri_split.netloc)
+        or (uri_split.username is not None)
+        or (uri_split.password is not None)
+    )
+
+
+class RPURIBValidateURIValueErrorCode(StrEnum):
+    IS_RELATIVE = 'is_relative'
+    HAS_QUERY = 'has_query'
+    HAS_FRAGMENT = 'has_fragment'
+
+
+class RPURIBValidateURIValueError(ValueError):
+
+    def __init__(self, message: str, code: RPURIBValidateURIValueErrorCode):
+        super().__init__(message, code)
+        self.code = code
+
+
+def rpurib_validate_uri_base_split(uri_base_split: SplitResult) -> SplitResult:
+    if not is_uri_absolute(uri_base_split):
+        raise RPURIBValidateURIValueError(
+            'base URI should be absolute',
+            RPURIBValidateURIValueErrorCode.IS_RELATIVE,
+        )
+    if unquote(uri_base_split.query):
+        raise RPURIBValidateURIValueError(
+            'base URI should not have a query',
+            RPURIBValidateURIValueErrorCode.HAS_QUERY,
+        )
+    if uri_base_split.fragment:
+        raise RPURIBValidateURIValueError(
+            'base URI should not have a fragment',
+            RPURIBValidateURIValueErrorCode.HAS_FRAGMENT,
+        )
+    return uri_base_split
+
+
+def rpurib_split_and_validate_uri_base(uri_base: str) -> SplitResult:
+    # here scheme is a default value:
+    uri_base_split = urlsplit(uri_base, scheme='')
+    return rpurib_validate_uri_base_split(uri_base_split)
+
+
+def rpurib_validate_uri_split(uri_split: SplitResult) -> SplitResult:
+    if not is_uri_absolute(uri_split):
+        raise RPURIBValidateURIValueError(
+            'URI should be absolute',
+            RPURIBValidateURIValueErrorCode.IS_RELATIVE,
+        )
+    if uri_split.fragment:
+        raise RPURIBValidateURIValueError(
+            'URI should not have a fragment',
+            RPURIBValidateURIValueErrorCode.HAS_FRAGMENT,
+        )
+    if unquote(uri_split.query):
+        raise RPURIBValidateURIValueError(
+            'URI should not have a query',
+            RPURIBValidateURIValueErrorCode.HAS_QUERY,
+        )
+    return uri_split
+
+
+def rpurib_split_and_validate_uri(uri: str) -> SplitResult:
+    # here scheme is a default value:
+    uri_split = urlsplit(uri, scheme='')
+    return rpurib_validate_uri_split(uri_split)
+
+
+class RPURIBNotRelativeValueError(ValueError):
+    pass
+
+
+def relative_path_from_uri_by_base_splits_validated(
+    uri_split: SplitResult, uri_base_split: SplitResult,
+) -> PurePosixPath:
+    uri_path = PurePosixPath(unquote(uri_split.path))
+    uri_base_path = PurePosixPath(unquote(uri_base_split.path))
+    try:
+        return uri_path.relative_to(uri_base_path, walk_up=False)
+    except ValueError as err:
+        raise RPURIBNotRelativeValueError(str(err)) from err
+
+
+def _relative_path_from_uri_by_base(
+    uri: str | SplitResult, uri_base: str | SplitResult,
+) -> PurePosixPath:
+    # XXX: ValueError s are propagated
+    if not isinstance(uri_base, SplitResult):
+        uri_base_split = rpurib_split_and_validate_uri_base(uri_base)
+    else:
+        uri_base_split = uri_base
+    if not isinstance(uri, SplitResult):
+        uri_split = rpurib_split_and_validate_uri(uri)
+    else:
+        uri_split = uri
+    return relative_path_from_uri_by_base_splits_validated(uri_split, uri_base_split)
+
+
+def translate_uri_base_splits_validated(
+    uri_split: SplitResult,
+    uri_base_old_split: SplitResult,
+    uri_base_new_split: SplitResult,
+) -> SplitResult:
+    path_rel = _relative_path_from_uri_by_base(uri_split, uri_base_old_split)
+    uri_base_new_split = rpurib_validate_uri_base_split(uri_base_new_split)
+    path_new = PurePosixPath(uri_base_new_split.path) / path_rel
+    return uri_split._replace(
+        scheme=uri_base_new_split.scheme,
+        netloc=uri_base_new_split.netloc,
+        path=str(path_new),
+    )

jsonschema_extras/formats/__init__.py

@@ -0,0 +1,30 @@
+"""Utilities for working with format checkers, and some bundled
+format checkers.
+
+To use some of the bundled format checkers:
+
+1. instantiate a :class:`jsonschema.FormatChecker`
+   (or use one which you already instantiate);
+2. add desired format checking functions to the format checker
+   using :func:`register_funcs_in_checker` or :func:`register_func_in_checker`
+   with bundled instances of :class:`FormatCheckingFuncInfo`;
+3. pass the format checker to :func:`jsonschema.validate`
+   or :class:`jsonschema.protocols.Validator` to enable validation of formats.
+"""
+
+from ._common import *  # noqa: F401,F403
+from .numbers_range import *  # noqa: F401,F403
+from .slice_string import *  # noqa: F401,F403
+
+
+__all__ = (
+    'FormatCheckFn',
+    'FormatCheckingFuncInfo',
+    'register_func_in_checker',
+    'register_funcs_in_checker',
+    'is_numbers_range',
+    'is_numbers_range_info',
+    'SLICE_STRING_PATTERN',
+    'is_slice_string',
+    'is_slice_string_info',
+)

jsonschema_extras/formats/_common.py

@@ -0,0 +1,74 @@
+from collections.abc import Callable, Iterable, Sequence
+from typing import TYPE_CHECKING, NamedTuple
+
+
+if TYPE_CHECKING:
+    from jsonschema import FormatChecker
+
+
+#: Format checking function.
+#:
+#: Note:
+#:     Any exceptions the function raises on an invalid data value are part
+#:     of the function's contract for :class:`~jsonschema.FormatChecker`.
+#:
+#: Args:
+#:     object: a data value to validate
+#:
+#: Returns:
+#:     bool: whether the object is valid for the format
+type FormatCheckFn = Callable[[object], bool]
+
+
+class FormatCheckingFuncInfo(NamedTuple):
+    """Data needed to register a format checking function
+    in a :class:`~jsonschema.FormatChecker`.
+
+    Attributes:
+        format: Exact name of the format for JSON Schema.
+        func:
+            Function that checks if a JSON data value satisfies a format.
+        raises:
+            Type(s) of exceptions raised by `func` on an invalid value.
+            Exceptions of other types are immediately propagated.
+            See :meth:`~jsonschema.FormatChecker.checks` for details.
+    """
+    format: str
+    func: FormatCheckFn
+    raises: type[Exception] | tuple[type[Exception], ...] = ()
+
+
+def register_func_in_checker(
+    checker: 'FormatChecker', func_info: FormatCheckingFuncInfo,
+) -> FormatCheckFn:
+    """Register a format checking function
+    in a :class:`~jsonschema.FormatChecker`.
+
+    Utility function working with :class:`FormatCheckingFuncInfo`.
+
+    Args:
+        checker (jsonschema.FormatChecker): A ``format`` property checker.
+        func_info (FormatCheckingFuncInfo):
+            Data needed to register a format checking function.
+
+    Returns:
+        ``func_info.func``
+    """
+    return checker.checks(func_info.format, func_info.raises)(func_info.func)
+
+
+def register_funcs_in_checker(
+    checker: 'FormatChecker', funcs_info: Iterable[FormatCheckingFuncInfo],
+) -> Sequence[FormatCheckFn]:
+    """Register multiple format checking functions
+    in a :class:`~jsonschema.FormatChecker`.
+
+    Args:
+        checker (jsonschema.FormatChecker): A ``format`` property checker.
+        funcs_info (Iterable[FormatCheckingFuncInfo]):
+            Instances of data needed to register formatt checking functions.
+
+    Returns:
+        sequence of ``func_info.func`` objects
+    """
+    return [register_func_in_checker(checker, func_info) for func_info in funcs_info]

jsonschema_extras/formats/numbers_range.py

@@ -0,0 +1,57 @@
+from collections.abc import Sequence
+from typing import cast
+
+from jsonschema_extras._util import SEQUENCE_PRIMITIVE_TYPES_DEFAULT
+from ._common import FormatCheckingFuncInfo
+
+
+def is_numbers_range(instance: object) -> bool:
+    """Tests if an object is a numbers range (a sequence of 2 numbers
+    in non-descending order).
+
+    A numbers range is defined as a sequence containing exactly 2 comparable
+    numeric elements where the first element is less than or equal
+    to the second element, forming a valid range [min, max].
+
+    Returns:
+        bool: Whether `instance` is a numbers range: ascending sequence
+        of 2 numbers.
+
+    Examples:
+
+        Valid ranges::
+
+            >>> is_numbers_range([1, 5])
+            True
+            >>> is_numbers_range([3.14, 3.14])
+            True
+            >>> is_numbers_range((0, 10))
+            True
+
+        Invalid ranges::
+
+            >>> is_numbers_range([5, 1])
+            False
+            >>> is_numbers_range([1, 2, 3])
+            False
+            >>> is_numbers_range([1])
+            False
+            >>> is_numbers_range(5)
+            False
+    """
+    if not (
+        isinstance(instance, Sequence)
+        and (not isinstance(instance, tuple(SEQUENCE_PRIMITIVE_TYPES_DEFAULT)))
+        and (len(instance) == 2)
+    ):
+        return False
+    try:
+        return cast(bool, (instance[0] <= instance[1]))
+    except TypeError:
+        return False
+
+
+#: Format ``numbers-range`` checked by :func:`is_numbers_range`
+is_numbers_range_info = FormatCheckingFuncInfo(
+    'numbers-range', is_numbers_range, (TypeError,),
+)