Pretty exception messages

Author: jg-rp

jsonpath/env.py

@@ -493,8 +493,9 @@ def check_well_typedness(
         """Check the well-typedness of a function's arguments at compile-time."""
         # Correct number of arguments?
         if len(args) != len(func.arg_types):
+            plural = "" if len(func.arg_types) == 1 else "s"
             raise JSONPathTypeError(
-                f"{token.value!r}() requires {len(func.arg_types)} arguments",
+                f"{token.value}() requires {len(func.arg_types)} argument{plural}",
                 token=token,
             )
 

jsonpath/exceptions.py

@@ -5,6 +5,8 @@
 from typing import TYPE_CHECKING
 from typing import Optional
 
+from .token import TOKEN_EOF
+
 if TYPE_CHECKING:
     from .token import Token
 
@@ -22,13 +24,69 @@ def __init__(self, *args: object, token: Optional[Token] = None) -> None:
         self.token: Optional[Token] = token
 
     def __str__(self) -> str:
-        msg = super().__str__()
+        return self.detailed_message()
 
+    def detailed_message(self) -> str:
+        """Return an error message formatted with extra context info."""
         if not self.token:
-            return msg
+            return super().__str__()
 
-        line, column = self.token.position()
-        return f"{msg}, line {line}, column {column}"
+        lineno, col, _prev, current, _next = self._error_context(
+            self.token.path, self.token.index
+        )
+
+        if self.token.kind == TOKEN_EOF:
+            col = len(current)
+
+        pad = " " * len(str(lineno))
+        length = len(self.token.value)
+        pointer = (" " * col) + ("^" * max(length, 1))
+
+        return (
+            f"{self.message}\n"
+            f"{pad} -> {self.token.path!r} {lineno}:{col}\n"
+            f"{pad} |\n"
+            f"{lineno} | {current}\n"
+            f"{pad} | {pointer} {self.message}\n"
+        )
+
+    @property
+    def message(self) -> object:
+        """The exception's error message if one was given."""
+        if self.args:
+            return self.args[0]
+        return None
+
+    def _error_context(self, text: str, index: int) -> tuple[int, int, str, str, str]:
+        lines = text.splitlines(keepends=True)
+        cumulative_length = 0
+        target_line_index = -1
+
+        for i, line in enumerate(lines):
+            cumulative_length += len(line)
+            if index < cumulative_length:
+                target_line_index = i
+                break
+
+        if target_line_index == -1:
+            raise ValueError("index is out of bounds for the given string")
+
+        # Line number (1-based)
+        line_number = target_line_index + 1
+        # Column number within the line
+        column_number = index - (cumulative_length - len(lines[target_line_index]))
+
+        previous_line = (
+            lines[target_line_index - 1].rstrip() if target_line_index > 0 else ""
+        )
+        current_line = lines[target_line_index].rstrip()
+        next_line = (
+            lines[target_line_index + 1].rstrip()
+            if target_line_index < len(lines) - 1
+            else ""
+        )
+
+        return line_number, column_number, previous_line, current_line, next_line
 
 
 class JSONPathSyntaxError(JSONPathError):

jsonpath/parse.py

@@ -675,19 +675,13 @@ def parse_infix_expression(
         return InfixExpression(left, operator, right)
 
     def parse_grouped_expression(self, stream: TokenStream) -> BaseExpression:
-        stream.eat(TOKEN_LPAREN)
+        _token = stream.eat(TOKEN_LPAREN)
         expr = self.parse_filter_expression(stream)
 
         while stream.current().kind != TOKEN_RPAREN:
             token = stream.current()
-            if token.kind == TOKEN_EOF:
-                raise JSONPathSyntaxError("unbalanced parentheses", token=token)
-
-            if token.kind not in self.BINARY_OPERATORS:
-                raise JSONPathSyntaxError(
-                    f"expected an expression, found '{token.value}'",
-                    token=token,
-                )
+            if token.kind in (TOKEN_EOF, TOKEN_RBRACKET):
+                raise JSONPathSyntaxError("unbalanced parentheses", token=_token)
 
             expr = self.parse_infix_expression(stream, expr)
 

tests/test_errors.py

@@ -22,7 +22,7 @@ def test_unclosed_selection_list(env: JSONPathEnvironment) -> None:
 
 
 def test_function_missing_param(env: JSONPathEnvironment) -> None:
-    with pytest.raises(JSONPathTypeError):
+    with pytest.raises(JSONPathTypeError, match=r"length\(\) requires 1 argument"):
         env.compile("$[?(length()==1)]")