jsonschema_extras.registries package

type jsonschema_extras.registries.CacheFn = Callable[[Retrieve], Retrieve]
type jsonschema_extras.registries.CacheSpecDefault = Literal['default']
jsonschema_extras.registries.LOADS_FN_JSON_DEFAULT(text, *, loads_kwargs=None)

Deserialize a schema from JSON text

Satisfies LoadTextFn.

Return type:

Any

Parameters:

  • text (str)

  • loads_kwargs (Kwargs | None)

type jsonschema_extras.registries.LoadTextFn = Callable[[str], D]
exception jsonschema_extras.registries.NoSuchResourceFromValueError[source]

Bases: ValueError

ValueError in a schema’s URI that should be interpreted as absence of the resource.

jsonschema_extras.registries.RESOURCE_FROM_CONTENTS_FN_DEFAULT(contents, default_specification=<class 'referencing._core.Specification'>)

Create a resource guessing which specification applies to the contents.

Raises:

CannotDetermineSpecification – if the given contents don’t have any discernible information which could be used to guess which specification they identify as

Return type:

Resource[TypeVar(D)]

Parameters:
type jsonschema_extras.registries.ResourceFromContentsFn = Callable[[D], Resource]
class jsonschema_extras.registries.RetrievalURITranslator(retrieve, uri_base_old, uri_base_new, *, allow_old=False)[source]

Bases: Generic[D]

Decorator for a Retrieve callable translating URIs that match with a given old base URI to a new base URI.

When retrieving a resource, this decorator attempts to resolve the portion of the URI relative to the old base URI. If successful, it rewrites and appends this portion to the new base URI. If translation fails, it either falls back to the original URI (if allow_old is True) or immediately raises NoSuchResource.

Both base URIs and specific schema URIs are restricted: each must have a scheme and a path, and no other components are allowed (i.e. no credentials, netloc, query, fragment). “Parent” segments .. in the path of a schema URI are prohibited. All of the above properties are validated.

Parameters:

  • retrieve (Retrieve[TypeVar(D)]) – Retriever object that implements referencing.typing.Retrieve.

  • uri_base_old (str) – “Old” base URI.

  • uri_base_new (str) – “New” base URI.

  • allow_old (bool) – If True and retrieval by a translated URI fails, also tries the original URI. Default: False.

type jsonschema_extras.registries.RetrieveTextFn = Callable[[str], str]
class jsonschema_extras.registries.RetrieversChain(retrievers=(), postpone_excs=(), pass_excs=(), should_postpone_exc_fn=<function RetrieversChain.<lambda>>)[source]

Bases: list[Retrieve[D]], Generic[D]

Chain of Retrieve callables that attempts each retriever in order until one succeeds.

Warning

The chain is based on list, so it is mutable (and has all methods of list). If you mutate it after passing to a Registry, make sure you know what you are doing.

Allows a user to customize which exceptions are postponed vs raised immediately.

On retrieval failure, provides detailed cause info.

Parameters:
property pass_excs: Collection[type[Exception]]

Exposed read‑only view of pass_excs passed into the constructor.

property postpone_excs: Collection[type[Exception]]

Exposed read‑only view of postpone_excs passed into the constructor.

property should_postpone_exc_fn: Callable[[Exception], bool]

Exposed read‑only view of should_postpone_exc_fn passed into the constructor.

jsonschema_extras.registries.build_schemas_from_filesystem_retriever(uri_base, path, *, open_kwargs=None, cache=None, loads=<function schema_data_from_json_text>, from_contents=<bound method Resource.from_contents of <class 'referencing._core.Resource'>>)[source]

Returns a new retrieval callable for schemas on a filesystem under a specified root.

The returned retriever maps URIs under uri_base to files under path. See the rules of this mapping and restrictions on URIs in description of jsonschema_extras.registries.filesystem.

Parameters:

  • uri_base (str) – Base URI corresponding to the filesystem root. Must have the scheme file: and a path, no other components are allowed (i.e. no credentials, netloc, query, fragment).

  • path (str | PathLike[str]) – Root filesystem path containing the schemas.

  • open_kwargs (Mapping[str, Any] | None) – Keyword arguments to pass to Python built-in function open(). Allowed arguments: buffering, encoding (default: 'utf-8'), errors, newline.

  • cache (GenericAlias[TypeVar(D)] | Literal['default'] | None) – Caching decorator for Retrieve, or 'default' to use the default caching implementation (see description of jsonschema_extras.registries.retrieval for details). Defaults to None, meaning no caching.

  • loads (GenericAlias[TypeVar(D)]) – Function to deserialize resource contents (for example, JSON data structure from JSON string). Default: LOADS_FN_JSON_DEFAULT (for JSON).

  • from_contents (GenericAlias[TypeVar(D)]) – Function to produce a Resource from deserialized resource contents. Default: from_contents().

Return type:

Retrieve[TypeVar(D)]

Returns:

A Retrieve callable that resolves schema URIs under uri_base from files under path (with caching, if instructed so).

Raises:

  • ValueError – On invalid uri_base.

  • TypeError – If there are arguments in open_kwargs other than allowed arguments.

jsonschema_extras.registries.file_path_from_uri_by_base(uri, uri_base, path)[source]

Computes the file path of a locally stored schema based on its URI.

