More fluent API test cases.

Author: jg-rp

jsonpath/fluent_api.py

@@ -33,7 +33,7 @@ def __iter__(self) -> Iterator[JSONPathMatch]:
         return self._it
 
     def take(self, n: int) -> Query:
-        """Limit the result set to at most _n_ matches.
+        """Limit the query iterator to at most _n_ matches.
 
         Raises:
             ValueError: If _n_ < 0.
@@ -45,7 +45,7 @@ def take(self, n: int) -> Query:
         return self
 
     def limit(self, n: int) -> Query:
-        """Limit the result set to at most _n_ matches.
+        """Limit the query iterator to at most _n_ matches.
 
         `limit()` is an alias of `take()`.
 
@@ -55,7 +55,7 @@ def limit(self, n: int) -> Query:
         return self.take(n)
 
     def head(self, n: int) -> Query:
-        """Take the first _n_ matches.
+        """Limit the query iterator to at most the first _n_ matches.
 
         `head()` is an alias for `take()`.
 
@@ -64,8 +64,18 @@ def head(self, n: int) -> Query:
         """
         return self.take(n)
 
+    def first(self, n: int) -> Query:
+        """Limit the query iterator to at most the first _n_ matches.
+
+        `first()` is an alias for `take()`.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        return self.take(n)
+
     def drop(self, n: int) -> Query:
-        """Skip up to _n_ matches from the result set.
+        """Skip up to _n_ matches from the query iterator.
 
         Raises:
             ValueError: If _n_ < 0.
@@ -79,15 +89,15 @@ def drop(self, n: int) -> Query:
         return self
 
     def skip(self, n: int) -> Query:
-        """Skip up to _n_ matches from the result set.
+        """Skip up to _n_ matches from the query iterator.
 
         Raises:
             ValueError: If _n_ < 0.
         """
         return self.drop(n)
 
     def tail(self, n: int) -> Query:
-        """Drop matches up to the last _n_ matches.
+        """Drop matches up to the last _n_ matches from the iterator.
 
         Raises:
             ValueError: If _n_ < 0.
@@ -98,6 +108,16 @@ def tail(self, n: int) -> Query:
         self._it = iter(collections.deque(self._it, maxlen=n))
         return self
 
+    def last(self, n: int) -> Query:
+        """Drop up to the last _n_ matches from the iterator.
+
+        `last()` is an alias for `tail()`.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        return self.tail(n)
+
     def values(self) -> Iterable[object]:
         """Return an iterable of objects associated with each match."""
         return (m.obj for m in self._it)
@@ -110,14 +130,21 @@ 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)
 
-    def first(self) -> Optional[JSONPathMatch]:
+    def first_one(self) -> Optional[JSONPathMatch]:
         """Return the first `JSONPathMatch` or `None` if there were no matches."""
         try:
             return next(self._it)
         except StopIteration:
             return None
 
-    def last(self) -> Optional[JSONPathMatch]:
+    def one(self) -> Optional[JSONPathMatch]:
+        """Return the first `JSONPathMatch` or `None` if there were no matches.
+
+        `one()` is an alias for `first_one()`.
+        """
+        return self.first_one()
+
+    def last_one(self) -> Optional[JSONPathMatch]:
         """Return the last `JSONPathMatch` or `None` if there were no matches."""
         try:
             return next(iter(self.tail(1)))

tests/test_fluent_api.py

@@ -1,6 +1,7 @@
 """Test cases for the fluent API."""
 import pytest
 
+from jsonpath import JSONPathMatch
 from jsonpath import query
 
 
@@ -141,6 +142,14 @@ def test_query_head() -> None:
     assert [m.obj for m in matches] == [0, 1]
 
 
+def test_query_first() -> None:
+    """Test that we can limit the number of matches with `first`."""
+    it = query("$.some.*", {"some": [0, 1, 2, 3]}).first(2)
+    matches = list(it)
+    assert len(matches) == 2  # noqa: PLR2004
+    assert [m.obj for m in matches] == [0, 1]
+
+
 def test_query_tail() -> None:
     """Test that we can get the last _n_ matches."""
     it = query("$.some.*", {"some": [0, 1, 2, 3]}).tail(2)
@@ -177,3 +186,57 @@ def test_query_tail_negative() -> None:
     """Test that we get an exception if tail is given a negative integer."""
     with pytest.raises(ValueError, match="can't select a negative number of matches"):
         query("$.some.*", {"some": [0, 1, 2, 3]}).tail(-1)
+
+
+def test_query_last() -> None:
+    """Test that we can get the last _n_ matches with `last`."""
+    it = query("$.some.*", {"some": [0, 1, 2, 3]}).last(2)
+    matches = list(it)
+    assert len(matches) == 2  # noqa: PLR2004
+    assert [m.obj for m in matches] == [2, 3]
+
+
+def test_query_first_one() -> None:
+    """Test that we can get the first match from a query iterator."""
+    maybe_match = query("$.some.*", {"some": [0, 1, 2, 3]}).first_one()
+    assert isinstance(maybe_match, JSONPathMatch)
+    assert maybe_match.value == 0
+
+
+def test_query_first_one_of_empty_iterator() -> None:
+    """Test that `first_one` returns `None` if the iterator is empty."""
+    maybe_match = query("$.nosuchthing.*", {"some": [0, 1, 2, 3]}).first_one()
+    assert maybe_match is None
+
+
+def test_query_one() -> None:
+    """Test that we can get the first match from a query iterator with `one`."""
+    maybe_match = query("$.some.*", {"some": [0, 1, 2, 3]}).one()
+    assert isinstance(maybe_match, JSONPathMatch)
+    assert maybe_match.value == 0
+
+
+def test_query_last_one() -> None:
+    """Test that we can get the last match from a query iterator."""
+    maybe_match = query("$.some.*", {"some": [0, 1, 2, 3]}).last_one()
+    assert isinstance(maybe_match, JSONPathMatch)
+    assert maybe_match.value == 3  # noqa: PLR2004
+
+
+def test_query_last_of_empty_iterator() -> None:
+    """Test that `last_one` returns `None` if the iterator is empty."""
+    maybe_match = query("$.nosuchthing.*", {"some": [0, 1, 2, 3]}).last_one()
+    assert maybe_match is None
+
+
+def test_query_tee() -> None:
+    """Test that we can tee a query iterator."""
+    it1, it2 = query("$.some.*", {"some": [0, 1, 2, 3]}).tee()
+
+    rv1 = it1.skip(1).one()
+    assert rv1 is not None
+    assert rv1.value == 1
+
+    rv2 = it2.skip(2).one()
+    assert rv2 is not None
+    assert rv2.value == 2  # noqa: PLR2004