add JsonParseError

Author: samuelcolvin

crates/jiter-python/jiter.pyi

@@ -63,8 +63,35 @@ class LosslessFloat:
     def __bytes__(self) -> bytes:
         """Return the JSON bytes slice as bytes"""
 
-    def __str__(self):
+    def __str__(self) -> str:
         """Return the JSON bytes slice as a string"""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        ...
+
+
+class JsonParseError(ValueError):
+    """
+    Represents details of failed JSON parsing.
+    """
+
+    def kind(self) -> str:
+        ...
+
+    def description(self) -> str:
+        ...
+
+    def index(self) -> int:
+        ...
+
+    def line(self) -> int:
+        ...
+
+    def column(self) -> int:
+        ...
+
+    def __str__(self) -> str:
+        """String summary of the error, combined description and position"""
+
+    def __repr__(self) -> str:
         ...

crates/jiter-python/src/lib.rs

@@ -2,7 +2,7 @@ use std::sync::OnceLock;
 
 use pyo3::prelude::*;
 
-use jiter::{map_json_error, LosslessFloat, PartialMode, PythonParse, StringCacheMode};
+use jiter::{JsonParseError, LosslessFloat, PartialMode, PythonParse, StringCacheMode};
 
 #[allow(clippy::fn_params_excessive_bools)]
 #[pyfunction(
@@ -33,9 +33,7 @@ pub fn from_json<'py>(
         catch_duplicate_keys,
         lossless_floats,
     };
-    parse_builder
-        .python_parse(py, json_data)
-        .map_err(|e| map_json_error(json_data, &e))
+    parse_builder.python_parse_exc(py, json_data)
 }
 
 pub fn get_jiter_version() -> &'static str {
@@ -70,5 +68,6 @@ fn jiter_python(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(cache_clear, m)?)?;
     m.add_function(wrap_pyfunction!(cache_usage, m)?)?;
     m.add_class::<LosslessFloat>()?;
+    m.add_class::<JsonParseError>()?;
     Ok(())
 }

crates/jiter-python/tests/test_jiter.py

@@ -7,14 +7,14 @@
 from dirty_equals import IsFloatNan
 
 
-def test_python_parse_numeric():
+def test_parse_numeric():
     parsed = jiter.from_json(
         b'  { "int": 1, "bigint": 123456789012345678901234567890, "float": 1.2}  '
     )
     assert parsed == {"int": 1, "bigint": 123456789012345678901234567890, "float": 1.2}
 
 
-def test_python_parse_other_cached():
+def test_parse_other_cached():
     parsed = jiter.from_json(
         b'["string", true, false, null, NaN, Infinity, -Infinity]',
         allow_inf_nan=True,
@@ -23,27 +23,34 @@ def test_python_parse_other_cached():
     assert parsed == ["string", True, False, None, IsFloatNan(), inf, -inf]
 
 
-def test_python_parse_other_no_cache():
+def test_parse_other_no_cache():
     parsed = jiter.from_json(
         b'["string", true, false, null]',
         cache_mode=False,
     )
     assert parsed == ["string", True, False, None]
 
 
-def test_python_disallow_nan():
-    with pytest.raises(ValueError, match="expected value at line 1 column 2"):
+def test_disallow_nan():
+    with pytest.raises(jiter.JsonParseError, match="expected value at line 1 column 2"):
         jiter.from_json(b"[NaN]", allow_inf_nan=False)
 
 
 def test_error():
-    with pytest.raises(ValueError, match="EOF while parsing a list at line 1 column 9"):
+    with pytest.raises(jiter.JsonParseError, match="EOF while parsing a list at line 1 column 9") as exc_info:
         jiter.from_json(b'["string"')
 
+    assert exc_info.value.kind() == 'EofWhileParsingList'
+    assert exc_info.value.description() == 'EOF while parsing a list'
+    assert exc_info.value.index() == 9
+    assert exc_info.value.line() == 1
+    assert exc_info.value.column() == 9
+    assert repr(exc_info.value) == 'JsonParseError("EOF while parsing a list at line 1 column 9")'
+
 
 def test_recursion_limit():
     with pytest.raises(
-        ValueError, match="recursion limit exceeded at line 1 column 202"
+        jiter.JsonParseError, match="recursion limit exceeded at line 1 column 202"
     ):
         jiter.from_json(b"[" * 10_000)
 
@@ -150,21 +157,21 @@ def test_partial_nested():
         assert isinstance(parsed, dict)
 
 
-def test_python_cache_usage_all():
+def test_cache_usage_all():
     jiter.cache_clear()
     parsed = jiter.from_json(b'{"foo": "bar", "spam": 3}', cache_mode="all")
     assert parsed == {"foo": "bar", "spam": 3}
     assert jiter.cache_usage() == 3
 
 
-def test_python_cache_usage_keys():
+def test_cache_usage_keys():
     jiter.cache_clear()
     parsed = jiter.from_json(b'{"foo": "bar", "spam": 3}', cache_mode="keys")
     assert parsed == {"foo": "bar", "spam": 3}
     assert jiter.cache_usage() == 2
 
 
-def test_python_cache_usage_none():
+def test_cache_usage_none():
     jiter.cache_clear()
     parsed = jiter.from_json(
         b'{"foo": "bar", "spam": 3}',

crates/jiter/src/errors.rs

@@ -107,6 +107,35 @@ impl std::fmt::Display for JsonErrorType {
     }
 }
 
+impl JsonErrorType {
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Self::FloatExpectingInt => "FloatExpectingInt",
+            Self::DuplicateKey(_) => "DuplicateKey",
+            Self::EofWhileParsingList => "EofWhileParsingList",
+            Self::EofWhileParsingObject => "EofWhileParsingObject",
+            Self::EofWhileParsingString => "EofWhileParsingString",
+            Self::EofWhileParsingValue => "EofWhileParsingValue",
+            Self::ExpectedColon => "ExpectedColon",
+            Self::ExpectedListCommaOrEnd => "ExpectedListCommaOrEnd",
+            Self::ExpectedObjectCommaOrEnd => "ExpectedObjectCommaOrEnd",
+            Self::ExpectedSomeIdent => "ExpectedSomeIdent",
+            Self::ExpectedSomeValue => "ExpectedSomeValue",
+            Self::InvalidEscape => "InvalidEscape",
+            Self::InvalidNumber => "InvalidNumber",
+            Self::NumberOutOfRange => "NumberOutOfRange",
+            Self::InvalidUnicodeCodePoint => "InvalidUnicodeCodePoint",
+            Self::ControlCharacterWhileParsingString => "ControlCharacterWhileParsingString",
+            Self::KeyMustBeAString => "KeyMustBeAString",
+            Self::LoneLeadingSurrogateInHexEscape => "LoneLeadingSurrogateInHexEscape",
+            Self::TrailingComma => "TrailingComma",
+            Self::TrailingCharacters => "TrailingCharacters",
+            Self::UnexpectedEndOfHexEscape => "UnexpectedEndOfHexEscape",
+            Self::RecursionLimitExceeded => "RecursionLimitExceeded",
+        }
+    }
+}
+
 pub type JsonResult<T> = Result<T, JsonError>;
 
 /// Represents an error from parsing JSON

