Implement find_one and JSONPathNodeList.items

Author: jg-rp

README.md

@@ -41,7 +41,7 @@ Each `JSONPathNode` has:
 The returned list is a subclass of `list` with some helper methods.
 
 - `values()` returns a list of values, one for each node.
-- `values_or_singular()` returns a scalar value if the list has exactly one node, or a list of values otherwise.
+- `items()` returns a list of `(normalized path, value)` tuples, one tuple for each node in the list.
 
 **Example:**
 
@@ -65,10 +65,56 @@ for node in jsonpath.find("$.users[?@.score > 85]", value):
 # {'name': 'John', 'score': 86, 'admin': True} at '$['users'][1]'
 ```
 
-### finditer(query, value)
+### `finditer(query, value)`
 
 `finditer()` accepts the same arguments as [`find()`](#findquery-value), but returns an iterator over `JSONPathNode` instances rather than a list. This could be useful if you're expecting a large number of results that you don't want to load into memory all at once.
 
+### `find_one(query, value)`
+
+`find_one()` accepts the same arguments as [`find()`](#findquery-value), but returns the first available `JSONPathNode`, or `None` if there were no matches.
+
+`find_one()` is equivalent to:
+
+```python
+def find_one(query, value):
+    try:
+        return next(iter(jsonpath.finditer(query, value)))
+    except StopIteration:
+        return None
+```
+
+### `compile(query)`
+
+`find(query, value)` is a convenience function for `JSONPathEnvironment().compile(query).apply(value)`. Use `compile(query)` to obtain a `JSONPathQuery` instance which can be applied to difference JSON-like values repeatedly.
+
+```python
+import jsonpath_rfc9535 as jsonpath
+
+value = {
+    "users": [
+        {"name": "Sue", "score": 100},
+        {"name": "John", "score": 86, "admin": True},
+        {"name": "Sally", "score": 84, "admin": False},
+        {"name": "Jane", "score": 55},
+    ],
+    "moderator": "John",
+}
+
+query = jsonpath.compile("$.users[?@.score > 85]")
+
+for node in query.apply(value):
+    print(f"{node.value} at '{node.path()}'")
+
+# {'name': 'Sue', 'score': 100} at '$['users'][0]'
+# {'name': 'John', 'score': 86, 'admin': True} at '$['users'][1]'
+```
+
+A `JSONPathQuery` has a `finditer(value)` method too, and `find(value)` is an alias for `apply(value)`.
+
 ## License
 
 `python-jsonpath-rfc9535` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+
+```
+
+```

jsonpath_rfc9535/__init__.py

@@ -29,6 +29,7 @@
     "Parser",
     "JSONPathQuery",
     "find",
+    "find_one",
     "finditer",
     "compile",
 )
@@ -38,3 +39,4 @@
 compile = DEFAULT_ENV.compile  # noqa: A001
 finditer = DEFAULT_ENV.finditer
 find = DEFAULT_ENV.find
+find_one = DEFAULT_ENV.find_one

jsonpath_rfc9535/environment.py

@@ -144,6 +144,28 @@ def find(
         """
         return self.compile(query).find(value)
 
+    def find_one(
+        self,
+        query: str,
+        value: JSONValue,
+    ) -> Optional[JSONPathNode]:
+        """Return the first available node from applying _query_ to _value_.
+
+        Arguments:
+            query: A JSONPath expression.
+            value: JSON-like data to query, as you'd get from `json.load`.
+
+        Returns:
+            The first available `JSONPathNode` instance, or `None` if there
+                are no matches.
+
+        Raises:
+            JSONPathSyntaxError: If the query is invalid.
+            JSONPathTypeError: If a filter expression attempts to use types in
+                an incompatible way.
+        """
+        return self.compile(query).find_one(value)
+
     def setup_function_extensions(self) -> None:
         """Initialize function extensions."""
         self.function_extensions["length"] = function_extensions.Length()

jsonpath_rfc9535/node.py

@@ -43,7 +43,7 @@ def path(self) -> str:
         )
 
     def __str__(self) -> str:
-        return f"JSONPathNode({self.path()})"
+        return f"JSONPathNode({self.path()!r})"
 
 
 class JSONPathNodeList(List[JSONPathNode]):
@@ -56,11 +56,9 @@ def values(self) -> List[object]:
         """Return the values from this node list."""
         return [node.value for node in self]
 
-    def values_or_singular(self) -> object:
-        """Return values from this node list, or a single value if there's one node."""
-        if len(self) == 1:
-            return self[0].value
-        return [node.value for node in self]
+    def items(self) -> List[Tuple[str, object]]:
+        """Return a list of (path, value) pairs, one for each node in the list."""
+        return [(node.path(), node.value) for node in self]
 
     def empty(self) -> bool:
         """Return `True` if this node list is empty."""

jsonpath_rfc9535/query.py

@@ -4,6 +4,7 @@
 
 from typing import TYPE_CHECKING
 from typing import Iterable
+from typing import Optional
 from typing import Tuple
 
 from .node import JSONPathNode
@@ -97,6 +98,28 @@ def find(
         """
         return JSONPathNodeList(self.finditer(value))
 
+    apply = find
+
+    def find_one(self, value: JSONValue) -> Optional[JSONPathNode]:
+        """Return the first node from applying this query to _value_.
+
+        Arguments:
+            value: JSON-like data to query, as you'd get from `json.load`.
+
+        Returns:
+            The first available `JSONPathNode` instance, or `None` if there
+                are no matches.
+
+        Raises:
+            JSONPathSyntaxError: If the query is invalid.
+            JSONPathTypeError: If a filter expression attempts to use types in
+                an incompatible way.
+        """
+        try:
+            return next(iter(self.finditer(value)))
+        except StopIteration:
+            return None
+
     def singular_query(self) -> bool:
         """Return `True` if this JSONPath expression is a singular query."""
         for segment in self.segments:

tests/test_env.py

@@ -0,0 +1,21 @@
+import pytest
+
+from jsonpath_rfc9535 import JSONPathEnvironment
+
+
+@pytest.fixture()
+def env() -> JSONPathEnvironment:
+    return JSONPathEnvironment()
+
+
+def test_find_one(env: JSONPathEnvironment) -> None:
+    """Test that we can get the first node from a node iterator."""
+    match = env.find_one("$.some", {"some": 1, "thing": 2})
+    assert match is not None
+    assert match.value == 1
+
+
+def test_find_on_no_match(env: JSONPathEnvironment) -> None:
+    """Test that we get `None` if there are no matches."""
+    match = env.find_one("$.other", {"some": 1, "thing": 2})
+    assert match is None