jsonschema_extras.registries.filesystem module

Utilities for accessing schemas on a local filesystem.

Functions in this module match up a path to a directory on a filesystem (root of local schemas hierarchy) with a base URI for schemas. When retrieving a schema by its URI, they compute the portion relative to the specified base URI and use it as a path relative to the specified filesystem root path to locate the schema file.

Both the base URI and specific schema URIs are restricted: each must have the scheme file: and a path, 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 by this module’s functions.

jsonschema_extras.registries.filesystem.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)

exception jsonschema_extras.registries.filesystem.NoSuchResourceFromValueError[source]

Bases: ValueError

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

jsonschema_extras.registries.filesystem.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:
jsonschema_extras.registries.filesystem.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)] | CacheSpecDefault | 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.filesystem.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.filesystem.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.