python-jsonpath 1.0.0__tar.gz → 1.1.1__tar.gz

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-jsonpath
-Version: 1.0.0
+Version: 1.1.1
 Summary: JSONPath, JSON Pointer and JSON Patch for Python.
 Project-URL: Documentation, https://jg-rp.github.io/python-jsonpath/
 Project-URL: Issues, https://github.com/jg-rp/python-jsonpath/issues

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2023-present James Prior <jamesgr.prior@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "1.0.0"
+__version__ = "1.1.1"

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/__init__.py

@@ -17,6 +17,7 @@ from .exceptions import RelativeJSONPointerError
 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
@@ -52,6 +53,8 @@ __all__ = (
     "Lexer",
     "match",
     "Parser",
+    "query",
+    "Query",
     "RelativeJSONPointer",
     "RelativeJSONPointerError",
     "RelativeJSONPointerIndexError",
@@ -69,3 +72,4 @@ findall_async = DEFAULT_ENV.findall_async
 finditer = DEFAULT_ENV.finditer
 finditer_async = DEFAULT_ENV.finditer_async
 match = DEFAULT_ENV.match
+query = DEFAULT_ENV.query

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/env.py

@@ -27,6 +27,7 @@ from .filter import FilterExpression
 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 JSONPathEnvironment:
     - 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 JSONPathEnvironment:
 
             **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 @@ class JSONPathEnvironment:
         *,
         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 @@ class JSONPathEnvironment:
         *,
         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 @@ class JSONPathEnvironment:
         """
         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,

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/filter.py

@@ -1,4 +1,5 @@
 """Filter expression nodes."""
+
 from __future__ import annotations
 
 import copy
@@ -317,7 +318,7 @@ class PrefixExpression(FilterExpression):
 class InfixExpression(FilterExpression):
     """A pair of expressions and a comparison or logical operator."""
 
-    __slots__ = ("left", "operator", "right")
+    __slots__ = ("left", "operator", "right", "logical")
 
     def __init__(
         self,
@@ -328,10 +329,11 @@ class InfixExpression(FilterExpression):
         self.left = left
         self.operator = operator
         self.right = right
+        self.logical = operator in ("&&", "||")
         super().__init__()
 
     def __str__(self) -> str:
-        if self.operator in ("&&", "||"):
+        if self.logical:
             return f"({self.left} {self.operator} {self.right})"
         return f"{self.left} {self.operator} {self.right}"
 
@@ -345,22 +347,22 @@ class InfixExpression(FilterExpression):
 
     def evaluate(self, context: FilterContext) -> bool:
         left = self.left.evaluate(context)
-        if isinstance(left, NodeList) and len(left) == 1:
+        if not self.logical and isinstance(left, NodeList) and len(left) == 1:
             left = left[0].obj
 
         right = self.right.evaluate(context)
-        if isinstance(right, NodeList) and len(right) == 1:
+        if not self.logical and isinstance(right, NodeList) and len(right) == 1:
             right = right[0].obj
 
         return context.env.compare(left, self.operator, right)
 
     async def evaluate_async(self, context: FilterContext) -> bool:
         left = await self.left.evaluate_async(context)
-        if isinstance(left, NodeList) and len(left) == 1:
+        if not self.logical and isinstance(left, NodeList) and len(left) == 1:
             left = left[0].obj
 
         right = await self.right.evaluate_async(context)
-        if isinstance(right, NodeList) and len(right) == 1:
+        if not self.logical and isinstance(right, NodeList) and len(right) == 1:
             right = right[0].obj
 
         return context.env.compare(left, self.operator, right)

python_jsonpath-1.1.1/jsonpath/fluent_api.py

@@ -0,0 +1,161 @@
+"""A fluent API for managing JSONPathMatch iterators."""
+from __future__ import annotations
+
+import collections
+import itertools
+from typing import TYPE_CHECKING
+from typing import Iterable
+from typing import Iterator
+from typing import Optional
+from typing import Tuple
+
+if TYPE_CHECKING:
+    from jsonpath import JSONPathMatch
+    from jsonpath import JSONPointer
+
+
+class Query:
+    """A fluent API for managing `JSONPathMatch` iterators.
+
+    Usually you'll want to use `jsonpath.query()` or `JSONPathEnvironment.query()`
+    to create instances of `Query` rather than instantiating `Query` directly.
+
+    Arguments:
+        it: A `JSONPathMatch` iterable, as you'd get from `jsonpath.finditer()` or
+            `JSONPathEnvironment.finditer()`.
+
+    **New in version 1.1.0**
+    """
+
+    def __init__(self, it: Iterable[JSONPathMatch]) -> None:
+        self._it = iter(it)
+
+    def __iter__(self) -> Iterator[JSONPathMatch]:
+        return self._it
+
+    def limit(self, n: int) -> Query:
+        """Limit the query iterator to at most _n_ matches.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        if n < 0:
+            raise ValueError("can't limit by a negative number of matches")
+
+        self._it = itertools.islice(self._it, n)
+        return self
+
+    def head(self, n: int) -> Query:
+        """Limit the query iterator to at most the first _n_ matches.
+
+        `head()` is an alias for `limit()`.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        return self.limit(n)
+
+    def first(self, n: int) -> Query:
+        """Limit the query iterator to at most the first _n_ matches.
+
+        `first()` is an alias for `limit()`.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        return self.limit(n)
+
+    def drop(self, n: int) -> Query:
+        """Skip up to _n_ matches from the query iterator.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        if n < 0:
+            raise ValueError("can't drop a negative number of matches")
+
+        if n > 0:
+            next(itertools.islice(self._it, n, n), None)
+
+        return self
+
+    def skip(self, n: int) -> Query:
+        """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 from the iterator.
+
+        Raises:
+            ValueError: If _n_ < 0.
+        """
+        if n < 0:
+            raise ValueError("can't select a negative number of matches")
+
+        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)
+
+    def locations(self) -> Iterable[str]:
+        """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, path) tuples, one for each match."""
+        return ((m.path, m.obj) for m in self._it)
+
+    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."""
+        try:
+            return next(self._it)
+        except StopIteration:
+            return None
+
+    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)))
+        except StopIteration:
+            return None
+
+    def tee(self, n: int = 2) -> Tuple[Query, ...]:
+        """Return _n_ independent queries by teeing this query's iterator.
+
+        It is not safe to use a `Query` instance after calling `tee()`.
+        """
+        return tuple(Query(it) for it in itertools.tee(self._it, n))
+
+    def take(self, n: int) -> Query:
+        """Return a new query iterating over the next _n_ matches.
+
+        It is safe to continue using this query after calling take.
+        """
+        return Query(list(itertools.islice(self._it, n)))

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/match.py

