Add pointers to the fluent API

Author: jg-rp

docs/query.md

@@ -24,6 +24,23 @@ for value in values:
     # ...
 ```
 
+`Query` objects are iterable and can only be iterated once. Pass the query to `list()` (or other sequence) to get a list of results that can be iterated multiple times or otherwise manipulated.
+
+```python
+from jsonpath import query
+
+# data = ...
+
+values = list(
+    query("$.some[[email protected]]", data)
+    .skip(5)
+    .limit(10)
+    .values()
+)
+
+print(values[1])
+```
+
 ## Chainable methods
 
 The following `Query` methods all return `self` (the same `Query` instance), so method calls can be chained to further manipulate the underlying iterator.

jsonpath/fluent_api.py

@@ -11,6 +11,7 @@
 
 if TYPE_CHECKING:
     from jsonpath import JSONPathMatch
+    from jsonpath import JSONPointer
 
 
 class Query:
@@ -123,14 +124,16 @@ def values(self) -> Iterable[object]:
         return (m.obj for m in self._it)
 
     def locations(self) -> Iterable[str]:
-        """Return an iterable of normalized paths for each match."""
+        """Return an iterable of normalized paths, one for each match."""
         return (m.path for m in self._it)
 
     def items(self) -> Iterable[Tuple[str, object]]:
-        """Return an iterable of (object, normalized path) tuples for each match."""
+        """Return an iterable of (object, path) tuples, one for each match."""
         return ((m.path, m.obj) for m in self._it)
 
-    # TODO: def pointers
+    def pointers(self) -> Iterable[JSONPointer]:
+        """Return an iterable of JSONPointers, one for each match."""
+        return (m.pointer() for m in self._it)
 
     def first_one(self) -> Optional[JSONPathMatch]:
         """Return the first `JSONPathMatch` or `None` if there were no matches."""

tests/test_fluent_api.py

@@ -2,6 +2,7 @@
 import pytest
 
 from jsonpath import JSONPathMatch
+from jsonpath import JSONPointer
 from jsonpath import query
 
 
@@ -240,3 +241,10 @@ def test_query_tee() -> None:
     rv2 = it2.skip(2).one()
     assert rv2 is not None
     assert rv2.value == 2  # noqa: PLR2004
+
+
+def test_query_pointers() -> None:
+    """Test that we can get pointers from a query."""
+    pointers = list(query("$.some.*", {"some": [0, 1, 2, 3]}).pointers())
+    assert len(pointers) == 4  # noqa: PLR2004
+    assert pointers[0] == JSONPointer("/some/0")