chore: change the default "extra context" identifier to _, see #5

Author: jg-rp

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Version 0.6.0
 
+**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.
+
 **Features**
 
 - Added a non-standard keys/properties selector (`~`).
@@ -25,7 +29,7 @@
 
 **Fixes**
 
-- Fixed a bug where the current object selector (`@`) would evaluate to `undefined` when a filter is applied to an array of strings.
+- Fixed a bug where the current object identifier (`@`) would evaluate to `undefined` when a filter is applied to an array of strings.
 - Compound paths that have a trailing `|` or `&` now raise a `JSONPathSyntaxError`.
 
 **IETF JSONPath Draft compliance**

docs/syntax.md

@@ -187,5 +187,5 @@ 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 a filter context selector. With usage similar to `$` and `@`, `#` exposes arbitrary data from the `filter_context` argument to `findall()` and `finditer()`.
+- `_` 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

@@ -55,7 +55,7 @@ class JSONPathEnvironment:
     and overriding class attributes and/or methods. Some of these
     customizations include:
 
-    - Changing the root (`$`), self (`@`) or filter context (`#`) token with
+    - Changing the root (`$`), self (`@`) or filter context (`_`) token with
       class attributes `root_token`, `self_token` and `filter_context_token`.
     - Registering a custom lexer or parser with the class attributes
       `lexer_class` or `parser_class`. `lexer_class` must be a subclass of
@@ -69,7 +69,7 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
 
     Attributes:
         filter_context_token (str): The pattern used to select extra filter context
-            data. Defaults to `"#"`.
+            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 `"~"`.
@@ -93,7 +93,7 @@ class attributes `root_token`, `self_token` and `filter_context_token`.
     root_token = "$"
     self_token = "@"
     union_token = "|"
-    filter_context_token = "#"
+    filter_context_token = "_"
 
     max_int_index = (2**53) - 1
     min_int_index = -(2**53) + 1

jsonpath/filter.py

@@ -402,7 +402,7 @@ class FilterContextPath(Path):
 
     def __str__(self) -> str:
         path_repr = str(self.path)
-        return "#" + path_repr[1:]
+        return "_" + path_repr[1:]
 
     def evaluate(self, context: FilterContext) -> object:
         matches = self.path.findall(context.extra_context)

tests/test_env.py

@@ -27,7 +27,7 @@ def test_find_all_from_json_string(env: JSONPathEnvironment) -> None:
 def test_find_all_with_extra_filter_context(env: JSONPathEnvironment) -> None:
     """Test that we can pass extra filter context to findall."""
     rv = env.findall(
-        "$[?(@.some == #.other)]",
+        "$[?(@.some == _.other)]",
         {"foo": {"some": 1, "thing": 2}},
         filter_context={"other": 1},
     )
@@ -49,7 +49,7 @@ def test_find_iter_from_json_string(env: JSONPathEnvironment) -> None:
 def test_find_iter_with_extra_filter_context(env: JSONPathEnvironment) -> None:
     """Test that we can pass extra filter context to finditer."""
     matches = env.finditer(
-        "$[?(@.some == #.other)]",
+        "$[?(@.some == _.other)]",
         {"foo": {"some": 1, "thing": 2}},
         filter_context={"other": 1},
     )
@@ -79,7 +79,7 @@ def test_find_all_async_with_extra_filter_context(env: JSONPathEnvironment) -> N
 
     async def coro() -> List[object]:
         return await env.findall_async(
-            "$[?(@.some == #.other)]",
+            "$[?(@.some == _.other)]",
             {"foo": {"some": 1, "thing": 2}},
             filter_context={"other": 1},
         )
@@ -112,7 +112,7 @@ def test_find_iter_async_with_extra_filter_context(env: JSONPathEnvironment) ->
 
     async def coro() -> List[object]:
         matches = await env.finditer_async(
-            "$[?(@.some == #.other)]",
+            "$[?(@.some == _.other)]",
             {"foo": {"some": 1, "thing": 2}},
             filter_context={"other": 1},
         )