docs: add query iterator guide

Author: jg-rp

docs/query.md

@@ -0,0 +1,61 @@
+# Query Iterators
+
+**_New in version 1.1.0_**
+
+In addition to [`findall()`](api.md#jsonpath.JSONPathEnvironment.findall) and [`finditer()`](api.md#jsonpath.JSONPathEnvironment.finditer), covered in the [quick start guide](./quickstart.md), Python JSONPath offers a fluent _query_ iterator interface.
+
+[`Query`](api.md#jsonpath.Query) objects provide chainable methods for manipulating a [`JSONPathMatch`](api.md#jsonpath.JSONPathMatch) iterator, just like you'd get from `finditer()`. Obtain a `Query` object using the package-level `query()` function or [`JSONPathEnvironment.query()`](api.md#jsonpath.JSONPathEnvironment.query).
+
+This example uses the query API to skip the first 5 matches, limit the total number of matches to 10, and get the value associated with each match.
+
+```python
+from jsonpath import query
+
+# data = ...
+
+values = (
+    query("$.some[[email protected]]", data)
+    .skip(5)
+    .limit(10)
+    .values()
+)
+
+for value in values:
+    # ...
+```
+
+## 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.
+
+| Method          | Aliases                 | Description                                        |
+| --------------- | ----------------------- | -------------------------------------------------- |
+| `skip(n: int)`  | `drop`                  | Drop up to _n_ matches from the iterator.          |
+| `limit(n: int)` | `head`, `take`, `first` | Yield at most _n_ matches from the iterator.       |
+| `tail(n: int)`  | `last`                  | Drop matches from the iterator up to the last _n_. |
+
+## Terminal methods
+
+These are terminal methods of the `Query` class. They can not be chained.
+
+| Method        | Aliases | Description                                                                                 |
+| ------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `values()`    |         | Return an iterable of objects, one for each match in the iterable.                          |
+| `locations()` |         | Return an iterable of normalized paths, one for each match in the iterable.                 |
+| `items()`     |         | Return an iterable of (object, normalized path) tuples, one for each match in the iterable. |
+| `pointers()`  |         | Return an iterable of `JSONPointer` instances, one for each match in the iterable.          |
+| `first_one()` | `one`   | Return the first `JSONPathMatch`, or `None` if there were no matches.                       |
+| `last_one()`  |         | Return the last `JSONPathMatch`, or `None` if there were no matches.                        |
+
+## Tee
+
+And finally there's `tee()`, which creates multiple independent queries from one query iterator. It is not safe to use the initial `Query` instance after calling `tee()`.
+
+```python
+from jsonpath import query
+
+it1, it2 = query("$.some[[email protected]]", data).tee()
+
+head = it1.head(10) # first 10 matches
+tail = it2.tail(10) # last 10 matches
+```

docs/quickstart.md

@@ -294,7 +294,7 @@ print(data)  # {'some': {'other': 'thing', 'foo': {'bar': [1], 'else': 'thing'}}
 
 ## What's Next?
 
-Read about user-defined filter functions at [Function Extensions](advanced.md#function-extensions), or see how to make extra data available to filters with [Extra Filter Context](advanced.md#extra-filter-context).
+Read about the [Query Iterators](query.md) API or [user-defined filter functions](advanced.md#function-extensions). Also see how to make extra data available to filters with [Extra Filter Context](advanced.md#extra-filter-context).
 
 `findall()`, `finditer()` and `compile()` are shortcuts that use the default[`JSONPathEnvironment`](api.md#jsonpath.JSONPathEnvironment). `jsonpath.findall(path, data)` is equivalent to:
 

jsonpath/__init__.py

@@ -74,6 +74,4 @@
 finditer = DEFAULT_ENV.finditer
 finditer_async = DEFAULT_ENV.finditer_async
 match = DEFAULT_ENV.match
-first = DEFAULT_ENV.match
 query = DEFAULT_ENV.query
-find = DEFAULT_ENV.query

jsonpath/fluent_api.py

@@ -130,6 +130,8 @@ def items(self) -> Iterable[Tuple[str, object]]:
         """Return an iterable of (object, normalized path) tuples for each match."""
         return ((m.path, m.obj) for m in self._it)
 
+    # TODO: def pointers
+
     def first_one(self) -> Optional[JSONPathMatch]:
         """Return the first `JSONPathMatch` or `None` if there were no matches."""
         try:
@@ -152,7 +154,7 @@ def last_one(self) -> Optional[JSONPathMatch]:
             return None
 
     def tee(self, n: int = 2) -> Tuple[Query, ...]:
-        """Return _n_ independent queries by teeing this query's match iterable.
+        """Return _n_ independent queries by teeing this query's iterator.
 
         It is not safe to use a `Query` instance after calling `tee()`.
         """

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
   - Guides:
       - JSONPath Syntax: "syntax.md"
       - Filter Functions: "functions.md"
+      - Query Iterators: "query.md"
       - JSON Pointers: "pointers.md"
       - Async Support: "async.md"
   - API Reference: