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

jsonpath/path.py

@@ -1,15 +1,13 @@
-# noqa: D100
+"""A compiled JSONPath ready to be applied to a JSON string or Python object."""
+
 from __future__ import annotations
 
 import itertools
 from typing import TYPE_CHECKING
-from typing import Any
 from typing import AsyncIterable
 from typing import Iterable
 from typing import List
-from typing import Mapping
 from typing import Optional
-from typing import Sequence
 from typing import Tuple
 from typing import TypeVar
 from typing import Union
@@ -18,15 +16,15 @@ from jsonpath._data import load_data
 from jsonpath.fluent_api import Query
 from jsonpath.match import FilterContextVars
 from jsonpath.match import JSONPathMatch
+from jsonpath.segments import JSONPathRecursiveDescentSegment
 from jsonpath.selectors import IndexSelector
-from jsonpath.selectors import ListSelector
-from jsonpath.selectors import PropertySelector
+from jsonpath.selectors import NameSelector
 
 if TYPE_CHECKING:
-    from io import IOBase
+    from jsonpath._types import JSONData
 
     from .env import JSONPathEnvironment
-    from .selectors import JSONPathSelector
+    from .segments import JSONPathSegment
 
 
 class JSONPath:
@@ -34,9 +32,9 @@ class JSONPath:
 
     Arguments:
         env: The `JSONPathEnvironment` this path is bound to.
-        selectors: An iterable of `JSONPathSelector` objects, as generated by
+        segments: An iterable of `JSONPathSegment` instances, as generated by
             a `Parser`.
-        fake_root: Indicates if target JSON values should be wrapped in a single-
+        pseudo_root: Indicates if target JSON values should be wrapped in a single-
             element array, so as to make the target root value selectable.
 
 
@@ -45,35 +43,30 @@ class JSONPath:
         selectors: The `JSONPathSelector` instances that make up this path.
     """
 
-    __slots__ = ("env", "fake_root", "selectors")
+    __slots__ = ("env", "pseudo_root", "segments")
 
     def __init__(
         self,
         *,
         env: JSONPathEnvironment,
-        selectors: Iterable[JSONPathSelector],
-        fake_root: bool = False,
+        segments: Iterable[JSONPathSegment],
+        pseudo_root: bool = False,
     ) -> None:
         self.env = env
-        self.selectors = tuple(selectors)
-        self.fake_root = fake_root
+        self.segments = tuple(segments)
+        self.pseudo_root = pseudo_root
 
     def __str__(self) -> str:
-        return self.env.root_token + "".join(
-            str(selector) for selector in self.selectors
-        )
+        return self.env.root_token + "".join(str(segment) for segment in self.segments)
 
     def __eq__(self, __value: object) -> bool:
-        return isinstance(__value, JSONPath) and self.selectors == __value.selectors
+        return isinstance(__value, JSONPath) and self.segments == __value.segments
 
     def __hash__(self) -> int:
-        return hash(self.selectors)
+        return hash(self.segments)
 
     def findall(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> List[object]:
         """Find all objects in `data` matching the given JSONPath `path`.
 
