summaryrefslogtreecommitdiff
path: root/docs/errors.rst
diff options
context:
space:
mode:
authorJulian Berman <Julian@GrayVines.com>2013-09-22 18:37:45 -0400
committerJulian Berman <Julian@GrayVines.com>2013-10-27 18:35:29 -0400
commit8199901c3b434366edb8b87d5b56c65ca624bcca (patch)
treeb894226e7cb9dac7060c2c84c58f12bc93a53cd5 /docs/errors.rst
parent3c6568b2171794aadc8df25dd79a5d491008fb48 (diff)
downloadjsonschema-8199901c3b434366edb8b87d5b56c65ca624bcca.tar.gz
Initial stab at best_match.
Diffstat (limited to 'docs/errors.rst')
-rw-r--r--docs/errors.rst31
1 files changed, 31 insertions, 0 deletions
diff --git a/docs/errors.rst b/docs/errors.rst
index 9f63c25..c3cf096 100644
--- a/docs/errors.rst
+++ b/docs/errors.rst
@@ -301,3 +301,34 @@ 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
+----------
+
+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.
+
+ 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.
+ :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.