python-jsonpath 1.3.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

jsonpath/env.py

@@ -2,7 +2,20 @@
 
 from __future__ import annotations
 
-import re
+try:
+    import regex  # noqa: F401
+
+    REGEX_AVAILABLE = True
+except ImportError:
+    REGEX_AVAILABLE = False
+
+try:
+    import iregexp_check  # noqa: F401
+
+    IREGEXP_AVAILABLE = True
+except ImportError:
+    IREGEXP_AVAILABLE = False
+
 from decimal import Decimal
 from operator import getitem
 from typing import TYPE_CHECKING
@@ -24,10 +37,10 @@ from .exceptions import JSONPathSyntaxError
 from .exceptions import JSONPathTypeError
 from .filter import UNDEFINED
 from .filter import VALUE_TYPE_EXPRESSIONS
-from .filter import FilterExpression
+from .filter import BaseExpression
+from .filter import FilterQuery
 from .filter import FunctionExtension
 from .filter import InfixExpression
-from .filter import Path
 from .fluent_api import Query
 from .function_extensions import ExpressionType
 from .function_extensions import FilterFunction
@@ -40,14 +53,13 @@ from .path import CompoundJSONPath
 from .path import JSONPath
 from .stream import TokenStream
 from .token import TOKEN_EOF
-from .token import TOKEN_FAKE_ROOT
 from .token import TOKEN_INTERSECTION
+from .token import TOKEN_PSEUDO_ROOT
 from .token import TOKEN_UNION
 from .token import Token
 
 if TYPE_CHECKING:
-    from io import IOBase
-
+    from ._types import JSONData
     from .match import FilterContextVars
 
 
@@ -88,12 +100,14 @@ class JSONPathEnvironment:
             well-typedness as compile time.
 
             **New in version 0.10.0**
+        strict: When `True`, follow RFC 9535 strictly.
+            **New in version 2.0.0**
 
     ## Class attributes
 
     Attributes:
-        fake_root_token (str): The pattern used to select a "fake" root node, one level
-            above the real root node.
+        pseudo_root_token (str): The pattern used to select a "fake" root node, one
+            level above the real root node.
         filter_context_token (str): The pattern used to select extra filter context
             data. Defaults to `"_"`.
         intersection_token (str): The pattern used as the intersection operator.
@@ -102,11 +116,16 @@ class JSONPathEnvironment:
             filtering a mapping or sequence. Defaults to `"#"`.
         keys_selector_token (str): The pattern used as the "keys" selector. Defaults to
             `"~"`.
+        keys_filter_token (str): The pattern used as the "keys filter" selector.
+            Defaults to `"~?"`.
         lexer_class: The lexer to use when tokenizing path strings.
         max_int_index (int): The maximum integer allowed when selecting array items by
             index. Defaults to `(2**53) - 1`.
         min_int_index (int): The minimum integer allowed when selecting array items by
             index. Defaults to `-(2**53) + 1`.
+        max_recursion_depth (int): The maximum number of dict/objects and/or arrays/
+            lists the recursive descent selector can visit before a
+            `JSONPathRecursionError` is thrown.
         parser_class: The parser to use when parsing tokens from the lexer.
         root_token (str): The pattern used to select the root node in a JSON document.
             Defaults to `"$"`.
@@ -115,19 +134,21 @@ class JSONPathEnvironment:
         union_token (str): The pattern used as the union operator. Defaults to `"|"`.
     """
 
-    # These should be unescaped strings. `re.escape` will be called
-    # on them automatically when compiling lexer rules.
-    fake_root_token = "^"
+    # These should be unescaped strings. `re.escape` will be called on them
+    # automatically when compiling lexer rules.
+    pseudo_root_token = "^"
     filter_context_token = "_"
     intersection_token = "&"
     key_token = "#"
     keys_selector_token = "~"
+    keys_filter_token = "~?"
     root_token = "$"
     self_token = "@"
     union_token = "|"
 
     max_int_index = (2**53) - 1
     min_int_index = -(2**53) + 1
+    max_recursion_depth = 100
 
     # Override these to customize path tokenization and parsing.
     lexer_class: Type[Lexer] = Lexer
@@ -140,6 +161,7 @@ class JSONPathEnvironment:
         filter_caching: bool = True,
         unicode_escape: bool = True,
         well_typed: bool = True,
+        strict: bool = False,
     ) -> None:
         self.filter_caching: bool = filter_caching
         """Enable or disable filter expression caching."""
@@ -151,6 +173,24 @@ class JSONPathEnvironment:
         self.well_typed: bool = well_typed
         """Control well-typedness checks on filter function expressions."""
 
+        self.strict: bool = strict
+        """When `True`, follow RFC 9535 strictly.
+        
+        This includes things like enforcing a leading root identifier and
+        ensuring there's no leading or trailing whitespace when parsing a
+        JSONPath query.
+        """
+
+        self.regex_available: bool = REGEX_AVAILABLE
+        """When `True`, the third party `regex` package is available."""
+
+        self.iregexp_available: bool = IREGEXP_AVAILABLE
+        """When `True`, the iregexp_check package is available.
+        
+        iregexp_check will be used to validate regular expressions against RFC 9485,
+        if available.
+        """
+
         self.lexer: Lexer = self.lexer_class(env=self)
         """The lexer bound to this environment."""
 
@@ -180,46 +220,53 @@ class JSONPathEnvironment:
         """
         tokens = self.lexer.tokenize(path)
         stream = TokenStream(tokens)