@@ -76,6 +76,11 @@ class JSONPathMatch:
         """Return a `JSONPointer` pointing to this match's path."""
         return JSONPointer.from_match(self)
 
+    @property
+    def value(self) -> object:
+        """Return the value associated with this match/node."""
+        return self.obj
+
 
 def _truncate(val: str, num: int, end: str = "...") -> str:
     # Replaces consecutive whitespace with a single newline.

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/parse.py

@@ -1,4 +1,5 @@
 """The default JSONPath parser."""
+
 from __future__ import annotations
 
 import json
@@ -142,14 +143,15 @@ class Parser:
     """A JSONPath parser bound to a JSONPathEnvironment."""
 
     PRECEDENCE_LOWEST = 1
-    PRECEDENCE_LOGICALRIGHT = 3
-    PRECEDENCE_LOGICAL = 4
+    PRECEDENCE_LOGICALRIGHT = 2
+    PRECEDENCE_LOGICAL_OR = 3
+    PRECEDENCE_LOGICAL_AND = 4
     PRECEDENCE_RELATIONAL = 5
     PRECEDENCE_MEMBERSHIP = 6
     PRECEDENCE_PREFIX = 7
 
     PRECEDENCES = {
-        TOKEN_AND: PRECEDENCE_LOGICAL,
+        TOKEN_AND: PRECEDENCE_LOGICAL_AND,
         TOKEN_CONTAINS: PRECEDENCE_MEMBERSHIP,
         TOKEN_EQ: PRECEDENCE_RELATIONAL,
         TOKEN_GE: PRECEDENCE_RELATIONAL,
@@ -160,7 +162,7 @@ class Parser:
         TOKEN_LT: PRECEDENCE_RELATIONAL,
         TOKEN_NE: PRECEDENCE_RELATIONAL,
         TOKEN_NOT: PRECEDENCE_PREFIX,
-        TOKEN_OR: PRECEDENCE_LOGICAL,
+        TOKEN_OR: PRECEDENCE_LOGICAL_OR,
         TOKEN_RE: PRECEDENCE_RELATIONAL,
         TOKEN_RPAREN: PRECEDENCE_LOWEST,
     }
