feat: add current key/index identifier, closes #5

Author: jg-rp

CHANGELOG.md

@@ -4,13 +4,14 @@
 
 **Breaking changes**
 
-- The "extra context" identifier now defaults to `_`. Previously it defaulted to `#`, but it has been decided that `#` is better suited as a "keys" or "properties" identifier.
+- The "extra filter context" identifier now defaults to `_`. Previously it defaulted to `#`, but it has been decided that `#` is better suited as a current key/property or index identifier.
 
 **Features**
 
 - Added a non-standard keys/properties selector (`~`).
 - Added a non-standard `typeof()` filter function. `type()` is an alias for `typeof()`.
 - Added a non-standard `isinstance()` filter function. `is()` is an alias for `isinstance()`.
+- Added a current key/property or index identifier. When filtering a mapping, `#` will hold key associated with the current node (`@`). When filtering a sequence, `#` will hold the current index.
 
 **IETF JSONPath Draft compliance**
 

docs/syntax.md

@@ -120,9 +120,9 @@ $..title
 $...title
 ```
 
-### Filters (`[?(EXPRESSION)]`)
+### Filters (`[?EXPRESSION]`)
 
-Filters allow you to remove nodes from a selection using a Boolean expression. Within a filter, `@` refers to the current node and `$` refers to the root node in the target document. `@` and `$` can be used to select nodes as part of the expression. Since version 0.3.0, the parentheses are optional, as per the IETF JSONPath draft. These two examples are equivalent.
+Filters allow you to remove nodes from a selection using a Boolean expression. When filtering a mapping-like object, `#` references the current key/property and `@` references the current value associated with `#`. When filtering a sequence-like object, `@` references the current item and `#` will hold the item's index in the sequence.
 
 ```text
 $..products[?(@.price < $.price_cap)]
@@ -187,5 +187,6 @@ And this is a list of features that are uncommon or unique to Python JSONPath.
 
 - `|` is a union operator, where matches from two or more JSONPaths are combined. This is not part of the Python API, but built-in to the JSONPath syntax.
 - `&` is an intersection operator, where we exclude matches that don't exist in both left and right paths. This is not part of the Python API, but built-in to the JSONPath syntax.
+- `#` is the current key/property or index identifier when filtering a mapping or sequence.
 - `_` is a filter context selector. With usage similar to `$` and `@`, `_` exposes arbitrary data from the `filter_context` argument to `findall()` and `finditer()`.
 - `~` is a "keys" or "properties" selector.

jsonpath/env.py

@@ -72,7 +72,10 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
             data. Defaults to `"_"`.
         intersection_token (str): The pattern used as the intersection operator.
             Defaults to `"$"`.
-        keys_token (str): The pattern used as the "keys" selector. Defaults to `"~"`.
+        key_token (str): The pattern used to identify the current key or index when
+            filtering a, mapping or sequence. Defaults to `"#"`.
+        keys_selector_token (str): The pattern used as the "keys" selector. Defaults to
+            `"~"`.
         lexer_class: The lexer to use when tokenizing path strings.
         max_int_index (int): The maximum integer allowed when selecting array items by
             index. Defaults to `(2**53) - 1`.
@@ -88,12 +91,13 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
 
     # These should be unescaped strings. `re.escape` will be called
     # on them automatically when compiling lexer rules.
+    filter_context_token = "_"
     intersection_token = "&"
-    keys_token = "~"
+    key_token = "#"
+    keys_selector_token = "~"
     root_token = "$"
     self_token = "@"
     union_token = "|"
-    filter_context_token = "_"
 
     max_int_index = (2**53) - 1
     min_int_index = -(2**53) + 1

jsonpath/filter.py

@@ -449,3 +449,20 @@ async def evaluate_async(self, context: FilterContext) -> object:
             return UNDEFINED
         args = [await arg.evaluate_async(context) for arg in self.args]
         return func(*args)
+
+
+class CurrentKey(FilterExpression):
+    """The key/property or index associated with the current object."""
+
+    __slots__ = ()
+
+    def evaluate(self, context: FilterContext) -> object:
+        if context.current_key is None:
+            return UNDEFINED
+        return context.current_key
+
+    async def evaluate_async(self, context: FilterContext) -> object:
+        return self.evaluate(context)
+
+
+CURRENT_KEY = CurrentKey()

jsonpath/lex.py

@@ -31,6 +31,7 @@
 from .token import TOKEN_INDEX
 from .token import TOKEN_INT
 from .token import TOKEN_INTERSECTION
+from .token import TOKEN_KEY
 from .token import TOKEN_KEYS
 from .token import TOKEN_LE
 from .token import TOKEN_LG
@@ -145,10 +146,11 @@ def compile_rules(self) -> Pattern[str]:
             (TOKEN_OR, self.bool_or_pattern),
             (TOKEN_ROOT, re.escape(self.env.root_token)),
             (TOKEN_SELF, re.escape(self.env.self_token)),
+            (TOKEN_KEY, re.escape(self.env.key_token)),
             (TOKEN_UNION, re.escape(self.env.union_token)),
             (TOKEN_INTERSECTION, re.escape(self.env.intersection_token)),
             (TOKEN_FILTER_CONTEXT, re.escape(self.env.filter_context_token)),
-            (TOKEN_KEYS, re.escape(self.env.keys_token)),
+            (TOKEN_KEYS, re.escape(self.env.keys_selector_token)),
             (TOKEN_IN, r"in"),
             (TOKEN_TRUE, r"[Tt]rue"),
             (TOKEN_FALSE, r"[Ff]alse"),

jsonpath/parse.py

@@ -12,6 +12,7 @@
 from typing import Union
 
 from .exceptions import JSONPathSyntaxError