-        fake_root = stream.current.kind == TOKEN_FAKE_ROOT
+        pseudo_root = stream.current().kind == TOKEN_PSEUDO_ROOT
         _path: Union[JSONPath, CompoundJSONPath] = JSONPath(
-            env=self, selectors=self.parser.parse(stream), fake_root=fake_root
+            env=self, segments=self.parser.parse(stream), pseudo_root=pseudo_root
         )
 
-        if stream.current.kind != TOKEN_EOF:
+        if stream.skip_whitespace() and self.strict:
+            raise JSONPathSyntaxError(
+                "unexpected whitespace", token=stream.tokens[stream.pos - 1]
+            )
+
+        if stream.current().kind != TOKEN_EOF:
             _path = CompoundJSONPath(env=self, path=_path)
-            while stream.current.kind != TOKEN_EOF:
-                if stream.peek.kind == TOKEN_EOF:
+            while stream.current().kind != TOKEN_EOF:
+                if stream.peek().kind == TOKEN_EOF:
                     # trailing union or intersection
                     raise JSONPathSyntaxError(
-                        f"expected a path after {stream.current.value!r}",
-                        token=stream.current,
+                        f"expected a path after {stream.current().value!r}",
+                        token=stream.current(),
                     )
 
-                if stream.current.kind == TOKEN_UNION:
-                    stream.next_token()
-                    fake_root = stream.current.kind == TOKEN_FAKE_ROOT
+                if stream.current().kind == TOKEN_UNION:
+                    stream.next()
+                    stream.skip_whitespace()
+                    pseudo_root = stream.current().kind == TOKEN_PSEUDO_ROOT
                     _path = _path.union(
                         JSONPath(
                             env=self,
-                            selectors=self.parser.parse(stream),
-                            fake_root=fake_root,
+                            segments=self.parser.parse(stream),
+                            pseudo_root=pseudo_root,
                         )
                     )
-                elif stream.current.kind == TOKEN_INTERSECTION:
-                    stream.next_token()
-                    fake_root = stream.current.kind == TOKEN_FAKE_ROOT
+                elif stream.current().kind == TOKEN_INTERSECTION:
+                    stream.next()
+                    stream.skip_whitespace()
+                    pseudo_root = stream.current().kind == TOKEN_PSEUDO_ROOT
                     _path = _path.intersection(
                         JSONPath(
                             env=self,
-                            selectors=self.parser.parse(stream),
-                            fake_root=fake_root,
+                            segments=self.parser.parse(stream),
+                            pseudo_root=pseudo_root,
                         )
                     )
                 else:  # pragma: no cover
                     # Parser.parse catches this too
                     raise JSONPathSyntaxError(  # noqa: TRY003
-                        f"unexpected token {stream.current.value!r}",
-                        token=stream.current,
+                        f"unexpected token {stream.current().value!r}",
+                        token=stream.current(),
                     )
 
         return _path
