Merge pull request #6 from jg-rp/nodelists

feat: add support for filter functions that operate on node lists

Author: jg-rp

CHANGELOG.md

@@ -1,15 +1,20 @@
 # Python JSONPath Change Log
 
-## Version 0.7.0
+## Version 0.7.0 (unreleased)
 
 **Breaking changes**
 
 - `JSONPathIndexError` now requires a `token` parameter. It used to be optional.
+- Filter expressions that resolve JSON paths (like `SelfPath` and `RootPath`) now return a `NodeList`. The node list must then be explicitly unpacked by `JSONPathEnvironment.compare()` and any filter function that has a `with_node_lists` attribute set to `True`. This is done for the benefit of the `count()` filter function and standards compliance.
 
 **Features**
 
 - `missing` is now an allowed alias of `undefined` when using the `isinstance()` filter function.
 
+**IETF JSONPath Draft compliance**
+
+- The built-in `count()` filter function is now compliant with the standard, operating on a "nodelist" instead of node values.
+
 ## Version 0.6.0
 
 **Breaking changes**

jsonpath/env.py

@@ -24,6 +24,7 @@
 from .filter import UNDEFINED
 from .function_extensions import validate
 from .lex import Lexer
+from .match import NodeList
 from .parse import Parser
 from .path import CompoundJSONPath
 from .path import JSONPath
@@ -338,6 +339,11 @@ def compare(self, left: object, operator: str, right: object) -> bool:
             `True` if the comparison between _left_ and _right_, with the
             given _operator_, is truthy. `False` otherwise.
         """
+        if isinstance(left, NodeList):
+            left = left.values_or_singular()
+        if isinstance(right, NodeList):
+            right = right.values_or_singular()
+
         if operator == "&&":
             return self.is_truthy(left) and self.is_truthy(right)
         if operator == "||":

jsonpath/filter.py

@@ -14,6 +14,7 @@
 from typing import TypeVar
 
 from .exceptions import JSONPathTypeError
+from .match import NodeList
 
 if TYPE_CHECKING:
     from .path import JSONPath
@@ -342,14 +343,12 @@ def evaluate(self, context: FilterContext) -> object:  # noqa: PLR0911
             return UNDEFINED
 
         try:
-            matches = self.path.findall(context.current)
+            matches = NodeList(self.path.finditer(context.current))
         except json.JSONDecodeError:  # this should never happen
             return UNDEFINED
 
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
     async def evaluate_async(self, context: FilterContext) -> object:  # noqa: PLR0911
@@ -363,14 +362,17 @@ async def evaluate_async(self, context: FilterContext) -> object:  # noqa: PLR09
             return UNDEFINED
 
         try:
-            matches = await self.path.findall_async(context.current)
+            matches = NodeList(
+                [
+                    match
+                    async for match in await self.path.finditer_async(context.current)
+                ]
+            )
         except json.JSONDecodeError:
             return UNDEFINED
 
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
 
@@ -381,19 +383,17 @@ def __str__(self) -> str:
         return str(self.path)
 
     def evaluate(self, context: FilterContext) -> object:
-        matches = self.path.findall(context.root)
+        matches = NodeList(self.path.finditer(context.root))
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
     async def evaluate_async(self, context: FilterContext) -> object:
-        matches = await self.path.findall_async(context.root)
+        matches = NodeList(
+            [match async for match in await self.path.finditer_async(context.root)]
+        )
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
 
@@ -405,19 +405,20 @@ def __str__(self) -> str:
         return "_" + path_repr[1:]
 
     def evaluate(self, context: FilterContext) -> object:
-        matches = self.path.findall(context.extra_context)
+        matches = NodeList(self.path.finditer(context.extra_context))
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
     async def evaluate_async(self, context: FilterContext) -> object:
-        matches = await self.path.findall_async(context.extra_context)
+        matches = NodeList(
+            [
+                match
+                async for match in await self.path.finditer_async(context.extra_context)
+            ]
+        )
         if not matches:
             return UNDEFINED
-        if len(matches) == 1:
-            return matches[0]
         return matches
 
 
@@ -440,15 +441,25 @@ def evaluate(self, context: FilterContext) -> object:
         except KeyError:
             return UNDEFINED
         args = [arg.evaluate(context) for arg in self.args]
-        return func(*args)
+        if getattr(func, "with_node_lists", False):
+            return func(*args)
+        return func(*self._unpack_node_lists(args))
 
     async def evaluate_async(self, context: FilterContext) -> object:
         try:
             func = context.env.function_extensions[self.name]
         except KeyError:
             return UNDEFINED
         args = [await arg.evaluate_async(context) for arg in self.args]
-        return func(*args)
+        if getattr(func, "with_node_lists", False):
+            return func(*args)
+        return func(*self._unpack_node_lists(args))
+
+    def _unpack_node_lists(self, args: List[object]) -> List[object]:
+        return [
+            obj.values_or_singular() if isinstance(obj, NodeList) else obj
+            for obj in args
+        ]
 
 
 class CurrentKey(FilterExpression):

jsonpath/function_extensions/count.py

@@ -1,26 +1,27 @@
 """The standard `count` function extension."""
-from collections.abc import Sized
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 from typing import List
-from typing import Optional
 
 from ..exceptions import JSONPathTypeError
 from ..filter import Literal
+from ..filter import Nil
 
 if TYPE_CHECKING:
     from ..env import JSONPathEnvironment
+    from ..match import NodeList
     from ..token import Token
 
 
 class Count:
     """The built-in `count` function."""
 
-    def __call__(self, obj: Sized) -> Optional[int]:
-        """Return an object's length, or `None` if the object does not have a length."""
-        try:
-            return len(obj)
-        except TypeError:
-            return None
+    with_node_lists = True
+
+    def __call__(self, node_list: NodeList) -> int:
+        """Return the number of nodes in the node list."""
+        return len(node_list)
 
     def validate(
         self,
@@ -35,7 +36,7 @@ def validate(
                 token=token,
             )
 
-        if isinstance(args[0], Literal):
+        if isinstance(args[0], (Literal, Nil)):
             raise JSONPathTypeError(
                 f"{token.value!r} requires a node list, "
                 f"found {args[0].__class__.__name__}",

jsonpath/match.py

@@ -76,3 +76,17 @@ def _truncate(val: str, num: int, end: str = "...") -> str:
     if len(words) < num:
         return " ".join(words)
     return " ".join(words[:num]) + end
+
+
+class NodeList(List[JSONPathMatch]):
+    """List of JSONPathMatch objects, analogous to the spec's nodelist."""
+
+    def values(self) -> List[object]:
+        """Return the values from this node list."""
+        return [match.obj for match in self]
+
+    def values_or_singular(self) -> object:
+        """Return the values from this node list."""
+        if len(self) == 1:
+            return self[0].obj
+        return [match.obj for match in self]

tests/compliance.py

@@ -55,6 +55,23 @@ class Case:
     "functions, match, result cannot be compared": "ignore",
     "functions, search, result cannot be compared": "ignore",
     "functions, value, result must be compared": "ignore",
+    "whitespace, selectors, space between root and bracket": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, newline between root and bracket": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, tab between root and bracket": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, return between root and bracket": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, space between bracket and bracket": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, space between root and dot": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, newline between root and dot": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, tab between root and dot": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, return between root and dot": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, space between dot and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, newline between dot and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, tab between dot and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, return between dot and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, space between recursive descent and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, newline between recursive descent and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, tab between recursive descent and name": "flexible whitespace policy",  # noqa: E501
+    "whitespace, selectors, return between recursive descent and name": "flexible whitespace policy",  # noqa: E501
 }