Add parent, children and parts to JSONPathMatch.

Author: jg-rp

CHANGELOG.md

@@ -7,11 +7,16 @@
 - Added support for function extensions.
 - Added the built-in `length()` function.
 - Added the built-in `count()` function. `count()` is an alias for `length()`
-- Added the built-in `keys()` function (non-standard).
 - Support filters without parentheses.
 - Adhere to IETF JSONPath draft escaping in quoted property selectors.
 - Handle UTF-16 surrogate pairs in quoted property selectors.
 
+**Features**
+
+- Added the built-in `keys()` function.
+- Added `parent` and `children` properties to `JSONPathMatch`. Now we can traverse the "document tree" after finding matches.
+- Added a `parts` property to `JSONPathMatch`. `parts` is a tuple of `int`s, `slice`s and `str`s that can be used with `JSONPathEnvironment.getitem()` to get the matched object from the original data structure, or equivalent data structures. It is the keys, indices and slices that make up a concrete path.
+
 ## Version 0.2.0
 
 **Fixes**

jsonpath/match.py

@@ -1,38 +1,55 @@
 """The JSONPath match object, as returned from :meth:`JSONPath.finditer`."""
+from __future__ import annotations
 
 from typing import Any
+from typing import List
 from typing import Mapping
+from typing import Optional
 from typing import Sequence
+from typing import Tuple
 from typing import Union
 
 FilterContextVars = Mapping[str, Any]
-
-# TODO: store path as tuple of things
-# TODO: store reference to parent
-# TODO: store list of children
+PathPart = Union[int, slice, str]
 
 
 class JSONPathMatch:
     """Bind a matched object to its path."""
 
-    __slots__ = ("_filter_context", "obj", "path", "root")
+    __slots__ = (
+        "_filter_context",
+        "children",
+        "obj",
+        "parent",
+        "parts",
+        "path",
+        "root",
+    )
 
     def __init__(
         self,
         *,
         filter_context: FilterContextVars,
         obj: object,
+        parent: Optional[JSONPathMatch],
         path: str,
+        parts: Tuple[PathPart, ...],
         root: Union[Sequence[Any], Mapping[str, Any]],
     ) -> None:
-        self.path = path
+        self._filter_context = filter_context
+        self.children: List[JSONPathMatch] = []
         self.obj = obj
+        self.parent = parent
+        self.parts = parts
+        self.path = path
         self.root = root
-        self._filter_context = filter_context
 
     def __str__(self) -> str:
         return f"{_truncate(str(self.obj), 5)!r} @ {_truncate(self.path, 5)}"
 
+    def add_child(self, *children: JSONPathMatch) -> None:
+        self.children.extend(children)
+
     def filter_context(self) -> FilterContextVars:
         """"""
         return self._filter_context

jsonpath/path.py

@@ -67,10 +67,12 @@ def finditer(
 
         matches: Iterable[JSONPathMatch] = [
             JSONPathMatch(
-                path=self.env.root_token,
+                filter_context=filter_context or {},
                 obj=data,
+                parent=None,
+                path=self.env.root_token,
+                parts=(),
                 root=data,
-                filter_context=filter_context or {},
             )
         ]
 
@@ -108,10 +110,12 @@ async def finditer_async(
 
         async def root_iter() -> AsyncIterable[JSONPathMatch]:
             yield JSONPathMatch(
-                path=self.env.root_token,
+                filter_context=filter_context or {},
                 obj=data,
+                parent=None,
+                path=self.env.root_token,
+                parts=(),
                 root=data,
-                filter_context=filter_context or {},
             )
 
         matches: AsyncIterable[JSONPathMatch] = root_iter()