@@ -227,7 +274,7 @@ class JSONPathEnvironment:
     def findall(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
         *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> List[object]:
@@ -257,7 +304,7 @@ class JSONPathEnvironment:
     def finditer(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
         *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> Iterable[JSONPathMatch]:
@@ -286,7 +333,7 @@ class JSONPathEnvironment:
     def match(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
         *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> Union[JSONPathMatch, None]:
@@ -315,7 +362,8 @@ class JSONPathEnvironment:
     def query(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
+        *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> Query:
         """Return a `Query` iterator over matches found by applying _path_ to _data_.
@@ -374,7 +422,7 @@ class JSONPathEnvironment:
     async def findall_async(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
         *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> List[object]:
@@ -386,7 +434,7 @@ class JSONPathEnvironment:
     async def finditer_async(
         self,
         path: str,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        data: JSONData,
         *,
         filter_context: Optional[FilterContextVars] = None,
     ) -> AsyncIterable[JSONPathMatch]:
@@ -402,10 +450,13 @@ class JSONPathEnvironment:
         self.function_extensions["match"] = function_extensions.Match()
         self.function_extensions["search"] = function_extensions.Search()
         self.function_extensions["value"] = function_extensions.Value()
-        self.function_extensions["isinstance"] = function_extensions.IsInstance()
-        self.function_extensions["is"] = self.function_extensions["isinstance"]
-        self.function_extensions["typeof"] = function_extensions.TypeOf()
-        self.function_extensions["type"] = self.function_extensions["typeof"]
+
+        if not self.strict:
+            self.function_extensions["isinstance"] = function_extensions.IsInstance()
+            self.function_extensions["is"] = self.function_extensions["isinstance"]
+            self.function_extensions["typeof"] = function_extensions.TypeOf()
+            self.function_extensions["type"] = self.function_extensions["typeof"]
+            self.function_extensions["startswith"] = function_extensions.StartsWith()
 
     def validate_function_extension_signature(
         self, token: Token, args: List[Any]
@@ -440,13 +491,14 @@ class JSONPathEnvironment:
         self,
         token: Token,
         func: FilterFunction,
-        args: List[FilterExpression],
+        args: List[BaseExpression],
     ) -> None:
         """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,
             )
 
@@ -456,7 +508,7 @@ class JSONPathEnvironment:
             if typ == ExpressionType.VALUE:
                 if not (
                     isinstance(arg, VALUE_TYPE_EXPRESSIONS)
-                    or (isinstance(arg, Path) and arg.path.singular_query())
+                    or (isinstance(arg, FilterQuery) and arg.path.singular_query())
                     or (self._function_return_type(arg) == ExpressionType.VALUE)
                 ):
                     raise JSONPathTypeError(
@@ -464,13 +516,13 @@ class JSONPathEnvironment:
                         token=token,
                     )
             elif typ == ExpressionType.LOGICAL:
-                if not isinstance(arg, (Path, InfixExpression)):
+                if not isinstance(arg, (FilterQuery, InfixExpression)):
                     raise JSONPathTypeError(
                         f"{token.value}() argument {idx} must be of LogicalType",
                         token=token,
                     )
             elif typ == ExpressionType.NODES and not (
-                isinstance(arg, Path)
+                isinstance(arg, FilterQuery)
                 or self._function_return_type(arg) == ExpressionType.NODES
             ):
                 raise JSONPathTypeError(
@@ -478,7 +530,7 @@ class JSONPathEnvironment:
                     token=token,
                 )
 
-    def _function_return_type(self, expr: FilterExpression) -> Optional[ExpressionType]:
+    def _function_return_type(self, expr: BaseExpression) -> Optional[ExpressionType]:
         """Return the type returned from a filter function.
 
         If _expr_ is not a `FunctionExtension` or the registered function definition is
@@ -568,7 +620,8 @@ class JSONPathEnvironment:
             return left in right
         if operator == "contains" and isinstance(left, (Mapping, Sequence)):
             return right in left
-        if operator == "=~" and isinstance(right, re.Pattern) and isinstance(left, str):
+        if operator == "=~" and hasattr(right, "fullmatch") and isinstance(left, str):
+            # Right should be a regex.Pattern or an re.Pattern.
             return bool(right.fullmatch(left))
         return False
 

jsonpath/exceptions.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 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 @@ class JSONPathError(Exception):
         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):
@@ -77,6 +135,19 @@ class JSONPathNameError(JSONPathError):
         self.token = token
 
 
+class JSONPathRecursionError(JSONPathError):
+    """An exception raised when the maximum recursion depth is reached.
+
+    Arguments:
+        args: Arguments passed to `Exception`.
+        token: The token that caused the error.
+    """
+
+    def __init__(self, *args: object, token: Token) -> None:
+        super().__init__(*args)
+        self.token = token
+
+
 class JSONPointerError(Exception):
     """Base class for all JSON Pointer errors."""