Skip to content

Commit b9dbe5a

Browse files
committed
Slightly tidy the section on protocols in the docs.
1 parent cdc3a21 commit b9dbe5a

File tree

1 file changed

+18
-22
lines changed

1 file changed

+18
-22
lines changed

docs/validate.rst

Lines changed: 18 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,20 @@ The simplest way to validate an instance under a given schema is to use the
2525
The Validator Protocol
2626
-----------------------
2727

28-
`jsonschema` defines a protocol that all validator classes should adhere
29-
to.
28+
`jsonschema` defines a `protocol <typing.Protocol>` that all validator classes adhere to.
29+
30+
.. hint::
31+
32+
If you are unfamiliar with protocols, either as a general notion or as specifically implemented by `typing.Protocol`, you can think of them as a set of attributes and methods that all objects satisfying the protocol have.
33+
34+
Here, in the context of `jsonschema`, the `Validator.iter_errors` method can be called on `jsonschema.validators.Draft202012Validator`, or `jsonschema.validators.Draft7Validator`, or indeed any validator class, as all of them have it, along with all of the other methods described below.
3035

3136
.. autoclass:: jsonschema.protocols.Validator
3237
:noindex:
3338
:members:
3439

35-
All of the `versioned validators <versioned-validators>` that are included with
36-
`jsonschema` adhere to the protocol, and implementers of validator classes
37-
that extend or complement the ones included should adhere to it as well. For
38-
more information see `creating-validators`.
40+
All of the `versioned validators <versioned-validators>` that are included with `jsonschema` adhere to the protocol, and any `extensions of these validators <jsonschema.validators.extend>` will as well.
41+
For more information on `creating <jsonschema.validators.create>` or `extending <jsonschema.validators.extend>` validators see `creating-validators`.
3942

4043
Type Checking
4144
-------------
@@ -119,10 +122,10 @@ existing `TypeChecker` or create a new one. You may then create a new
119122
Versioned Validators
120123
--------------------
121124

122-
`jsonschema` ships with validator classes for various versions of
123-
the JSON Schema specification. For details on the methods and attributes
124-
that each validator class provides see the `Validator` protocol,
125-
which each included validator class implements.
125+
`jsonschema` ships with validator classes for various versions of the JSON Schema specification.
126+
For details on the methods and attributes that each validator class provides see the `Validator` protocol, which each included validator class implements.
127+
128+
Each of the below cover a specific release of the JSON Schema specification.
126129

127130
.. autoclass:: Draft202012Validator
128131
:noindex:
@@ -168,11 +171,8 @@ Draft 2020-12 meta-schema, you could use:
168171
Validating Formats
169172
------------------
170173

171-
JSON Schema defines the :kw:`format` keyword which can be used to check
172-
if primitive types (``string``\s, ``number``\s, ``boolean``\s) conform to
173-
well-defined formats. By default, no validation is enforced, but optionally,
174-
validation can be enabled by hooking in a format-checking object into an
175-
`Validator`.
174+
JSON Schema defines the :kw:`format` keyword which can be used to check if primitive types (``string``\s, ``number``\s, ``boolean``\s) conform to well-defined formats.
175+
By default, no validation is enforced, but optionally, validation can be enabled by hooking in a format-checking object into a `Validator`.
176176

177177
.. doctest::
178178

@@ -191,18 +191,14 @@ validation can be enabled by hooking in a format-checking object into an
191191
:exclude-members: cls_checks
192192

193193
.. attribute:: checkers
194-
A mapping of currently known formats to tuple of functions that
195-
validate them and errors that should be caught. New checkers can be
196-
added and removed either per-instance or globally for all checkers
197-
using the `FormatChecker.checks` or `FormatChecker.cls_checks`
198-
decorators respectively.
194+
A mapping of currently known formats to tuple of functions that validate them and errors that should be caught.
195+
New checkers can be added and removed either per-instance or globally for all checkers using the `FormatChecker.checks` decorator.
199196

200197
.. classmethod:: cls_checks(format, raises=())
201198

202199
Register a decorated function as *globally* validating a new format.
203200

204-
Any instance created after this function is called will pick up the
205-
supplied checker.
201+
Any instance created after this function is called will pick up the supplied checker.
206202

207203
:argument str format: the format that the decorated function will check
208204
:argument Exception raises: the exception(s) raised

0 commit comments

Comments
 (0)