Merge pull request #890 from sirosen/add-validator-protocol

Add `jsonschema.protocols.IValidator`

Author: Julian

README.rst

@@ -74,7 +74,7 @@ Features
   and
   `Draft 3 <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.Draft3Validator>`_
 
-* `Lazy validation <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.IValidator.iter_errors>`_
+* `Lazy validation <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.protocols.Validator.iter_errors>`_
   that can iteratively report *all* validation errors.
 
 * `Programmatic querying <https://python-jsonschema.readthedocs.io/en/latest/errors/>`_

docs/creating.rst

@@ -23,3 +23,12 @@ Any validating function that validates against a subschema should call
 instance, or schema, it should pass one or both of the ``path`` or
 ``schema_path`` arguments to ``descend`` in order to properly maintain
 where in the instance or schema respectively the error occurred.
+
+The Validator Protocol
+----------------------
+
+``jsonschema`` defines a `protocol <typing.Protocol>`,
+`jsonschema.protocols.Validator` which can be used in type annotations to
+describe the type of a validator object.
+
+For full details, see `validator-protocol`.

docs/errors.rst

@@ -275,7 +275,7 @@ error objects.
 As you can see, `jsonschema.exceptions.ErrorTree` takes an
 iterable of `ValidationError`\s when constructing a tree so
 you can directly pass it the return value of a validator object's
-`jsonschema.IValidator.iter_errors` method.
+`jsonschema.protocols.Validator.iter_errors` method.
 
 `ErrorTree`\s support a number of useful operations. The first one we
 might want to perform is to check whether a given element in our instance

docs/faq.rst

@@ -90,8 +90,8 @@ but fail the second!
 
 Still, filling in defaults is a thing that is useful. `jsonschema`
 allows you to `define your own validator classes and callables
-<creating>`, so you can easily create an `jsonschema.IValidator` that
-does do default setting. Here's some code to get you started. (In
+<creating>`, so you can easily create an `jsonschema.protocols.Validator`
+that does do default setting. Here's some code to get you started. (In
 this code, we add the default properties to each object *before* the
 properties are validated, so the default values themselves will need to
 be valid under the schema.)

docs/spelling-wordlist.txt

@@ -1,5 +1,5 @@
 # this appears to be misinterpreting Napoleon types as prose, sigh...
-IValidator
+Validator
 TypeChecker
 UnknownType
 ValidationError

docs/validate.rst

@@ -19,160 +19,26 @@ The simplest way to validate an instance under a given schema is to use the
     fundamentals underway at `Understanding JSON Schema
     <https://json-schema.org/understanding-json-schema/>`_
 
+.. _validator-protocol:
 
-The Validator Interface
+The Validator Protocol
 -----------------------
 
-`jsonschema` defines an (informal) interface that all validator
+`jsonschema` defines a protocol that all validator
 classes should adhere to.
 
-.. class:: IValidator(schema, types=(), resolver=None, format_checker=None)
-
-    :argument dict 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
-        `IValidator.check_schema` to validate a schema first.
-    :argument resolver: an instance of `RefResolver` that will be
-        used to resolve :validator:`$ref` properties (JSON references). If
-        unprovided, one will be created.
-    :argument format_checker: an instance of `FormatChecker`
-        whose `FormatChecker.conforms` method will be called to
-        check and see if instances conform to each :validator:`format`
-        property present in the schema. If unprovided, no validation
-        will be done for :validator:`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.
-    :argument types:
-        .. deprecated:: 3.0.0
-
-            Use `TypeChecker.redefine` and
-            `jsonschema.validators.extend` instead of this argument.
-
-                See `validating-types` for details.
-
-        If used, this overrides or extends the list of known types when
-        validating the :validator:`type` property.
-
-        What is provided should map strings (type names) to class objects
-        that will be checked via `isinstance`.
-
-
-    .. attribute:: META_SCHEMA
-
-        An object representing the validator's meta schema (the schema that
-        describes valid schemas in the given version).
-
-    .. attribute:: VALIDATORS
-
-        A mapping of validator names (`str`\s) to functions
-        that validate the validator property with that name. For more
-        information see `creating-validators`.
-
-    .. attribute:: TYPE_CHECKER
-
-        A `TypeChecker` that will be used when validating :validator:`type`
-        properties in JSON schemas.
-
-    .. attribute:: schema
-
-        The schema that was passed in when initializing the object.
-
-    .. attribute:: DEFAULT_TYPES
-
-        .. deprecated:: 3.0.0
-
-            Use of this attribute is deprecated in favor of the new `type
-            checkers <TypeChecker>`.
-
-            See `validating-types` for details.
-
-        For backwards compatibility on existing validator classes, a mapping of
-        JSON types to Python class objects which define the Python types for
-        each JSON type.
-
-        Any existing code using this attribute should likely transition to
-        using `TypeChecker.is_type`.
-
-
-    .. classmethod:: check_schema(schema)
-
-        Validate the given schema against the validator's `META_SCHEMA`.
-
-        :raises: `jsonschema.exceptions.SchemaError` if the schema
-            is invalid
-
-    .. method:: is_type(instance, type)
-
-        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.
-
-    .. method:: is_valid(instance)
-
-        Check if the instance is valid under the current `schema`.
-
-        :rtype: bool
-
-        >>> schema = {"maxItems" : 2}
-        >>> Draft3Validator(schema).is_valid([2, 3, 4])
-        False
-
-    .. method:: iter_errors(instance)
-
-        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 = Draft3Validator(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
-
-    .. method:: validate(instance)
-
-        Check if the instance is valid under the current `schema`.
-
-        :raises: `jsonschema.exceptions.ValidationError` if the
-            instance is invalid
-
-        >>> schema = {"maxItems" : 2}
-        >>> Draft3Validator(schema).validate([2, 3, 4])
-        Traceback (most recent call last):
-            ...
-        ValidationError: [2, 3, 4] is too long
-
-    .. method:: evolve(**kwargs)
-
-        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 :validator:`$ref`
-        resolution behavior.
-
-        >>> validator = Draft202012Validator({})
-        >>> validator.evolve(schema={"type": "number"})
-        Draft202012Validator(schema={'type': 'number'}, format_checker=None)
-
+.. autoclass:: jsonschema.protocols.Validator
+    :members:
 
 All of the `versioned validators <versioned-validators>` that are included with
-`jsonschema` adhere to the interface, and implementers of validator classes
+`jsonschema` adhere to the protocol, and implementers of validator classes
 that extend or complement the ones included should adhere to it as well. For
 more information see `creating-validators`.
 
 Type Checking
 -------------
 
-To handle JSON Schema's :validator:`type` property, a `IValidator` uses
+To handle JSON Schema's :validator:`type` property, a `Validator` uses
 an associated `TypeChecker`. The type checker provides an immutable
 mapping between names of types and functions that can test if an instance is
 of that type. The defaults are suitable for most users - each of the
@@ -216,7 +82,7 @@ given how common validating these types are.
 If you *do* want the generality, or just want to add a few specific additional
 types as being acceptable for a validator object, then you should update an
 existing `TypeChecker` or create a new one. You may then create a new
-`IValidator` via `jsonschema.validators.extend`.
+`Validator` via `jsonschema.validators.extend`.
 
 .. code-block:: python
 
@@ -244,7 +110,7 @@ Versioned Validators
 
 `jsonschema` ships with validator classes for various versions of
 the JSON Schema specification. For details on the methods and attributes
-that each validator class provides see the `IValidator` interface,
+that each validator class provides see the `Validator` interface,
 which each included validator class implements.
 
 .. autoclass:: Draft202012Validator
@@ -289,7 +155,7 @@ JSON Schema defines the :validator:`format` property which can be used to check
 if primitive types (``string``\s, ``number``\s, ``boolean``\s) conform to
 well-defined formats. By default, no validation is enforced, but optionally,
 validation can be enabled by hooking in a format-checking object into an
-`IValidator`.
+`Validator`.
 
 .. doctest::
 

jsonschema/__init__.py

@@ -26,6 +26,7 @@
     SchemaError,
     ValidationError,
 )
+from jsonschema.protocols import Validator
 from jsonschema.validators import (
     Draft3Validator,
     Draft4Validator,

jsonschema/_types.py

@@ -49,7 +49,7 @@ class TypeChecker(object):
     """
     A ``type`` property checker.
 
-    A `TypeChecker` performs type checking for an `IValidator`. Type
+    A `TypeChecker` performs type checking for a `Validator`. Type
     checks to perform are updated using `TypeChecker.redefine` or
     `TypeChecker.redefine_many` and removed via `TypeChecker.remove`.
     Each of these return a new `TypeChecker` object.