@@ -100,10 +93,7 @@ class JSONPath:
         ]
 
     def finditer(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Iterable[JSONPathMatch]:
         """Generate `JSONPathMatch` objects for each match.
 
@@ -125,27 +115,26 @@ class JSONPath:
                 an incompatible way.
         """
         _data = load_data(data)
+        path = self.env.pseudo_root_token if self.pseudo_root else self.env.root_token
+
         matches: Iterable[JSONPathMatch] = [
             JSONPathMatch(
                 filter_context=filter_context or {},
-                obj=[_data] if self.fake_root else _data,
+                obj=[_data] if self.pseudo_root else _data,
                 parent=None,
-                path=self.env.root_token,
+                path=path,
                 parts=(),
                 root=_data,
             )
         ]
 
-        for selector in self.selectors:
-            matches = selector.resolve(matches)
+        for segment in self.segments:
+            matches = segment.resolve(matches)
 
         return matches
 
     async def findall_async(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> List[object]:
         """An async version of `findall()`."""
         return [
@@ -156,36 +145,31 @@ class JSONPath:
         ]
 
     async def finditer_async(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> AsyncIterable[JSONPathMatch]:
         """An async version of `finditer()`."""
         _data = load_data(data)
+        path = self.env.pseudo_root_token if self.pseudo_root else self.env.root_token
 
         async def root_iter() -> AsyncIterable[JSONPathMatch]:
             yield self.env.match_class(
                 filter_context=filter_context or {},
-                obj=[_data] if self.fake_root else _data,
+                obj=[_data] if self.pseudo_root else _data,
                 parent=None,
-                path=self.env.root_token,
+                path=path,
                 parts=(),
                 root=_data,
             )
 
         matches: AsyncIterable[JSONPathMatch] = root_iter()
 
-        for selector in self.selectors:
-            matches = selector.resolve_async(matches)
+        for segment in self.segments:
+            matches = segment.resolve_async(matches)
 
         return matches
 
     def match(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Union[JSONPathMatch, None]:
         """Return a `JSONPathMatch` instance for the first object found in _data_.
 
@@ -212,10 +196,7 @@ class JSONPath:
             return None
 
     def query(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Query:
         """Return a `Query` iterator over matches found by applying this path to _data_.
 
@@ -237,20 +218,21 @@ class JSONPath:
 
     def empty(self) -> bool:
         """Return `True` if this path has no selectors."""
-        return not bool(self.selectors)
+        return not bool(self.segments)
 
     def singular_query(self) -> bool:
         """Return `True` if this JSONPath query is a singular query."""
-        for selector in self.selectors:
-            if isinstance(selector, (PropertySelector, IndexSelector)):
-                continue
-            if (
-                isinstance(selector, ListSelector)
-                and len(selector.items) == 1
-                and isinstance(selector.items[0], (PropertySelector, IndexSelector))
+        for segment in self.segments:
+            if isinstance(segment, JSONPathRecursiveDescentSegment):
+                return False
+
+            if len(segment.selectors) == 1 and isinstance(
+                segment.selectors[0], (NameSelector, IndexSelector)
             ):
                 continue
+
             return False
+
         return True
 
 
@@ -288,10 +270,7 @@ class CompoundJSONPath:
         return hash((self.path, self.paths))
 
     def findall(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> List[object]:
         """Find all objects in `data` matching the given JSONPath `path`.
 
@@ -326,10 +305,7 @@ class CompoundJSONPath:
         return objs
 
     def finditer(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Iterable[JSONPathMatch]:
         """Generate `JSONPathMatch` objects for each match.
 
@@ -364,10 +340,7 @@ class CompoundJSONPath:
         return matches
 
     def match(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Union[JSONPathMatch, None]:
         """Return a `JSONPathMatch` instance for the first object found in _data_.
 
@@ -394,10 +367,7 @@ class CompoundJSONPath:
             return None
 
     async def findall_async(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> List[object]:
         """An async version of `findall()`."""
         objs = await self.path.findall_async(data, filter_context=filter_context)
@@ -413,10 +383,7 @@ class CompoundJSONPath:
         return objs
 
     async def finditer_async(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> AsyncIterable[JSONPathMatch]:
         """An async version of `finditer()`."""
         matches = await self.path.finditer_async(data, filter_context=filter_context)
@@ -433,10 +400,7 @@ class CompoundJSONPath:
         return matches
 
     def query(
-        self,
-        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
-        *,
-        filter_context: Optional[FilterContextVars] = None,
+        self, data: JSONData, *, filter_context: Optional[FilterContextVars] = None
     ) -> Query:
         """Return a `Query` iterator over matches found by applying this path to _data_.
 

jsonpath/pointer.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:
 
 class _Undefined:
     def __str__(self) -> str:
-        return "<jsonpath.pointer.UNDEFINED>"
+        return "<jsonpath.pointer.UNDEFINED>"  # pragma: no cover
 
 
 UNDEFINED = _Undefined()
@@ -115,59 +115,83 @@ class JSONPointer:
         try:
             index = int(s)
             if index < self.min_int_index or index > self.max_int_index:
-                raise JSONPointerIndexError("index out of range")
+                raise JSONPointerError("index out of range")
             return index
         except ValueError:
             return s
 
-    def _getitem(self, obj: Any, key: Any) -> Any:  # noqa: PLR0912
+    def _getitem(self, obj: Any, key: Any) -> Any:
         try:
+            # Handle the most common cases. A mapping with a string key, or a sequence
+            # with an integer index.
+            #
+            # Note that `obj` does not have to be a Mapping or Sequence here. Any object
+            # implementing `__getitem__` will do.
             return getitem(obj, key)
         except KeyError as err:
-            # Try a string repr of the index-like item as a mapping key.
-            if isinstance(key, int):
-                try:
-                    return getitem(obj, str(key))
-                except KeyError:
-                    raise JSONPointerKeyError(key) from err
-            # Handle non-standard keys/property selector/pointer.
-            if (
-                isinstance(key, str)
-                and isinstance(obj, Mapping)
-                and key.startswith((self.keys_selector, "#"))
-                and key[1:] in obj
-            ):
-                return key[1:]
-            # Handle non-standard index/property pointer (`#`)
-            raise JSONPointerKeyError(key) from err
+            return self._handle_key_error(obj, key, err)
         except TypeError as err:
-            if isinstance(obj, Sequence) and not isinstance(obj, str):
-                if key == "-":
-                    # "-" is a valid index when appending to a JSON array
-                    # with JSON Patch, but not when resolving a JSON Pointer.
-                    raise JSONPointerIndexError("index out of range") from None
-                # Handle non-standard index pointer.
-                if isinstance(key, str) and key.startswith("#"):
-                    _index = int(key[1:])
-                    if _index >= len(obj):
-                        raise JSONPointerIndexError(
-                            f"index out of range: {_index}"
-                        ) from err
-                    return _index
-                # Try int index. Reject non-zero ints that start with a zero.
-                if isinstance(key, str):
-                    index = self._index(key)
-                    if isinstance(index, int):
-                        try:
-                            return getitem(obj, int(key))
-                        except IndexError as index_err:
-                            raise JSONPointerIndexError(
-                                f"index out of range: {key}"
-                            ) from index_err
-            raise JSONPointerTypeError(f"{key}: {err}") from err
+            return self._handle_type_error(obj, key, err)
         except IndexError as err:
             raise JSONPointerIndexError(f"index out of range: {key}") from err
 
+    def _handle_key_error(self, obj: Any, key: Any, err: Exception) -> object:
+        if isinstance(key, int):
+            # Try a string repr of the index-like item as a mapping key.
+            return self._getitem(obj, str(key))
+
+        # Handle non-standard key/property selector/pointer.
+        #
+        # For the benefit of `RelativeJSONPointer.to()` and `JSONPathMatch.pointer()`,
+        # treat keys starting with a `#` or `~` as a "key pointer". If `key[1:]` is a
+        # key in `obj`, return the key.
+        #
+        # Note that if a key with a leading `#`/`~` exists in `obj`, it will have been
+        # handled by `_getitem`.
+        if (
+            isinstance(key, str)
+            and isinstance(obj, Mapping)
+            and key.startswith((self.keys_selector, "#"))
+            and key[1:] in obj
+        ):
+            return key[1:]
+
+        raise JSONPointerKeyError(key) from err
+
+    def _handle_type_error(self, obj: Any, key: Any, err: Exception) -> object:
+        if (
+            isinstance(obj, str)
+            or not isinstance(obj, Sequence)
+            or not isinstance(key, str)
+        ):
+            raise JSONPointerTypeError(f"{key}: {err}") from err
+
+        # `obj` is array-like
+        # `key` is a string
+
+        if key == "-":
+            # "-" is a valid index when appending to a JSON array with JSON Patch, but
+            # not when resolving a JSON Pointer.
+            raise JSONPointerIndexError("index out of range") from None
+
+        # Handle non-standard index pointer.
+        #
+        # For the benefit of `RelativeJSONPointer.to()`, treat keys starting with a `#`
+        # and followed by a valid index as an "index pointer". If `int(key[1:])` is
+        # less than `len(obj)`, return the index.
+        if re.match(r"#[1-9]\d*", key):
+            _index = int(key[1:])
+            if _index >= len(obj):
+                raise JSONPointerIndexError(f"index out of range: {_index}") from err
+            return _index
+
+        # Try int index. Reject non-zero ints that start with a zero.
+        index = self._index(key)
+        if isinstance(index, int):
+            return self._getitem(obj, index)
+
+        raise JSONPointerTypeError(f"{key}: {err}") from err
+
     def resolve(
         self,
         data: Union[str, IOBase, Sequence[object], Mapping[str, object]],
@@ -263,7 +287,7 @@ class JSONPointer:
             pointer = cls._encode(match.parts)
         else:
             # This should not happen, unless the JSONPathMatch has been tampered with.
-            pointer = ""
+            pointer = ""  # pragma: no cover
 
         return cls(
             pointer,
@@ -328,10 +352,10 @@ class JSONPointer:
         return isinstance(other, JSONPointer) and self.parts == other.parts
 
     def __hash__(self) -> int:
-        return hash(self.parts)
+        return hash(self.parts)  # pragma: no cover
 
     def __repr__(self) -> str:
-        return f"JSONPointer({self._s!r})"
+        return f"JSONPointer({self._s!r})"  # pragma: no cover
 
     def exists(
         self, data: Union[str, IOBase, Sequence[object], Mapping[str, object]]
@@ -486,7 +510,7 @@ class RelativeJSONPointer:
         return isinstance(__value, RelativeJSONPointer) and str(self) == str(__value)
 
     def __hash__(self) -> int:
-        return hash((self.origin, self.index, self.pointer))
+        return hash((self.origin, self.index, self.pointer))  # pragma: no cover
 
     def _parse(
         self,

jsonpath/segments.py

@@ -0,0 +1,131 @@
+"""JSONPath child and descendant segment definitions."""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from typing import TYPE_CHECKING
+from typing import AsyncIterable
+from typing import Iterable
+from typing import Mapping
+from typing import Sequence
+from typing import Tuple
+
+from .exceptions import JSONPathRecursionError
+
+if TYPE_CHECKING:
+    from .env import JSONPathEnvironment
+    from .match import JSONPathMatch
+    from .selectors import JSONPathSelector
+    from .token import Token
+
+
+class JSONPathSegment(ABC):
+    """Base class for all JSONPath segments."""
+
+    __slots__ = ("env", "token", "selectors")
+
+    def __init__(
+        self,
+        *,
+        env: JSONPathEnvironment,
+        token: Token,
+        selectors: Tuple[JSONPathSelector, ...],
+    ) -> None:
+        self.env = env
+        self.token = token
+        self.selectors = selectors
+
+    @abstractmethod
+    def resolve(self, nodes: Iterable[JSONPathMatch]) -> Iterable[JSONPathMatch]:
+        """Apply this segment to each `JSONPathMatch` in _nodes_."""
+
+    @abstractmethod
+    def resolve_async(
+        self, nodes: AsyncIterable[JSONPathMatch]
+    ) -> AsyncIterable[JSONPathMatch]:
+        """An async version of `resolve`."""
+
+
+class JSONPathChildSegment(JSONPathSegment):
+    """The JSONPath child selection segment."""
+
+    def resolve(self, nodes: Iterable[JSONPathMatch]) -> Iterable[JSONPathMatch]:
+        """Select children of each node in _nodes_."""
+        for node in nodes:
+            for selector in self.selectors:
+                yield from selector.resolve(node)
+
+    async def resolve_async(
+        self, nodes: AsyncIterable[JSONPathMatch]
+    ) -> AsyncIterable[JSONPathMatch]:
+        """An async version of `resolve`."""
+        async for node in nodes:
+            for selector in self.selectors:
+                async for match in selector.resolve_async(node):
+                    yield match
+
+    def __str__(self) -> str:
+        return f"[{', '.join(str(itm) for itm in self.selectors)}]"
+
+    def __eq__(self, __value: object) -> bool:
+        return (
+            isinstance(__value, JSONPathChildSegment)
+            and self.selectors == __value.selectors
+            and self.token == __value.token
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.selectors, self.token))
+
+
+class JSONPathRecursiveDescentSegment(JSONPathSegment):
+    """The JSONPath recursive descent segment."""
+
+    def resolve(self, nodes: Iterable[JSONPathMatch]) -> Iterable[JSONPathMatch]:
+        """Select descendants of each node in _nodes_."""
+        for node in nodes:
+            for _node in self._visit(node):
+                for selector in self.selectors:
+                    yield from selector.resolve(_node)
+
+    async def resolve_async(
+        self, nodes: AsyncIterable[JSONPathMatch]
+    ) -> AsyncIterable[JSONPathMatch]:
+        """An async version of `resolve`."""
+        async for node in nodes:
+            for _node in self._visit(node):
+                for selector in self.selectors:
+                    async for match in selector.resolve_async(_node):
+                        yield match
+
+    def _visit(self, node: JSONPathMatch, depth: int = 1) -> Iterable[JSONPathMatch]:
+        """Depth-first, pre-order node traversal."""
+        if depth > self.env.max_recursion_depth:
+            raise JSONPathRecursionError("recursion limit exceeded", token=self.token)
+
+        yield node
+
+        if isinstance(node.obj, Mapping):
+            for name, val in node.obj.items():
+                if isinstance(val, (Mapping, Sequence)):
+                    _node = node.new_child(val, name)
+                    yield from self._visit(_node, depth + 1)
+        elif isinstance(node.obj, Sequence) and not isinstance(node.obj, str):
+            for i, item in enumerate(node.obj):
+                if isinstance(item, (Mapping, Sequence)):
+                    _node = node.new_child(item, i)
+                    yield from self._visit(_node, depth + 1)
+
+    def __str__(self) -> str:
+        return f"..[{', '.join(str(itm) for itm in self.selectors)}]"
+
+    def __eq__(self, __value: object) -> bool:
+        return (
+            isinstance(__value, JSONPathRecursiveDescentSegment)
+            and self.selectors == __value.selectors
+            and self.token == __value.token
+        )
+
+    def __hash__(self) -> int:
+        return hash(("..", self.selectors, self.token))