jsonschema-extras 0.2.0__tar.gz

jsonschema_extras-0.2.0/LICENSE.txt

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

jsonschema_extras-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include jsonschema_extras/VERSION
+recursive-include jsonschema_extras/schemas *.json

jsonschema_extras-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: jsonschema-extras
+Version: 0.2.0
+Summary: Utilities for working with the Python library 'jsonschema'
+Author-email: Viacheslav Syropiatov <nonexistent@example.com>
+License-Expression: MIT
+Project-URL: source, https://github.com/asrelo/jsonschema-extras
+Project-URL: documentation, https://asrelo.github.io/jsonschema-extras
+Project-URL: issues, https://github.com/asrelo/jsonschema-extras/issues
+Keywords: json,json schema,jsonschema,validation,extras,utilities,utils
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: jsonschema~=4.26.0
+Requires-Dist: types-jsonschema
+Dynamic: license-file
+
+# jsonschema-extras
+
+[![PyPI version](https://img.shields.io/pypi/v/jsonschema-extras.svg)](https://pypi.org/project/jsonschema-extras)
+[![Python versions](https://img.shields.io/pypi/pyversions/jsonschema-extras.svg)](https://pypi.org/project/jsonschema-extras)
+[![License](https://img.shields.io/github/license/asrelo/jsonschema-extras.svg)](https://github.com/asrelo/jsonschema-extras/blob/main/LICENSE.txt)
+
+Utilities for working with the JSON Schema Python library [`jsonschema`](https://pypi.org/project/jsonschema/).
+
+**See [documentation](https://asrelo.github.io/jsonschema-extras).**
+
+**Contributions are welcome**, but please consider discussing it in [GitHub issues](https://github.com/asrelo/jsonschema-extras/issues) before committing to it.
+
+## Features
+
+- Specific schemas bundled with the library (easily usable)
+- Specific formats bundled with the library (easily usable)
+- Utilities for accessing JSON-encoded schemas on a local filesystem
+- Other utilities
+
+## Installation
+
+```bash
+pip install jsonschema-extras
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.txt).

jsonschema_extras-0.2.0/README.md

@@ -0,0 +1,28 @@
+# jsonschema-extras
+
+[![PyPI version](https://img.shields.io/pypi/v/jsonschema-extras.svg)](https://pypi.org/project/jsonschema-extras)
+[![Python versions](https://img.shields.io/pypi/pyversions/jsonschema-extras.svg)](https://pypi.org/project/jsonschema-extras)
+[![License](https://img.shields.io/github/license/asrelo/jsonschema-extras.svg)](https://github.com/asrelo/jsonschema-extras/blob/main/LICENSE.txt)
+
+Utilities for working with the JSON Schema Python library [`jsonschema`](https://pypi.org/project/jsonschema/).
+
+**See [documentation](https://asrelo.github.io/jsonschema-extras).**
+
+**Contributions are welcome**, but please consider discussing it in [GitHub issues](https://github.com/asrelo/jsonschema-extras/issues) before committing to it.
+
+## Features
+
+- Specific schemas bundled with the library (easily usable)
+- Specific formats bundled with the library (easily usable)
+- Utilities for accessing JSON-encoded schemas on a local filesystem
+- Other utilities
+
+## Installation
+
+```bash
+pip install jsonschema-extras
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.txt).

jsonschema_extras-0.2.0/jsonschema_extras/VERSION

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

jsonschema_extras-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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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',
+)