You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
182 lines
6.4 KiB
182 lines
6.4 KiB
"""
|
|
typing.Protocol classes for jsonschema interfaces.
|
|
"""
|
|
|
|
# for reference material on Protocols, see
|
|
# https://www.python.org/dev/peps/pep-0544/
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import TYPE_CHECKING, Any, ClassVar, Iterator
|
|
import sys
|
|
|
|
# doing these imports with `try ... except ImportError` doesn't pass mypy
|
|
# checking because mypy sees `typing._SpecialForm` and
|
|
# `typing_extensions._SpecialForm` as incompatible
|
|
#
|
|
# see:
|
|
# https://mypy.readthedocs.io/en/stable/runtime_troubles.html#using-new-additions-to-the-typing-module
|
|
# https://github.com/python/mypy/issues/4427
|
|
if sys.version_info >= (3, 8):
|
|
from typing import Protocol, runtime_checkable
|
|
else:
|
|
from typing_extensions import Protocol, runtime_checkable
|
|
|
|
# in order for Sphinx to resolve references accurately from type annotations,
|
|
# it needs to see names like `jsonschema.TypeChecker`
|
|
# therefore, only import at type-checking time (to avoid circular references),
|
|
# but use `jsonschema` for any types which will otherwise not be resolvable
|
|
if TYPE_CHECKING:
|
|
import jsonschema
|
|
|
|
from jsonschema.exceptions import ValidationError
|
|
from jsonschema.validators import RefResolver
|
|
|
|
# For code authors working on the validator protocol, these are the three
|
|
# use-cases which should be kept in mind:
|
|
#
|
|
# 1. As a protocol class, it can be used in type annotations to describe the
|
|
# available methods and attributes of a validator
|
|
# 2. It is the source of autodoc for the validator documentation
|
|
# 3. It is runtime_checkable, meaning that it can be used in isinstance()
|
|
# checks.
|
|
#
|
|
# Since protocols are not base classes, isinstance() checking is limited in
|
|
# its capabilities. See docs on runtime_checkable for detail
|
|
|
|
|
|
@runtime_checkable
|
|
class Validator(Protocol):
|
|
"""
|
|
The protocol to which all validator classes should adhere.
|
|
|
|
:argument schema: the schema that the validator object
|
|
will validate with. It is assumed to be valid, and providing
|
|
an invalid schema can lead to undefined behavior. See
|
|
`Validator.check_schema` to validate a schema first.
|
|
:argument resolver: an instance of `jsonschema.RefResolver` that will be
|
|
used to resolve :kw:`$ref` properties (JSON references). If
|
|
unprovided, one will be created.
|
|
:argument format_checker: an instance of `jsonschema.FormatChecker`
|
|
whose `jsonschema.FormatChecker.conforms` method will be called to
|
|
check and see if instances conform to each :kw:`format`
|
|
property present in the schema. If unprovided, no validation
|
|
will be done for :kw:`format`. Certain formats require
|
|
additional packages to be installed (ipv5, uri, color, date-time).
|
|
The required packages can be found at the bottom of this page.
|
|
"""
|
|
|
|
#: An object representing the validator's meta schema (the schema that
|
|
#: describes valid schemas in the given version).
|
|
META_SCHEMA: ClassVar[dict]
|
|
|
|
#: A mapping of validation keywords (`str`\s) to functions that
|
|
#: validate the keyword with that name. For more information see
|
|
#: `creating-validators`.
|
|
VALIDATORS: ClassVar[dict]
|
|
|
|
#: A `jsonschema.TypeChecker` that will be used when validating
|
|
#: :kw:`type` keywords in JSON schemas.
|
|
TYPE_CHECKER: ClassVar[jsonschema.TypeChecker]
|
|
|
|
#: A `jsonschema.FormatChecker` that will be used when validating
|
|
#: :kw:`format` properties in JSON schemas.
|
|
FORMAT_CHECKER: ClassVar[jsonschema.FormatChecker]
|
|
|
|
#: The schema that was passed in when initializing the object.
|
|
schema: dict | bool
|
|
|
|
def __init__(
|
|
self,
|
|
schema: dict | bool,
|
|
resolver: RefResolver | None = None,
|
|
format_checker: jsonschema.FormatChecker | None = None,
|
|
) -> None:
|
|
...
|
|
|
|
@classmethod
|
|
def check_schema(cls, schema: dict) -> None:
|
|
"""
|
|
Validate the given schema against the validator's `META_SCHEMA`.
|
|
|
|
:raises: `jsonschema.exceptions.SchemaError` if the schema
|
|
is invalid
|
|
"""
|
|
|
|
def is_type(self, instance: Any, type: str) -> bool:
|
|
"""
|
|
Check if the instance is of the given (JSON Schema) type.
|
|
|
|
:type type: str
|
|
:rtype: bool
|
|
:raises: `jsonschema.exceptions.UnknownType` if ``type``
|
|
is not a known type.
|
|
"""
|
|
|
|
def is_valid(self, instance: dict) -> bool:
|
|
"""
|
|
Check if the instance is valid under the current `schema`.
|
|
|
|
:rtype: bool
|
|
|
|
>>> schema = {"maxItems" : 2}
|
|
>>> Draft202012Validator(schema).is_valid([2, 3, 4])
|
|
False
|
|
"""
|
|
|
|
def iter_errors(self, instance: dict) -> Iterator[ValidationError]:
|
|
r"""
|
|
Lazily yield each of the validation errors in the given instance.
|
|
|
|
:rtype: an `collections.abc.Iterable` of
|
|
`jsonschema.exceptions.ValidationError`\s
|
|
|
|
>>> schema = {
|
|
... "type" : "array",
|
|
... "items" : {"enum" : [1, 2, 3]},
|
|
... "maxItems" : 2,
|
|
... }
|
|
>>> v = Draft202012Validator(schema)
|
|
>>> for error in sorted(v.iter_errors([2, 3, 4]), key=str):
|
|
... print(error.message)
|
|
4 is not one of [1, 2, 3]
|
|
[2, 3, 4] is too long
|
|
"""
|
|
|
|
def validate(self, instance: dict) -> None:
|
|
"""
|
|
Check if the instance is valid under the current `schema`.
|
|
|
|
:raises: `jsonschema.exceptions.ValidationError` if the
|
|
instance is invalid
|
|
|
|
>>> schema = {"maxItems" : 2}
|
|
>>> Draft202012Validator(schema).validate([2, 3, 4])
|
|
Traceback (most recent call last):
|
|
...
|
|
ValidationError: [2, 3, 4] is too long
|
|
"""
|
|
|
|
def evolve(self, **kwargs) -> "Validator":
|
|
"""
|
|
Create a new validator like this one, but with given changes.
|
|
|
|
Preserves all other attributes, so can be used to e.g. create a
|
|
validator with a different schema but with the same :kw:`$ref`
|
|
resolution behavior.
|
|
|
|
>>> validator = Draft202012Validator({})
|
|
>>> validator.evolve(schema={"type": "number"})
|
|
Draft202012Validator(schema={'type': 'number'}, format_checker=None)
|
|
|
|
The returned object satisfies the validator protocol, but may not
|
|
be of the same concrete class! In particular this occurs
|
|
when a :kw:`$ref` occurs to a schema with a different
|
|
:kw:`$schema` than this one (i.e. for a different draft).
|
|
|
|
>>> validator.evolve(
|
|
... schema={"$schema": Draft7Validator.META_SCHEMA["$id"]}
|
|
... )
|
|
Draft7Validator(schema=..., format_checker=None)
|
|
"""
|