Maps a URI under uri_base to a file under path. See the rules of this mapping and restrictions on URIs in description of jsonschema_extras.registries.filesystem.

Parameters:

  • uri (str) – URI of the schema to retrieve. Should be relative to uri_base, otherwise NoSuchResource is raised. Must have the scheme file: and a path (with no “parent” segments ..), no other components are allowed (i.e. no credentials, netloc, query, fragment).

  • uri_base (str) – Base URI corresponding to the filesystem root. Must have the scheme file: and a path, no other components are allowed (i.e. no credentials, netloc, query, fragment).

  • path (str | PathLike[str]) – Root filesystem path containing the schemas.

Return type:

PurePath

Returns:

Path under path to the schema on the filesystem.

Raises:

Examples

>>> file_path_from_uri_by_base(
...     'file:/schemas/person.json',
...     'file:/schemas/',
...     '/var/data/schemas',
... ).as_posix()
'/var/data/schemas/person.json'

>>> file_path_from_uri_by_base(
...     'file:/schemas/definitions/address.json',
...     'file:/schemas/',
...     '/var/data/schemas',
... ).as_posix()
'/var/data/schemas/definitions/address.json'
jsonschema_extras.registries.retrieve_text_from_filesystem(uri, uri_base, path, *, open_kwargs=None)[source]

Retrieves text of a schema on a filesystem under a specified root.

Maps URIs under uri_base to files under path. See the rules of this mapping and restrictions on URIs in description of jsonschema_extras.registries.filesystem.

Parameters:

  • uri (str) – URI of the schema to retrieve. Should be relative to uri_base, otherwise NoSuchResource is raised. Must have the scheme file: and a path (with no “parent” segments ..), no other components are allowed (i.e. no credentials, netloc, query, fragment).

  • uri_base (str) – Base URI corresponding to the filesystem root. Must have the scheme file: and a path, no other components are allowed (i.e. no credentials, netloc, query, fragment).

  • path (str | PathLike[str]) – Root filesystem path containing the schemas.

  • open_kwargs (Mapping[str, Any] | None) – Keyword arguments to pass to Python built-in function open(). Allowed arguments: buffering, encoding (default: 'utf-8'), errors, newline.

Return type:

str

Returns:

Text (serialized representation) of the schema loaded from the filesystem.

Raises:

  • referencing.exceptions.NoSuchResource – If a schema by the given URI does not exist (URI resolution relative to the base URI failed (has a NoSuchResourceFromValueError as cause), or the file was not found on the filesystem (has FileNotFoundError as cause).

  • OSError – If the file cannot be opened for a reason other than it was not found. Passed through from the Python built-in function open().

  • ValueError – On invalid uri or uri_base. OR If there was an encoding error when reading the file (passed through from the Python built-in function open()).

  • TypeError – If there are arguments in open_kwargs other than allowed arguments.

jsonschema_extras.registries.schema_data_from_json_text(text, *, loads_kwargs=None)[source]

Deserialize a schema from JSON text

Satisfies LoadTextFn.

Return type:

Any

Parameters:

  • text (str)

  • loads_kwargs (Kwargs | None)

jsonschema_extras.registries.to_cached_resource(cache=None, loads=<function schema_data_from_json_text>, from_contents=<bound method Resource.from_contents of <class 'referencing._core.Resource'>>)[source]

Build a decorator to make a resource retrieval callable out of a RetrieveTextFn with caching.

RetrieveTextFn retrieves serialized representation by URI. A decorator produced by this function adds deserialization (loads), creating a Resource and caching.

Parameters:
Return type:

Callable[[Callable[[str], str]], Retrieve[TypeVar(D)]]

Returns:

Decorator taking a text retriever RetrieveTextFn and returning a caching resource retriever.

jsonschema_extras.registries.to_maybe_cached_resource(cache=None, loads=<function schema_data_from_json_text>, from_contents=<bound method Resource.from_contents of <class 'referencing._core.Resource'>>)[source]

Build a decorator to make a resource retrieval callable out of a RetrieveTextFn with optional caching.

RetrieveTextFn retrieves serialized representation by URI. A decorator produced by this function adds deserialization (loads), creating a Resource and optional caching.

Parameters:
Return type:

Callable[[Callable[[str], str]], Retrieve[TypeVar(D)]]

Returns:

Decorator taking a text retriever RetrieveTextFn and returning a resource retriever.

jsonschema_extras.registries.to_resource(loads=<function schema_data_from_json_text>, from_contents=<bound method Resource.from_contents of <class 'referencing._core.Resource'>>)[source]

Build a decorator to make a resource retrieval callable out of a RetrieveTextFn.

RetrieveTextFn retrieves serialized representation by URI. A decorator produced by this function adds deserialization (loads), creating a Resource (with no caching).

Parameters:

  • loads (GenericAlias[TypeVar(D)]) – Function to deserialize resource contents (for example, JSON data structure from JSON string). Default: LOADS_FN_JSON_DEFAULT (for JSON).

  • from_contents (GenericAlias[TypeVar(D)]) – Function to produce a Resource from deserialized resource contents. Default: from_contents().

Return type:

Callable[[Callable[[str], str]], Retrieve[TypeVar(D)]]

Returns:

Decorator taking a text retriever RetrieveTextFn and returning a caching resource retriever.

Subpackages

Submodules