crates/jiter/src/lib.rs

@@ -6,6 +6,8 @@ mod lazy_index_map;
 mod number_decoder;
 mod parse;
 #[cfg(feature = "python")]
+mod py_error;
+#[cfg(feature = "python")]
 mod py_lossless_float;
 #[cfg(feature = "python")]
 mod py_string_cache;
@@ -23,9 +25,11 @@ pub use number_decoder::{NumberAny, NumberInt};
 pub use parse::Peek;
 pub use value::{JsonArray, JsonObject, JsonValue};
 
+#[cfg(feature = "python")]
+pub use py_error::JsonParseError;
 #[cfg(feature = "python")]
 pub use py_lossless_float::LosslessFloat;
 #[cfg(feature = "python")]
 pub use py_string_cache::{cache_clear, cache_usage, cached_py_string, pystring_fast_new, StringCacheMode};
 #[cfg(feature = "python")]
-pub use python::{map_json_error, PartialMode, PythonParse};
+pub use python::{PartialMode, PythonParse};

crates/jiter/src/py_error.rs

@@ -0,0 +1,53 @@
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+
+use crate::errors::{JsonError, LinePosition};
+
+#[pyclass(extends=PyValueError, module="jiter")]
+#[derive(Debug, Clone)]
+pub struct JsonParseError {
+    json_error: JsonError,
+    position: LinePosition,
+}
+
+impl JsonParseError {
+    pub fn new_err(py: Python, json_error: JsonError, json_data: &[u8]) -> PyErr {
+        let position = json_error.get_position(json_data);
+        let slf = Self { json_error, position };
+        match Py::new(py, slf) {
+            Ok(err) => PyErr::from_value_bound(err.into_bound(py).into_any()),
+            Err(err) => err,
+        }
+    }
+}
+
+#[pymethods]
+impl JsonParseError {
+    fn kind(&self) -> &'static str {
+        self.json_error.error_type.kind()
+    }
+
+    fn description(&self) -> String {
+        self.json_error.error_type.to_string()
+    }
+
+    fn index(&self) -> usize {
+        self.json_error.index
+    }
+
+    fn line(&self) -> usize {
+        self.position.line
+    }
+
+    fn column(&self) -> usize {
+        self.position.column
+    }
+
+    fn __str__(&self) -> String {
+        format!("{} at {}", self.json_error.error_type, self.position)
+    }
+
+    fn __repr__(&self) -> String {
+        format!("JsonParseError({:?})", self.__str__())
+    }
+}

crates/jiter/src/python.rs

@@ -12,6 +12,7 @@ use smallvec::SmallVec;
 use crate::errors::{json_err, json_error, JsonError, JsonResult, DEFAULT_RECURSION_LIMIT};
 use crate::number_decoder::{AbstractNumberDecoder, NumberAny, NumberRange};
 use crate::parse::{Parser, Peek};
+use crate::py_error::JsonParseError;
 use crate::py_string_cache::{StringCacheAll, StringCacheKeys, StringCacheMode, StringMaybeCache, StringNoCache};
 use crate::string_decoder::{StringDecoder, Tape};
 use crate::{JsonErrorType, LosslessFloat};
@@ -71,11 +72,13 @@ impl PythonParse {
             StringCacheMode::None => ppp_group!(StringNoCache),
         }
     }
-}
 
-/// Map a `JsonError` to a `PyErr` which can be raised as an exception in Python as a `ValueError`.
-pub fn map_json_error(json_data: &[u8], json_error: &JsonError) -> PyErr {
-    PyValueError::new_err(json_error.description(json_data))
+    /// Like `python_parse`, but maps [`JsonError`] to a `PyErr` which can be raised as an exception in
+    /// Python as a [`JsonParseError`].
+    pub fn python_parse_exc<'py>(self, py: Python<'py>, json_data: &[u8]) -> PyResult<Bound<'py, PyAny>> {
+        self.python_parse(py, json_data)
+            .map_err(|e| JsonParseError::new_err(py, e, json_data))
+    }
 }
 
 struct PythonParser<'j, StringCache, KeyCheck, ParseNumber> {