Merge pull request #53 from jg-rp/fluent-iapi

Add a fluent API for JSONPathMatch iterators.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Python JSONPath Change Log
 
+## Version 1.1.0 (unreleased)
+
+**Features**
+
+- Added the "query API", a fluent, chainable API for manipulating `JSONPathMatch` iterators.
+
 ## Version 1.0.0
 
 [RFC 9535](https://datatracker.ietf.org/doc/html/rfc9535) (JSONPath: Query Expressions for JSON) is now out, replacing the [draft IETF JSONPath base](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-21).

docs/api.md

@@ -11,6 +11,9 @@
 ::: jsonpath.CompoundJSONPath
  handler: python
 
+::: jsonpath.Query
+ handler: python
+
 ::: jsonpath.function_extensions.FilterFunction
  handler: python
 

docs/query.md

@@ -0,0 +1,94 @@
+# 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 five matches, limit the total number of matches to ten, 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:
+ # ...
+```
+
+`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.
+
+| Method | Aliases | Description |
+| --------------- | --------------- | -------------------------------------------------- |
+| `skip(n: int)` | `drop` | Drop up to _n_ matches from the iterator. |
+| `limit(n: int)` | `head`, `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. |
+
+## Take
+
+[`Query.take(self, n: int)`](api.md#jsonpath.Query.take) returns a new `Query` instance, iterating over the next _n_ matches. It leaves the existing query in a safe state, ready to resume iteration of remaining matches.
+
+```python
+from jsonpath import query
+
+it = query("$.some.*", {"some": [0, 1, 2, 3]})
+
+for match in it.take(2):
+ print(match.value) # 0, 1
+
+for value in it.values():
+ print(value) # 2, 3
+```
+
+## 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

@@ -17,6 +17,7 @@
 from .exceptions import RelativeJSONPointerIndexError
 from .exceptions import RelativeJSONPointerSyntaxError
 from .filter import UNDEFINED
+from .fluent_api import Query
 from .lex import Lexer
 from .match import JSONPathMatch
 from .parse import Parser
@@ -30,10 +31,12 @@
 __all__ = (
  "compile",
  "CompoundJSONPath",
+ "find",
  "findall_async",
  "findall",
  "finditer_async",
  "finditer",
+ "first",
  "JSONPatch",
  "JSONPath",
  "JSONPathEnvironment",
@@ -52,6 +55,8 @@
  "Lexer",
  "match",
  "Parser",
+ "query",
+ "Query",
  "RelativeJSONPointer",
  "RelativeJSONPointerError",
  "RelativeJSONPointerIndexError",
@@ -69,3 +74,4 @@
 finditer = DEFAULT_ENV.finditer
 finditer_async = DEFAULT_ENV.finditer_async
 match = DEFAULT_ENV.match
+query = DEFAULT_ENV.query

jsonpath/env.py

@@ -27,6 +27,7 @@
 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
 from .function_extensions import validate
@@ -76,8 +77,6 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
  - Hook in to mapping and sequence item getting by overriding `getitem()`.
  - Change filter comparison operator behavior by overriding `compare()`.
 
- ## Class attributes
-
  Arguments:
  filter_caching (bool): If `True`, filter expressions will be cached
  where possible.
@@ -89,6 +88,8 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
 
  **New in version 0.10.0**
 
+ ## Class attributes
+
  Attributes:
  fake_root_token (str): The pattern used to select a "fake" root node, one level
  above the real root node.
@@ -229,9 +230,9 @@ def findall(
  *,
  filter_context: Optional[FilterContextVars] = None,
  ) -> List[object]:
- """Find all objects in `data` matching the given JSONPath `path`.
+ """Find all objects in _data_ matching the JSONPath _path_.
 
- If `data` is a string or a file-like objects, it will be loaded
+ If _data_ is a string or a file-like objects, it will be loaded
  using `json.loads()` and the default `JSONDecoder`.
 
  Arguments:
@@ -259,10 +260,10 @@ def finditer(
  *,
  filter_context: Optional[FilterContextVars] = None,
  ) -> Iterable[JSONPathMatch]:
- """Generate `JSONPathMatch` objects for each match.
+ """Generate `JSONPathMatch` objects for each match of _path_ in _data_.
 
- If `data` is a string or a file-like objects, it will be loaded
- using `json.loads()` and the default `JSONDecoder`.
+ If _data_ is a string or a file-like objects, it will be loaded using
+ `json.loads()` and the default `JSONDecoder`.
 
  Arguments:
  path: The JSONPath as a string.
@@ -310,6 +311,50 @@ def match(
  """
  return self.compile(path).match(data, filter_context=filter_context)
 
+ def query(
+ self,
+ path: str,
+ data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+ filter_context: Optional[FilterContextVars] = None,
+ ) -> Query:
+ """Return a `Query` object over matches found by applying _path_ to _data_.
+
+ `Query` objects are iterable.
+
+ ```
+ for match in jsonpath.query("$.foo..bar", data):
+ ...
+ ```
+
+ You can skip and limit results with `Query.skip()` and `Query.limit()`.
+
+ ```
+ matches = (
+ jsonpath.query("$.foo..bar", data)
+ .skip(5)
+ .limit(10)
+ )
+
+ for match in matches
+ ...
+ ```
+
+ `Query.tail()` will get the last _n_ results.
+
+ ```
+ for match in jsonpath.query("$.foo..bar", data).tail(5):
+ ...
+ ```
+
+ Get values for each match using `Query.values()`.
+
+ ```
+ for obj in jsonpath.query("$.foo..bar", data).limit(5).values():
+ ...
+ ```
+ """
+ return Query(self.finditer(path, data, filter_context=filter_context))
+
  async def findall_async(
  self,
  path: str,