Add `jsonschema.protocols.IValidator`

This is a Protocol implementation for type checking under mypy and
other static analyzers. It uses the protocol class defined in py3.8+
and uses typing_extensions as a backport for py3.7

The documentation-only validator class has been replaced with the
protocol, and docs are now driven via autoclass on the protocol.

Importantly, several documented methods of the class have been
removed, as they were marked deprecated under jsonschema v3.0 and are
no longer provided by the builtin validators.

Minor adjustments to the docs are made to repoint references at the
new class definition.

4 files changed, 15 insertions, 141 deletions

diff --git a/docs/creating.rst b/docs/creating.rst
index a9f18d1..468e81d 100644
--- a/docs/creating.rst
+++ b/docs/creating.rst
@@ -23,3 +23,11 @@ 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, ``jsonschema.protocols.IValidator`` which
+can be used in type annotations to describe the type of a validator object.
+
+For full details, see `validator-protocol`.
diff --git a/docs/errors.rst b/docs/errors.rst
index 2b2f485..ceb5607 100644
--- a/docs/errors.rst
+++ b/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.IValidator.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
diff --git a/docs/faq.rst b/docs/faq.rst
index d8eea5b..dbe0ef3 100644
--- a/docs/faq.rst
+++ b/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.IValidator`
+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.)
diff --git a/docs/validate.rst b/docs/validate.rst
index 3d8134d..d6b901f 100644
--- a/docs/validate.rst
+++ b/docs/validate.rst
@@ -19,150 +19,16 @@ 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
 -----------------------
 
-`jsonschema` defines an (informal) interface that all validator
+`jsonschema` defines an interface 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.IValidator
+    :members:
 
 All of the `versioned validators <versioned-validators>` that are included with
 `jsonschema` adhere to the interface, and implementers of validator classes