diff options
Diffstat (limited to 'docs/errors.rst')
| -rw-r--r-- | docs/errors.rst | 88 |
1 files changed, 86 insertions, 2 deletions
diff --git a/docs/errors.rst b/docs/errors.rst index 9f63c25..7fbd2f0 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -2,7 +2,7 @@ Handling Validation Errors ========================== -.. currentmodule:: jsonschema +.. currentmodule:: jsonschema.exceptions When an invalid instance is encountered, a :exc:`ValidationError` will be raised or returned, depending on which method or function is used. @@ -194,7 +194,7 @@ If you want to programmatically be able to query which properties or validators failed when validating a given instance, you probably will want to do so using :class:`ErrorTree` objects. -.. autoclass:: ErrorTree +.. autoclass:: jsonschema.validators.ErrorTree :members: :special-members: :exclude-members: __dict__,__weakref__ @@ -301,3 +301,87 @@ To summarize, each tree contains child trees that can be accessed by indexing the tree to get the corresponding child tree for a given index into the instance. Each tree and child has a :attr:`~ErrorTree.errors` attribute, a dict, that maps the failed validator to the corresponding validation error. + + +best_match and by_relevance +--------------------------- + +The :func:`best_match` function is a simple but useful function for attempting +to guess the most relevant error in a given bunch. + +.. autofunction:: best_match + + Try to find an error that appears to be the best match among given errors. + + In general, errors that are higher up in the instance (i.e. for which + :attr:`ValidationError.path` is shorter) are considered better matches, + since they indicate "more" is wrong with the instance. + +.. doctest:: + + >>> from jsonschema import Draft4Validator + >>> from jsonschema.exceptions import best_match + + >>> schema = { + ... "type": "array", + ... "minItems": 3, + ... } + >>> print(best_match(Draft4Validator(schema).iter_errors(11)).message) + 11 is not of type 'array' + + If the resulting match is either :validator:`oneOf` or :validator:`anyOf`, + the *opposite* assumption is made -- i.e. the deepest error is picked, + since these validators only need to match once, and any other errors may + not be relevant. + + :argument iterable errors: the errors to select from. Do not provide a + mixture of errors from different validation attempts (i.e. from + different instances or schemas), since it won't produce sensical + output. + :argument callable key: the key to use when sorting errors. See + :func:`by_relevance` for more details (the default is to sort with the + defaults of that function). + :returns: the best matching error, or ``None`` if the iterable was empty + + .. note:: + + This function is a heuristic. Its return value may change for a given + set of inputs from version to version if better heuristics are added. + + +.. autofunction:: by_relevance + + Create a key function that can be used to sort errors by relevance. + + If you want to sort a bunch of errors entirely, you can use this function + to do so. Using the return value of this function as a key to e.g. + :func:`sorted` or :func:`max` will cause more relevant errors to be + considered greater than less relevant ones. + +.. doctest:: + + >>> schema = { + ... "properties": { + ... "name": {"type": "string"}, + ... "phones": { + ... "properties": { + ... "home": {"type": "string"} + ... }, + ... }, + ... }, + ... } + >>> instance = {"name": 123, "phones": {"home": [123]}} + >>> errors = Draft4Validator(schema).iter_errors(instance) + >>> [ + ... e.path[-1] + ... for e in sorted(errors, key=exceptions.by_relevance()) + ... ] + ['home', 'name'] + + :argument set weak: a collection of validators to consider to be "weak". If + there are two errors at the same level of the instance and one is in + the set of weak validators, the other error will take priority. By + default, :validator:`anyOf` and :validator:`oneOf` are considered weak + validators and will be superceded by other same-level validation + errors. + :argument set strong a collection of validators to consider to be "strong". |