@@ -563,9 +565,9 @@ class Parser:
 
     def parse_regex(self, stream: TokenStream) -> FilterExpression:
         pattern = stream.current.value
+        flags = 0
         if stream.peek.kind == TOKEN_RE_FLAGS:
             stream.next_token()
-            flags = 0
             for flag in set(stream.current.value):
                 flags |= self.RE_FLAG_MAP[flag]
         return RegexLiteral(value=re.compile(pattern, flags))

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/jsonpath/selectors.py

@@ -1,4 +1,4 @@
-"""JSONPath selector objects, as returned from `Parser.parse`."""
+"""JSONPath segments and selectors, as returned from `Parser.parse`."""
 from __future__ import annotations
 
 from abc import ABC
@@ -28,7 +28,7 @@ if TYPE_CHECKING:
 
 
 class JSONPathSelector(ABC):
-    """Base class for all JSONPath selectors."""
+    """Base class for all JSONPath segments and selectors."""
 
     __slots__ = ("env", "token")
 
@@ -38,7 +38,17 @@ class JSONPathSelector(ABC):
 
     @abstractmethod
     def resolve(self, matches: Iterable[JSONPathMatch]) -> Iterable[JSONPathMatch]:
-        """Expand matches from previous JSONPath selectors in to new matches."""
+        """Apply the segment/selector to each node in _matches_.
+
+        Arguments:
+            matches: Nodes matched by preceding segments/selectors. This is like
+                a lazy _NodeList_, as described in RFC 9535, but each match carries
+                more than the node's value and location.
+
+        Returns:
+            The `JSONPathMatch` instances created by applying this selector to each
+            preceding node.
+        """
 
     @abstractmethod
     def resolve_async(
@@ -48,7 +58,7 @@ class JSONPathSelector(ABC):
 
 
 class PropertySelector(JSONPathSelector):
-    """A JSONPath property."""
+    """A shorthand or bracketed property selector."""
 
     __slots__ = ("name", "shorthand")
 
@@ -115,7 +125,12 @@ class PropertySelector(JSONPathSelector):
 
 
 class IndexSelector(JSONPathSelector):
-    """Dotted and bracketed sequence access by index."""
+    """Select an element from an array by index.
+
+    Considering we don't require mapping (JSON object) keys/properties to
+    be quoted, and that we support mappings with numeric keys, we also check
+    to see if the "index" is a mapping key, which is non-standard.
+    """
 
     __slots__ = ("index", "_as_key")
 
@@ -213,7 +228,10 @@ class IndexSelector(JSONPathSelector):
 
 
 class KeysSelector(JSONPathSelector):
-    """Select an mapping's keys/properties."""
+    """Select mapping/object keys/properties.
+
+    NOTE: This is a non-standard selector.
+    """
 
     __slots__ = ("shorthand",)
 
@@ -354,7 +372,7 @@ class SliceSelector(JSONPathSelector):
 
 
 class WildSelector(JSONPathSelector):
-    """Wildcard expansion selector."""
+    """Select all items from a sequence/array or values from a mapping/object."""
 
     __slots__ = ("shorthand",)
 
@@ -433,7 +451,10 @@ class WildSelector(JSONPathSelector):
 
 
 class RecursiveDescentSelector(JSONPathSelector):
-    """A JSONPath selector that visits all objects recursively."""
+    """A JSONPath selector that visits all nodes recursively.
+
+    NOTE: Strictly this is a "segment", not a "selector".
+    """
 
     def __str__(self) -> str:
         return ".."
@@ -504,7 +525,10 @@ async def _alist(it: List[T]) -> AsyncIterable[T]:
 
 
 class ListSelector(JSONPathSelector):
-    """A JSONPath selector representing a list of properties, slices or indices."""
+    """A bracketed list of selectors, the results of which are concatenated together.
+
+    NOTE: Strictly this is a "segment", not a "selector".
+    """
 
     __slots__ = ("items",)
 
@@ -541,21 +565,21 @@ class ListSelector(JSONPathSelector):
         return hash((self.items, self.token))
 
     def resolve(self, matches: Iterable[JSONPathMatch]) -> Iterable[JSONPathMatch]:
-        _matches = list(matches)
-        for item in self.items:
-            yield from item.resolve(_matches)
+        for match_ in matches:
+            for item in self.items:
+                yield from item.resolve([match_])
 
     async def resolve_async(
         self, matches: AsyncIterable[JSONPathMatch]
     ) -> AsyncIterable[JSONPathMatch]:
-        _matches = [m async for m in matches]
-        for item in self.items:
-            async for match in item.resolve_async(_alist(_matches)):
-                yield match
+        async for match_ in matches:
+            for item in self.items:
+                async for m in item.resolve_async(_alist([match_])):
+                    yield m
 
 
 class Filter(JSONPathSelector):
-    """A filter selector."""
+    """Filter sequence/array items or mapping/object values with a filter expression."""
 
     __slots__ = ("expression", "cacheable_nodes")
 
@@ -713,7 +737,7 @@ class Filter(JSONPathSelector):
 
 
 class FilterContext:
-    """A filter expression context."""
+    """Contextual information and data for evaluating a filter expression."""
 
     __slots__ = (
         "current_key",

{python_jsonpath-1.0.0 → python_jsonpath-1.1.1}/pyproject.toml

@@ -105,6 +105,38 @@ warn_unreachable = true
 
 
 [tool.ruff]
+# Exclude a variety of commonly ignored directories.
+exclude = [
+  ".bzr",
+  ".direnv",
+  ".eggs",
+  ".git",
+  ".hg",
+  ".mypy_cache",
+  ".nox",
+  ".pants.d",
+  ".pytype",
+  ".ruff_cache",
+  ".svn",
+  ".tox",
+  ".venv",
+  "__pypackages__",
+  "_build",
+  "buck-out",
+  "build",
+  "dist",
+  "node_modules",
+  "venv",
+]
+
+# Same as Black.
+line-length = 88
+
+
+# Assume Python 3.10.
+target-version = "py310"
+
+[tool.ruff.lint]
 select = [
   "A",
   "ARG",
@@ -134,52 +166,23 @@ select = [
   "TID",
   "YTT",
 ]
+
 ignore = ["S105", "S101", "D107", "D105", "PLR0913", "SIM108"]
 
 fixable = ["I"]
 unfixable = []
 
-# Exclude a variety of commonly ignored directories.
-exclude = [
-  ".bzr",
-  ".direnv",
-  ".eggs",
-  ".git",
-  ".hg",
-  ".mypy_cache",
-  ".nox",
-  ".pants.d",
-  ".pytype",
-  ".ruff_cache",
-  ".svn",
-  ".tox",
-  ".venv",
-  "__pypackages__",
-  "_build",
-  "buck-out",
-  "build",
-  "dist",
-  "node_modules",
-  "venv",
-]
-
-# Same as Black.
-line-length = 88
-
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
-# Assume Python 3.10.
-target-version = "py310"
-
-[tool.ruff.isort]
+[tool.ruff.lint.isort]
 force-single-line = true
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "google"
 
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 "jsonpath/__about__.py" = ["D100"]
 "jsonpath/__init__.py" = ["D104"]
 "tests/*" = ["D100", "D101", "D104", "D103"]