Add a few examples of jsonschema.validators.validator_for.

Author: Julian

docs/conf.py

@@ -67,6 +67,7 @@ def setup(app):
 
 doctest_global_setup = """
 from jsonschema import *
+import jsonschema.validators
 """
 
 

jsonschema/validators.py

@@ -1141,6 +1141,43 @@ def validator_for(schema, default=_UNSET):
 
             If unprovided, the default is to return the latest supported
             draft.
+
+    Examples:
+
+        The :kw:`$schema` JSON Schema keyword will control which validator
+        class is returned:
+
+        >>> schema = {
+        ...     "$schema": "https://json-schema.org/draft/2020-12/schema",
+        ...     "type": "integer",
+        ... }
+        >>> jsonschema.validators.validator_for(schema)
+        <class 'jsonschema.validators.Draft202012Validator'>
+
+
+        Here, a draft 7 schema instead will return the draft 7 validator:
+
+        >>> schema = {
+        ...     "$schema": "http://json-schema.org/draft-07/schema#",
+        ...     "type": "integer",
+        ... }
+        >>> jsonschema.validators.validator_for(schema)
+        <class 'jsonschema.validators.Draft7Validator'>
+
+
+        Schemas with no ``$schema`` keyword will fallback to the default
+        argument:
+
+        >>> schema = {"type": "integer"}
+        >>> jsonschema.validators.validator_for(
+        ...     schema, default=Draft7Validator,
+        ... )
+        <class 'jsonschema.validators.Draft7Validator'>
+
+        or if none is provided, to the latest version supported.
+        Always including the keyword when authoring schemas is highly
+        recommended.
+
     """
 
     DefaultValidator = _LATEST_VERSION if default is _UNSET else default