+from .filter import CURRENT_KEY
 from .filter import FALSE
 from .filter import NIL
 from .filter import TRUE
@@ -58,6 +59,7 @@
 from .token import TOKEN_INDEX
 from .token import TOKEN_INT
 from .token import TOKEN_INTERSECTION
+from .token import TOKEN_KEY
 from .token import TOKEN_KEYS
 from .token import TOKEN_LE
 from .token import TOKEN_LG
@@ -198,6 +200,7 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
             TOKEN_FALSE: self.parse_boolean,
             TOKEN_FLOAT: self.parse_float_literal,
             TOKEN_INT: self.parse_integer_literal,
+            TOKEN_KEY: self.parse_current_key,
             TOKEN_LIST_START: self.parse_list_literal,
             TOKEN_LPAREN: self.parse_grouped_expression,
             TOKEN_MISSING: self.parse_undefined,
@@ -232,6 +235,7 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
             TOKEN_FALSE: self.parse_boolean,
             TOKEN_FLOAT: self.parse_float_literal,
             TOKEN_INT: self.parse_integer_literal,
+            TOKEN_KEY: self.parse_current_key,
             TOKEN_NIL: self.parse_nil,
             TOKEN_NONE: self.parse_nil,
             TOKEN_NULL: self.parse_nil,
@@ -507,6 +511,9 @@ def parse_self_path(self, stream: TokenStream) -> FilterExpression:
             JSONPath(env=self.env, selectors=self.parse_path(stream, in_filter=True))
         )
 
+    def parse_current_key(self, _: TokenStream) -> FilterExpression:
+        return CURRENT_KEY
+
     def parse_filter_context_path(self, stream: TokenStream) -> FilterExpression:
         stream.next_token()
         return FilterContextPath(

jsonpath/selectors.py

@@ -196,7 +196,7 @@ class KeysSelector(JSONPathSelector):
     __slots__ = ()
 
     def __str__(self) -> str:
-        return f"[{self.env.keys_token}]"
+        return f"[{self.env.keys_selector_token}]"
 
     def _keys(self, match: JSONPathMatch) -> Iterable[JSONPathMatch]:
         if isinstance(match.obj, Mapping):
@@ -205,8 +205,8 @@ def _keys(self, match: JSONPathMatch) -> Iterable[JSONPathMatch]:
                     filter_context=match.filter_context(),
                     obj=key,
                     parent=match,
-                    parts=match.parts + (self.env.keys_token, i),
-                    path=f"{match.path}[{self.env.keys_token}][{i}]",
+                    parts=match.parts + (self.env.keys_selector_token, i),
+                    path=f"{match.path}[{self.env.keys_selector_token}][{i}]",
                     root=match.root,
                 )
                 match.add_child(_match)
@@ -468,7 +468,7 @@ def __str__(self) -> str:
             elif isinstance(item, WildSelector):
                 buf.append("*")
             elif isinstance(item, KeysSelector):
-                buf.append(self.env.keys_token)
+                buf.append(self.env.keys_selector_token)
             else:
                 buf.append(str(item.index))
         return f"[{', '.join(buf)}]"
@@ -516,6 +516,7 @@ def resolve(  # noqa: PLR0912
                         current=val,
                         root=match.root,
                         extra_context=match.filter_context(),
+                        current_key=key,
                     )
                     try:
                         if self.expression.evaluate(context):
@@ -541,6 +542,7 @@ def resolve(  # noqa: PLR0912
                         current=obj,
                         root=match.root,
                         extra_context=match.filter_context(),
+                        current_key=i,
                     )
                     try:
                         if self.expression.evaluate(context):
@@ -570,6 +572,7 @@ async def resolve_async(  # noqa: PLR0912
                         current=val,
                         root=match.root,
                         extra_context=match.filter_context(),
+                        current_key=key,
                     )
 
                     try:
@@ -598,6 +601,7 @@ async def resolve_async(  # noqa: PLR0912
                         current=obj,
                         root=match.root,
                         extra_context=match.filter_context(),
+                        current_key=i,
                     )
 
                     try:
@@ -622,7 +626,7 @@ async def resolve_async(  # noqa: PLR0912
 class FilterContext:
     """A filter expression context."""
 
-    __slots__ = ("current", "env", "root", "extra_context")
+    __slots__ = ("current", "current_key", "env", "root", "extra_context")
 
     def __init__(
         self,
@@ -631,11 +635,13 @@ def __init__(
         current: object,
         root: Union[Sequence[Any], Mapping[str, Any]],
         extra_context: Optional[Mapping[str, Any]] = None,
+        current_key: Union[str, int, None] = None,
     ) -> None:
         self.env = env
         self.current = current
         self.root = root
         self.extra_context = extra_context or {}
+        self.current_key = current_key
 
     def __str__(self) -> str:
         return (

jsonpath/token.py

@@ -19,6 +19,7 @@
 TOKEN_FILTER_START = sys.intern("FILTER_START")
 TOKEN_IDENT = sys.intern("IDENT")
 TOKEN_INDEX = sys.intern("IDX")
+TOKEN_KEY = sys.intern("KEY")
 TOKEN_KEYS = sys.intern("KEYS")
 TOKEN_RBRACKET = sys.intern("RBRACKET")
 TOKEN_BARE_PROPERTY = sys.intern("BARE_PROPERTY")

tests/test_find.py

@@ -45,6 +45,18 @@ class Case:
         data={"some": ["thing", "else"]},
         want=[],
     ),
+    Case(
+        description="match key pattern",
+        path="$.some[?match(#, 'thing[0-9]+')]",
+        data={
+            "some": {
+                "thing1": {"foo": 1},
+                "thing2": {"foo": 2},
+                "other": {"foo": 3},
+            }
+        },
+        want=[{"foo": 1}, {"foo": 2}],
+    ),
 ]