python-jsonpath 1.1.0__tar.gz → 1.2.0__tar.gz

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/.gitignore

@@ -85,4 +85,7 @@ profile_.py
 
 # Test fixtures
 comparison_regression_suite.yaml
-cts.json
+cts.json
+
+# System
+.DS_Store

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-jsonpath
-Version: 1.1.0
+Version: 1.2.0
 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
@@ -56,6 +56,7 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> a
 
 - [Install](#install)
 - [Links](#links)
+- [Related projects](#related-projects)
 - [Examples](#examples)
 - [License](#license)
 
@@ -88,6 +89,14 @@ conda install -c conda-forge python-jsonpath
 - Source code: https://github.com/jg-rp/python-jsonpath
 - Issue tracker: https://github.com/jg-rp/python-jsonpath/issues
 
+## Related projects
+
+- [Python JSONPath RFC 9535](https://github.com/jg-rp/python-jsonpath-rfc9535) - An implementation of JSONPath that follows RFC 9535 much more strictly. If you require maximum interoperability with JSONPath implemented in other languages - at the expense of extra features - choose python-jsonpath-rfc9535 over python-jsonpath.
+
+  python-jsonpath-rfc9535 matches RFC 9535's JSONPath model internally and is careful to match the spec's terminology. It also includes utilities for verifying and testing the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite). Most notably the nondeterministic behavior of some JSONPath selectors.
+
+- [JSON P3](https://github.com/jg-rp/json-p3) - RFC 9535 implemented in TypeScript. JSON P3 does not include all the non-standard features of Python JSONPath, but does define some optional [extra syntax](https://jg-rp.github.io/json-p3/guides/jsonpath-extra).
+
 ## Examples
 
 ### JSONPath
@@ -110,7 +119,7 @@ print(user_names) # ['John', 'Sally', 'Jane']
 
 ### JSON Pointer
 
-Since version 0.8.0, we include an [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) compliant implementation of JSON Pointer. See JSON Pointer [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#pointerresolvepointer-data), [guide](https://jg-rp.github.io/python-jsonpath/pointers/) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPointer)
+We include an [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) compliant implementation of JSON Pointer. See JSON Pointer [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#pointerresolvepointer-data), [guide](https://jg-rp.github.io/python-jsonpath/pointers/) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPointer)
 
 ```python
 from jsonpath import pointer
@@ -133,7 +142,7 @@ print(jane_score)  # 55
 
 ### JSON Patch
 
-Since version 0.8.0, we also include an [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) compliant implementation of JSON Patch. See JSON Patch [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#patchapplypatch-data) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPatch)
+We also include an [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) compliant implementation of JSON Patch. See JSON Patch [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#patchapplypatch-data) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPatch)
 
 ```python
 from jsonpath import patch

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/README.md

@@ -31,6 +31,7 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> a
 
 - [Install](#install)
 - [Links](#links)
+- [Related projects](#related-projects)
 - [Examples](#examples)
 - [License](#license)
 
@@ -63,6 +64,14 @@ conda install -c conda-forge python-jsonpath
 - Source code: https://github.com/jg-rp/python-jsonpath
 - Issue tracker: https://github.com/jg-rp/python-jsonpath/issues
 
+## Related projects
+
+- [Python JSONPath RFC 9535](https://github.com/jg-rp/python-jsonpath-rfc9535) - An implementation of JSONPath that follows RFC 9535 much more strictly. If you require maximum interoperability with JSONPath implemented in other languages - at the expense of extra features - choose python-jsonpath-rfc9535 over python-jsonpath.
+
+  python-jsonpath-rfc9535 matches RFC 9535's JSONPath model internally and is careful to match the spec's terminology. It also includes utilities for verifying and testing the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite). Most notably the nondeterministic behavior of some JSONPath selectors.
+
+- [JSON P3](https://github.com/jg-rp/json-p3) - RFC 9535 implemented in TypeScript. JSON P3 does not include all the non-standard features of Python JSONPath, but does define some optional [extra syntax](https://jg-rp.github.io/json-p3/guides/jsonpath-extra).
+
 ## Examples
 
 ### JSONPath
@@ -85,7 +94,7 @@ print(user_names) # ['John', 'Sally', 'Jane']
 
 ### JSON Pointer
 
-Since version 0.8.0, we include an [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) compliant implementation of JSON Pointer. See JSON Pointer [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#pointerresolvepointer-data), [guide](https://jg-rp.github.io/python-jsonpath/pointers/) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPointer)
+We include an [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) compliant implementation of JSON Pointer. See JSON Pointer [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#pointerresolvepointer-data), [guide](https://jg-rp.github.io/python-jsonpath/pointers/) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPointer)
 
 ```python
 from jsonpath import pointer
@@ -108,7 +117,7 @@ print(jane_score)  # 55
 
 ### JSON Patch
 
-Since version 0.8.0, we also include an [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) compliant implementation of JSON Patch. See JSON Patch [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#patchapplypatch-data) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPatch)
+We also include an [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) compliant implementation of JSON Patch. See JSON Patch [quick start](https://jg-rp.github.io/python-jsonpath/quickstart/#patchapplypatch-data) and [API reference](https://jg-rp.github.io/python-jsonpath/api/#jsonpath.JSONPatch)
 
 ```python
 from jsonpath import patch

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/__about__.py

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

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/__init__.py

@@ -3,11 +3,14 @@
 # SPDX-License-Identifier: MIT
 
 from .env import JSONPathEnvironment
+from .exceptions import JSONPatchError
+from .exceptions import JSONPatchTestFailure
 from .exceptions import JSONPathError
 from .exceptions import JSONPathIndexError
 from .exceptions import JSONPathNameError
 from .exceptions import JSONPathSyntaxError
 from .exceptions import JSONPathTypeError
+from .exceptions import JSONPointerEncodeError
 from .exceptions import JSONPointerError
 from .exceptions import JSONPointerIndexError
 from .exceptions import JSONPointerKeyError
@@ -17,6 +20,7 @@ from .exceptions import RelativeJSONPointerError
 from .exceptions import RelativeJSONPointerIndexError
 from .exceptions import RelativeJSONPointerSyntaxError
 from .filter import UNDEFINED
+from .fluent_api import Projection
 from .fluent_api import Query
 from .lex import Lexer
 from .match import JSONPathMatch
@@ -31,13 +35,13 @@ from .pointer import resolve
 __all__ = (
     "compile",
     "CompoundJSONPath",
-    "find",
     "findall_async",
     "findall",
     "finditer_async",
     "finditer",
-    "first",
     "JSONPatch",
+    "JSONPatchError",
+    "JSONPatchTestFailure",
     "JSONPath",
     "JSONPathEnvironment",
     "JSONPathError",
@@ -47,6 +51,7 @@ __all__ = (
     "JSONPathSyntaxError",
     "JSONPathTypeError",
     "JSONPointer",
+    "JSONPointerEncodeError",
     "JSONPointerError",
     "JSONPointerIndexError",
     "JSONPointerKeyError",
@@ -55,6 +60,7 @@ __all__ = (
     "Lexer",
     "match",
     "Parser",
+    "Projection",
     "query",
     "Query",
     "RelativeJSONPointer",

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/env.py

@@ -1,4 +1,5 @@
 """Core JSONPath configuration object."""
+
 from __future__ import annotations
 
 import re
@@ -317,7 +318,7 @@ class JSONPathEnvironment:
         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_.
+        """Return a `Query` iterator over matches found by applying _path_ to _data_.
 
         `Query` objects are iterable.
 
@@ -352,8 +353,23 @@ class JSONPathEnvironment:
         for obj in jsonpath.query("$.foo..bar", data).limit(5).values():
             ...
         ```
+
+        Arguments:
+            path: The JSONPath as a string.
+            data: A JSON document or Python object implementing the `Sequence`
+                or `Mapping` interfaces.
+            filter_context: Arbitrary data made available to filters using
+                the _filter context_ selector.
+
+        Returns:
+            A query iterator.
+
+        Raises:
+            JSONPathSyntaxError: If the path is invalid.
+            JSONPathTypeError: If a filter expression attempts to use types in
+                an incompatible way.
         """
-        return Query(self.finditer(path, data, filter_context=filter_context))
+        return Query(self.finditer(path, data, filter_context=filter_context), self)
 
     async def findall_async(
         self,
@@ -548,9 +564,9 @@ class JSONPathEnvironment:
             return self._lt(right, left) or self._eq(left, right)
         if operator == "<=":
             return self._lt(left, right) or self._eq(left, right)
-        if operator == "in" and isinstance(right, Sequence):
+        if operator == "in" and isinstance(right, (Mapping, Sequence)):
             return left in right
-        if operator == "contains" and isinstance(left, Sequence):
+        if operator == "contains" and isinstance(left, (Mapping, Sequence)):
             return right in left
         if operator == "=~" and isinstance(right, re.Pattern) and isinstance(left, str):
             return bool(right.fullmatch(left))

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/filter.py

@@ -318,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,
@@ -329,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}"
 
@@ -346,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)
@@ -667,6 +668,9 @@ class CurrentKey(FilterExpression):
         super().__init__()
         self.volatile = True
 
+    def __str__(self) -> str:
+        return "#"
+
     def __eq__(self, other: object) -> bool:
         return isinstance(other, CurrentKey)
 

python_jsonpath-1.2.0/jsonpath/fluent_api.py

@@ -0,0 +1,286 @@
+"""A fluent API for working with `JSONPathMatch` iterators."""
+
+from __future__ import annotations
+
+import collections
+import itertools
+from enum import Enum
+from enum import auto
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Dict
+from typing import Iterable
+from typing import Iterator
+from typing import List
+from typing import Mapping
+from typing import Optional
+from typing import Sequence
+from typing import Tuple
+from typing import Union
+
+if TYPE_CHECKING:
+    from jsonpath import CompoundJSONPath
+    from jsonpath import JSONPath
+    from jsonpath import JSONPathEnvironment
+    from jsonpath import JSONPathMatch
+    from jsonpath import JSONPointer
+
+
+class Projection(Enum):
+    """Projection style used by `Query.select()`."""
+
+    RELATIVE = auto()
+    """The default projection. Selections include parent arrays and objects relative
+    to the JSONPathMatch."""
+
+    ROOT = auto()
+    """Selections include parent arrays and objects relative to the root JSON value."""
+
+    FLAT = auto()
+    """All selections are appended to a new array/list, without arrays and objects
+    on the path to the selected value."""
+
+
+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], env: JSONPathEnvironment) -> None:
+        self._it = iter(it)
+        self._env = env
+
+    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 (path, object) 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, self._env) 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)), self._env)
+
+    def select(
+        self,
+        *expressions: Union[str, JSONPath, CompoundJSONPath],
+        projection: Projection = Projection.RELATIVE,
+    ) -> Iterable[object]:
+        """Query projection using relative JSONPaths.
+
+        Arguments:
+            expressions: One or more JSONPath query expressions to select relative
+                to each match in this query iterator.
+            projection: The style of projection used when selecting values. Can be
+                one of `Projection.RELATIVE`, `Projection.ROOT` or `Projection.FLAT`.
+                Defaults to `Projection.RELATIVE`.
+
+        Returns:
+            An iterable of objects built from selecting _expressions_ relative to
+                each match from the current query.
+
+        **New in version 1.2.0**
+        """
+        return filter(
+            bool,
+            (self._select(m, expressions, projection) for m in self._it),
+        )
+
+    def _select(
+        self,
+        match: JSONPathMatch,
+        expressions: Tuple[Union[str, JSONPath, CompoundJSONPath], ...],
+        projection: Projection,
+    ) -> object:
+        if not isinstance(match.obj, (Mapping, Sequence)) or isinstance(match.obj, str):
+            return None
+
+        if projection == Projection.RELATIVE:
+            obj: Dict[Union[int, str], Any] = {}
+            for expr in expressions:
+                path = self._env.compile(expr) if isinstance(expr, str) else expr
+                for rel_match in path.finditer(match.obj):  # type: ignore
+                    _patch_obj(rel_match.parts, obj, rel_match.obj)
+
+            return _fix_sparse_arrays(obj)
+
+        if projection == Projection.FLAT:
+            arr: List[object] = []
+            for expr in expressions:
+                path = self._env.compile(expr) if isinstance(expr, str) else expr
+                for rel_match in path.finditer(match.obj):  # type: ignore
+                    arr.append(rel_match.obj)
+            return arr
+
+        # Project from the root document
+        obj = {}
+        for expr in expressions:
+            path = self._env.compile(expr) if isinstance(expr, str) else expr
+            for rel_match in path.finditer(match.obj):  # type: ignore
+                _patch_obj(match.parts + rel_match.parts, obj, rel_match.obj)
+
+        return _fix_sparse_arrays(obj)
+
+
+def _patch_obj(
+    parts: Tuple[Union[int, str], ...],
+    obj: Mapping[Union[str, int], Any],
+    value: object,
+) -> None:
+    _obj = obj
+
+    # For lack of a better idea, we're patching arrays to dictionaries with
+    # integer keys. This is to handle sparse array selections without having
+    # to keep track of indexes and how they map from the root JSON value to
+    # the selected JSON value.
+    #
+    # We'll fix these "sparse arrays" after the patch has been applied.
+    for part in parts[:-1]:
+        if part not in _obj:
+            _obj[part] = {}  # type: ignore
+        _obj = _obj[part]
+
+    _obj[parts[-1]] = value  # type: ignore
+
+
+def _fix_sparse_arrays(obj: Any) -> object:
+    """Fix sparse arrays (dictionaries with integer keys)."""
+    if isinstance(obj, str) or not obj:
+        return obj
+
+    if isinstance(obj, Sequence):
+        return [_fix_sparse_arrays(e) for e in obj]
+
+    if isinstance(obj, Mapping):
+        if isinstance(next(iter(obj)), int):
+            return [_fix_sparse_arrays(v) for v in obj.values()]
+        return {k: _fix_sparse_arrays(v) for k, v in obj.items()}
+
+    return obj

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/lex.py

@@ -1,4 +1,5 @@
 """JSONPath tokenization."""
+
 from __future__ import annotations
 
 import re
@@ -138,8 +139,8 @@ class Lexer:
             (TOKEN_LIST_SLICE, self.slice_list_pattern),
             (TOKEN_FUNCTION, self.function_pattern),
             (TOKEN_DOT_PROPERTY, self.dot_property_pattern),
-            (TOKEN_FLOAT, r"-?\d+\.\d*(?:e[+-]?\d+)?"),
-            (TOKEN_INT, r"-?\d+(?P<G_EXP>e[+\-]?\d+)?\b"),
+            (TOKEN_FLOAT, r"-?\d+\.\d*(?:[eE][+-]?\d+)?"),
+            (TOKEN_INT, r"-?\d+(?P<G_EXP>[eE][+\-]?\d+)?\b"),
             (TOKEN_DDOT, r"\.\."),
             (TOKEN_AND, self.logical_and_pattern),
             (TOKEN_OR, self.logical_or_pattern),

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/parse.py

@@ -30,6 +30,8 @@ from .filter import FunctionExtension
 from .filter import InfixExpression
 from .filter import IntegerLiteral
 from .filter import ListLiteral
+from .filter import Literal
+from .filter import Nil
 from .filter import Path
 from .filter import PrefixExpression
 from .filter import RegexLiteral
@@ -191,6 +193,23 @@ class Parser:
             "<=",
             "<",
             "!=",
+            "=~",
+        ]
+    )
+
+    # Infix operators that accept filter expression literals.
+    INFIX_LITERAL_OPERATORS = frozenset(
+        [
+            "==",
+            ">=",
+            ">",
+            "<=",
+            "<",
+            "!=",
+            "<>",
+            "=~",
+            "in",
+            "contains",
         ]
     )
 
@@ -455,6 +474,12 @@ class Parser:
                 stream.expect_peek(TOKEN_COMMA)
                 stream.next_token()
 
+                if stream.peek.kind == TOKEN_RBRACKET:
+                    raise JSONPathSyntaxError(
+                        "unexpected trailing comma",
+                        token=stream.peek,
+                    )
+
             stream.next_token()
 
         if not list_items:
@@ -477,6 +502,13 @@ class Parser:
                     f"result of {expr.name}() must be compared", token=tok
                 )
 
+        if isinstance(expr, (Literal, Nil)):
+            raise JSONPathSyntaxError(
+                "filter expression literals outside of "
+                "function expressions must be compared",
+                token=tok,
+            )
+
         return Filter(env=self.env, token=tok, expression=BooleanExpression(expr))
 
     def parse_boolean(self, stream: TokenStream) -> FilterExpression:
@@ -520,6 +552,20 @@ class Parser:
             self._raise_for_non_comparable_function(left, tok)
             self._raise_for_non_comparable_function(right, tok)
 
+        if operator not in self.INFIX_LITERAL_OPERATORS:
+            if isinstance(left, (Literal, Nil)):
+                raise JSONPathSyntaxError(
+                    "filter expression literals outside of "
+                    "function expressions must be compared",
+                    token=tok,
+                )
+            if isinstance(right, (Literal, Nil)):
+                raise JSONPathSyntaxError(
+                    "filter expression literals outside of "
+                    "function expressions must be compared",
+                    token=tok,
+                )
+
         return InfixExpression(left, operator, right)
 
     def parse_grouped_expression(self, stream: TokenStream) -> FilterExpression:
@@ -532,6 +578,13 @@ class Parser:
                 raise JSONPathSyntaxError(
                     "unbalanced parentheses", token=stream.current
                 )
+
+            if stream.current.kind not in self.BINARY_OPERATORS:
+                raise JSONPathSyntaxError(
+                    f"expected an expression, found '{stream.current.value}'",
+                    token=stream.current,
+                )
+
             expr = self.parse_infix_expression(stream, expr)
 
         stream.expect(TOKEN_RPAREN)
@@ -539,7 +592,6 @@ class Parser:
 
     def parse_root_path(self, stream: TokenStream) -> FilterExpression:
         root = stream.next_token()
-        assert root.kind in {TOKEN_ROOT, TOKEN_FAKE_ROOT}  # XXX:
         return RootPath(
             JSONPath(
                 env=self.env,

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/patch.py

@@ -1,4 +1,5 @@
 """JSON Patch, as per RFC 6902."""
+
 from __future__ import annotations
 
 import copy
@@ -85,6 +86,78 @@ class OpAdd(Op):
         return {"op": self.name, "path": str(self.path), "value": self.value}
 
 
+class OpAddNe(OpAdd):
+    """A non-standard _add if not exists_ operation.
+
+    This is like _OpAdd_, but only adds object/dict keys/values if they key does
+    not already exist.
+
+    **New in version 1.2.0**
+    """
+
+    __slots__ = ("path", "value")
+
+    name = "addne"
+
+    def apply(
+        self, data: Union[MutableSequence[object], MutableMapping[str, object]]
+    ) -> Union[MutableSequence[object], MutableMapping[str, object]]:
+        """Apply this patch operation to _data_."""
+        parent, obj = self.path.resolve_parent(data)
+        if parent is None:
+            # Replace the root object.
+            # The following op, if any, will raise a JSONPatchError if needed.
+            return self.value  # type: ignore
+
+        target = self.path.parts[-1]
+        if isinstance(parent, MutableSequence):
+            if obj is UNDEFINED:
+                parent.append(self.value)
+            else:
+                parent.insert(int(target), self.value)
+        elif isinstance(parent, MutableMapping) and target not in parent:
+            parent[target] = self.value
+        return data
+
+
+class OpAddAp(OpAdd):
+    """A non-standard add operation that appends to arrays/lists .
+
+    This is like _OpAdd_, but assumes an index of "-" if the path can not
+    be resolved.
+
+    **New in version 1.2.0**
+    """
+
+    __slots__ = ("path", "value")
+
+    name = "addap"
+
+    def apply(
+        self, data: Union[MutableSequence[object], MutableMapping[str, object]]
+    ) -> Union[MutableSequence[object], MutableMapping[str, object]]:
+        """Apply this patch operation to _data_."""
+        parent, obj = self.path.resolve_parent(data)
+        if parent is None:
+            # Replace the root object.
+            # The following op, if any, will raise a JSONPatchError if needed.
+            return self.value  # type: ignore
+
+        target = self.path.parts[-1]
+        if isinstance(parent, MutableSequence):
+            if obj is UNDEFINED:
+                parent.append(self.value)
+            else:
+                parent.insert(int(target), self.value)
+        elif isinstance(parent, MutableMapping):
+            parent[target] = self.value
+        else:
+            raise JSONPatchError(
+                f"unexpected operation on {parent.__class__.__name__!r}"
+            )
+        return data
+
+
 class OpRemove(Op):
     """The JSON Patch _remove_ operation."""
 
@@ -340,6 +413,16 @@ class JSONPatch:
                     path=self._op_pointer(operation, "path", "add", i),
                     value=self._op_value(operation, "value", "add", i),
                 )
+            elif op == "addne":
+                self.addne(
+                    path=self._op_pointer(operation, "path", "addne", i),
+                    value=self._op_value(operation, "value", "addne", i),
+                )
+            elif op == "addap":
+                self.addne(
+                    path=self._op_pointer(operation, "path", "addap", i),
+                    value=self._op_value(operation, "value", "addap", i),
+                )
             elif op == "remove":
                 self.remove(path=self._op_pointer(operation, "path", "add", i))
             elif op == "replace":
@@ -424,6 +507,38 @@ class JSONPatch:
         self.ops.append(OpAdd(path=pointer, value=value))
         return self
 
+    def addne(self: Self, path: Union[str, JSONPointer], value: object) -> Self:
+        """Append an _addne_ operation to this patch.
+
+        Arguments:
+            path: A string representation of a JSON Pointer, or one that has
+                already been parsed.
+            value: The object to add.
+
+        Returns:
+            This `JSONPatch` instance, so we can build a JSON Patch by chaining
+                calls to JSON Patch operation methods.
+        """
+        pointer = self._ensure_pointer(path)
+        self.ops.append(OpAddNe(path=pointer, value=value))
+        return self
+
+    def addap(self: Self, path: Union[str, JSONPointer], value: object) -> Self:
+        """Append an _addap_ operation to this patch.
+
+        Arguments:
+            path: A string representation of a JSON Pointer, or one that has
+                already been parsed.
+            value: The object to add.
+
+        Returns:
+            This `JSONPatch` instance, so we can build a JSON Patch by chaining
+                calls to JSON Patch operation methods.
+        """
+        pointer = self._ensure_pointer(path)
+        self.ops.append(OpAddAp(path=pointer, value=value))
+        return self
+
     def remove(self: Self, path: Union[str, JSONPointer]) -> Self:
         """Append a _remove_ operation to this patch.
 
@@ -551,6 +666,7 @@ class JSONPatch:
                 raise JSONPatchError(f"{err} ({op.name}:{i})") from err
             except (JSONPointerError, JSONPatchError) as err:
                 raise JSONPatchError(f"{err} ({op.name}:{i})") from err
+
         return _data
 
     def asdicts(self) -> List[Dict[str, object]]:

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/path.py

@@ -15,6 +15,7 @@ from typing import TypeVar
 from typing import Union
 
 from jsonpath._data import load_data
+from jsonpath.fluent_api import Query
 from jsonpath.match import FilterContextVars
 from jsonpath.match import JSONPathMatch
 from jsonpath.selectors import IndexSelector
@@ -210,6 +211,30 @@ class JSONPath:
         except StopIteration:
             return None
 
+    def query(
+        self,
+        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        *,
+        filter_context: Optional[FilterContextVars] = None,
+    ) -> Query:
+        """Return a `Query` iterator over matches found by applying this path to _data_.
+
+        Arguments:
+            data: A JSON document or Python object implementing the `Sequence`
+                or `Mapping` interfaces.
+            filter_context: Arbitrary data made available to filters using
+                the _filter context_ selector.
+
+        Returns:
+            A query iterator.
+
+        Raises:
+            JSONPathSyntaxError: If the path is invalid.
+            JSONPathTypeError: If a filter expression attempts to use types in
+                an incompatible way.
+        """
+        return Query(self.finditer(data, filter_context=filter_context), self.env)
+
     def empty(self) -> bool:
         """Return `True` if this path has no selectors."""
         return not bool(self.selectors)
@@ -407,6 +432,30 @@ class CompoundJSONPath:
 
         return matches
 
+    def query(
+        self,
+        data: Union[str, IOBase, Sequence[Any], Mapping[str, Any]],
+        *,
+        filter_context: Optional[FilterContextVars] = None,
+    ) -> Query:
+        """Return a `Query` iterator over matches found by applying this path to _data_.
+
+        Arguments:
+            data: A JSON document or Python object implementing the `Sequence`
+                or `Mapping` interfaces.
+            filter_context: Arbitrary data made available to filters using
+                the _filter context_ selector.
+
+        Returns:
+            A query iterator.
+
+        Raises:
+            JSONPathSyntaxError: If the path is invalid.
+            JSONPathTypeError: If a filter expression attempts to use types in
+                an incompatible way.
+        """
+        return Query(self.finditer(data, filter_context=filter_context), self.env)
+
     def union(self, path: JSONPath) -> CompoundJSONPath:
         """Union of this path and another path."""
         return self.__class__(

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/jsonpath/pointer.py

@@ -1,4 +1,5 @@
 """JSON Pointer. See https://datatracker.ietf.org/doc/html/rfc6901."""
+
 from __future__ import annotations
 
 import codecs
@@ -326,6 +327,9 @@ class JSONPointer:
     def __eq__(self, other: object) -> bool:
         return isinstance(other, JSONPointer) and self.parts == other.parts
 
+    def __hash__(self) -> int:
+        return hash(self.parts)
+
     def __repr__(self) -> str:
         return f"JSONPointer({self._s!r})"
 

{python_jsonpath-1.1.0 → python_jsonpath-1.2.0}/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",)
 
@@ -555,7 +579,7 @@ class ListSelector(JSONPathSelector):
 
 
 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.1.0/jsonpath/fluent_api.py

@@ -1,161 +0,0 @@
-"""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)))