Add and use a ValidationError exception, derived from ValueError

This makes it easier to discriminate between invalid document and validation errors.

docs/api.rst

@@ -2,7 +2,7 @@
 .. :Project:   python-rapidjson -- API documentation
 .. :Author:    Lele Gaifax <lele@metapensiero.it>
 .. :License:   MIT License
-.. :Copyright: © 2016, 2017 Lele Gaifax
+.. :Copyright: © 2016, 2017, 2018 Lele Gaifax
 ..
 
 ===============================
@@ -146,6 +146,17 @@
    *arrays* and *objects*.
 
 
+.. rubric:: Exceptions
+
+.. exception:: ValidationError
+
+   Exception raised by :class:`Validator` objects, a subclass of :exc:`ValueError`.
+
+   Its `args` attribute is a tuple with three string values, respectively the *schema
+   keyword* that generated the failure, its *JSON pointer* and a *JSON pointer* to the
+   error location in the (invalid) document.
+
+
 .. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601
 .. _RapidJSON: http://rapidjson.org/
 .. _UTC: https://en.wikipedia.org/wiki/Coordinated_Universal_Time

docs/validator.rst

@@ -2,7 +2,7 @@
 .. :Project:   python-rapidjson -- Validator class documentation
 .. :Author:    Lele Gaifax <lele@metapensiero.it>
 .. :License:   MIT License
-.. :Copyright: © 2017 Lele Gaifax
+.. :Copyright: © 2017, 2018 Lele Gaifax
 ..
 
 =================
@@ -13,7 +13,7 @@
 
 .. testsetup::
 
-   from rapidjson import Validator
+   from rapidjson import ValidationError, Validator
 
 .. class:: Validator(json_schema)
 
@@ -28,17 +28,48 @@
                    ``bytes`` instance, that will be validated
 
       The given `json` value will be validated accordingly to the *schema*: a
-      ``ValueError`` will be raised if the validation fails, and the exception will
-      contain three arguments, respectively the type of the error, the position in the
-      schema and the position in the ``JSON`` document where the error occurred:
+      :exc:`ValidationError` will be raised if the validation fails, and the exception
+      will contain three arguments, respectively the type of the error, the position in
+      the schema and the position in the ``JSON`` document where the error occurred:
 
       .. doctest::
 
          >>> validate = Validator('{"required": ["a", "b"]}')
          >>> validate('{"a": null, "b": 1}')
          >>> try:
          ...   validate('{"a": null, "c": false}')
-         ... except ValueError as error:
+         ... except ValidationError as error:
          ...   print(error.args)
          ...
          ('required', '#', '#')
+
+      .. doctest::
+
+         >>> validate = Validator('{"type": "array",'
+         ...                      ' "items": {"type": "string"},'
+         ...                      ' "minItems": 1}')
+         >>> validate('["foo", "bar"]')
+         >>> try:
+         ...   validate('[]')
+         ... except ValidationError as error:
+         ...   print(error.args)
+         ...
+         ('minItems', '#', '#')
+
+      .. doctest::
+
+         >>> try:
+         ...   validate('[1]')
+         ... except ValidationError as error:
+         ...   print(error.args)
+         ...
+         ('type', '#/items', '#/0')
+
+      When `json` is not a valid JSON document, a :exc:`ValueError` is raised instead:
+
+      .. doctest::
+
+         >>> validate('x')
+         Traceback (most recent call last):
+           File "<stdin>", line 1, in <module>
+         ValueError: Invalid JSON

rapidjson.cpp

@@ -57,6 +57,7 @@ static PyObject* decimal_type = NULL;
 static PyObject* timezone_type = NULL;
 static PyObject* timezone_utc = NULL;
 static PyObject* uuid_type = NULL;
+static PyObject* validation_error = NULL;
 
 
 /* These are the names of oftenly used methods or literal values, interned in the module
@@ -3547,7 +3548,7 @@ static PyObject* validator_call(PyObject* self, PyObject* args, PyObject* kwargs
         validator.GetInvalidDocumentPointer().StringifyUriFragment(dptr);
         Py_END_ALLOW_THREADS
 
-        PyErr_SetObject(PyExc_ValueError,
+        PyErr_SetObject(validation_error,
                         Py_BuildValue("sss", validator.GetInvalidSchemaKeyword(),
                                       sptr.GetString(), dptr.GetString()));
         sptr.Clear();
@@ -3640,6 +3641,7 @@ module_free(void* m)
     Py_CLEAR(timezone_type);
     Py_CLEAR(timezone_utc);
     Py_CLEAR(uuid_type);
+    Py_CLEAR(validation_error);
 }
 
 
@@ -3833,6 +3835,12 @@ PyInit_rapidjson()
     if (PyModule_AddObject(m, "RawJSON", (PyObject*) &RawJSON_Type))
         goto error;
 
+    validation_error = PyErr_NewException("rapidjson.ValidationError",
+                                          PyExc_ValueError, NULL);
+    if (validation_error == NULL
+        || PyModule_AddObject(m, "ValidationError", validation_error))
+        goto error;
+
     return m;
 
 error: