From b9dbe5afc7f30ac79de0c5623c4b2d8d7e06651b Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Tue, 30 Aug 2022 10:47:51 +0300 Subject: Slightly tidy the section on protocols in the docs. --- docs/validate.rst | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/validate.rst b/docs/validate.rst index 97039e2..870735b 100644 --- a/docs/validate.rst +++ b/docs/validate.rst @@ -25,17 +25,20 @@ The simplest way to validate an instance under a given schema is to use the The Validator Protocol ----------------------- -`jsonschema` defines a protocol that all validator classes should adhere -to. +`jsonschema` defines a `protocol ` that all validator classes adhere to. + +.. hint:: + + 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. + + 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. .. autoclass:: jsonschema.protocols.Validator :noindex: :members: -All of the `versioned validators ` that are included with -`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`. +All of the `versioned validators ` that are included with `jsonschema` adhere to the protocol, and any `extensions of these validators ` will as well. +For more information on `creating ` or `extending ` validators see `creating-validators`. Type Checking ------------- @@ -119,10 +122,10 @@ existing `TypeChecker` or create a new one. You may then create a new 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 `Validator` protocol, -which each included validator class implements. +`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 `Validator` protocol, which each included validator class implements. + +Each of the below cover a specific release of the JSON Schema specification. .. autoclass:: Draft202012Validator :noindex: @@ -168,11 +171,8 @@ Draft 2020-12 meta-schema, you could use: Validating Formats ------------------ -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. By default, no validation is enforced, but optionally, -validation can be enabled by hooking in a format-checking object into an -`Validator`. +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. +By default, no validation is enforced, but optionally, validation can be enabled by hooking in a format-checking object into a `Validator`. .. doctest:: @@ -191,18 +191,14 @@ validation can be enabled by hooking in a format-checking object into an :exclude-members: cls_checks .. attribute:: checkers - A mapping of currently known formats to tuple of functions that - validate them and errors that should be caught. New checkers can be - added and removed either per-instance or globally for all checkers - using the `FormatChecker.checks` or `FormatChecker.cls_checks` - decorators respectively. + A mapping of currently known formats to tuple of functions that validate them and errors that should be caught. + New checkers can be added and removed either per-instance or globally for all checkers using the `FormatChecker.checks` decorator. .. classmethod:: cls_checks(format, raises=()) Register a decorated function as *globally* validating a new format. - Any instance created after this function is called will pick up the - supplied checker. + Any instance created after this function is called will pick up the supplied checker. :argument str format: the format that the decorated function will check :argument Exception raises: the exception(s) raised -- cgit v1.2.1