Consistent naming with RFC 9535

Author: jg-rp

README.md

@@ -26,18 +26,16 @@ TODO:
 
 ## Usage
 
-NOTE: If you're coming from [Python JSONPath](https://github.com/jg-rp/python-jsonpath), this API is similar but different. Neither implementation is guaranteed to be a drop-in replacement for the other.
+### `find(query, value)`
 
-### `query(path, data)`
+Apply JSONPath expression _query_ to _value_. _value_ should arbitrary, possible nested, Python dictionaries, lists, strings, integers, floats, Booleans or `None`, as you would get from [`json.load()`](https://docs.python.org/3/library/json.html#json.load).
 
-Apply JSONPath expression _path_ to _data_. _data_ should arbitrary, possible nested, Python dictionaries, lists, strings, integers, floats, booleans or `None`, as you would get from [`json.load()`](https://docs.python.org/3/library/json.html#json.load).
-
-A list of `JSONPathNode` instances is returned, one node for each value in _data_ matched by _path_. The returned list will be empty if there were no matches.
+A list of `JSONPathNode` instances is returned, one node for each value matched by _path_. The returned list will be empty if there were no matches.
 
 Each `JSONPathNode` has:
 
 - a `value` property, which is the JSON-like value associated with the node.
-- a `parts` property, which is a tuple of property names and array/list indices that were required to reach the node's value in the target JSON document.
+- a `location` property, which is a tuple of property names and array/list indexes that were required to reach the node's value in the target JSON document.
 - a `path()` method, which returns the normalized path to the node in the target JSON document.
 
 The returned list is a subclass of `list` with some helper methods.
@@ -48,9 +46,9 @@ The returned list is a subclass of `list` with some helper methods.
 **Example:**
 
 ```python
-from jsonpath_rfc9535 import query
+from jsonpath_rfc9535 import find
 
-data = {
+value = {
     "users": [
         {"name": "Sue", "score": 100},
         {"name": "John", "score": 86, "admin": True},
@@ -60,22 +58,16 @@ data = {
     "moderator": "John",
 }
 
-for node in query("$.users[?@.score > 85]", data):
+for node in find("$.users[?@.score > 85]", value):
     print(f"{node.value} at '{node.path()}'")
 
 # {'name': 'Sue', 'score': 100} at '$['users'][0]'
 # {'name': 'John', 'score': 86, 'admin': True} at '$['users'][1]'
 ```
 
-### findall(path, data)
-
-`findall()` accepts the same arguments as [`query()`](#querypath-data), but returns a list of value rather than a list of nodes.
-
-`findall()` is equivalent to `query("$.some.thing", data).values()`.
-
-### finditer(path, data)
+### finditer(query, value)
 
-`finditer()` accepts the same arguments as [`query()`](#querypath-data), but returns an iterator over `JSONPathNode` instances rather than a list. This could be useful if you're expecting a large number of results that you don't want to load into memory all at once.
+`finditer()` accepts the same arguments as [`find()`](#findquery-value), but returns an iterator over `JSONPathNode` instances rather than a list. This could be useful if you're expecting a large number of results that you don't want to load into memory all at once.
 
 ## License
 

jsonpath_rfc9535/__init__.py

@@ -1,20 +1,20 @@
-from .environment import JSONLikeData
 from .environment import JSONPathEnvironment
+from .environment import JSONValue
 from .exceptions import JSONPathError
 from .exceptions import JSONPathIndexError
 from .exceptions import JSONPathNameError
 from .exceptions import JSONPathRecursionError
 from .exceptions import JSONPathSyntaxError
 from .exceptions import JSONPathTypeError
-from .expressions import NOTHING
+from .filter_expressions import NOTHING
 from .lex import Lexer
 from .node import JSONPathNode
 from .node import JSONPathNodeList
 from .parse import Parser
-from .path import JSONPath
+from .query import JSONPathQuery
 
 __all__ = (
-    "JSONLikeData",
+    "JSONValue",
     "JSONPathEnvironment",
     "JSONPathError",
     "JSONPathIndexError",
@@ -27,12 +27,14 @@
     "JSONPathNode",
     "JSONPathNodeList",
     "Parser",
-    "JSONPath",
+    "JSONPathQuery",
+    "find",
+    "finditer",
+    "compile",
 )
 
 # For convenience
 DEFAULT_ENV = JSONPathEnvironment()
 compile = DEFAULT_ENV.compile  # noqa: A001
-findall = DEFAULT_ENV.findall
 finditer = DEFAULT_ENV.finditer
-query = DEFAULT_ENV.query
+find = DEFAULT_ENV.find

jsonpath_rfc9535/cli.py

@@ -1,4 +1,4 @@
-"""JSONPath, JSON Pointer and JSON Patch command line interface."""
+"""JSONPath command line interface."""
 
 import argparse
 import json
@@ -14,8 +14,8 @@
 
 _EPILOG = """\
 Example usage:
-  Find values in source.json matching a JSONPath query, write them to result.json.
-  $ jsonpath-rfc9535 path -q "$.foo['bar'][?@.baz > 1]" -f source.json -o result.json
+  Find values in source.json matching a JSONPath expression, output to result.json.
+  $ jsonpath-rfc9535 -q "$.foo['bar'][?@.baz > 1]" -f source.json -o result.json
 """
 
 
@@ -31,8 +31,7 @@ def setup_parser() -> argparse.ArgumentParser:  # noqa: D103
         prog="jsonpath-rfc9535",
         formatter_class=DescriptionHelpFormatter,
         description=(
-            "Find values in a JSON document given an "
-            "RFC 9535 JSONPath query expression."
+            "Find values in a JSON document given an RFC 9535 JSONPath expression."
         ),
         epilog=_EPILOG,
     )
@@ -63,14 +62,14 @@ def setup_parser() -> argparse.ArgumentParser:  # noqa: D103
     group.add_argument(
         "-q",
         "--query",
-        help="JSONPath query string.",
+        help="JSONPath expression as a string.",
     )
 
     group.add_argument(
         "-r",
-        "--path-file",
+        "--query-file",
         type=argparse.FileType(mode="r"),
-        help="Text file containing a JSONPath query.",
+        help="Text file containing a JSONPath expression.",
     )
 
     parser.add_argument(
@@ -98,9 +97,7 @@ def setup_parser() -> argparse.ArgumentParser:  # noqa: D103
     return parser
 
 
-def handle_path_command(args: argparse.Namespace) -> None:  # noqa: PLR0912
-    """Handle the `path` sub command."""
-    # Empty string is OK.
+def handle_path_command(args: argparse.Namespace) -> None:  # noqa: PLR0912, D103
     if args.query is not None:
         query = args.query
     else:
@@ -111,22 +108,22 @@ def handle_path_command(args: argparse.Namespace) -> None:  # noqa: PLR0912
     except JSONPathSyntaxError as err:
         if args.debug:
             raise
-        sys.stderr.write(f"json path syntax error: {err}\n")
+        sys.stderr.write(f"syntax error: {err}\n")
         sys.exit(1)
     except JSONPathTypeError as err:
         if args.debug:
             raise
-        sys.stderr.write(f"json path type error: {err}\n")
+        sys.stderr.write(f"type error: {err}\n")
         sys.exit(1)
     except JSONPathIndexError as err:
         if args.debug:
             raise
-        sys.stderr.write(f"json path index error: {err}\n")
+        sys.stderr.write(f"index error: {err}\n")
         sys.exit(1)
 
     try:
         data = json.load(args.file)
-        matches = path.findall(data)
+        values = path.find(data).values()
     except json.JSONDecodeError as err:
         if args.debug:
             raise
@@ -136,11 +133,11 @@ def handle_path_command(args: argparse.Namespace) -> None:  # noqa: PLR0912
         # Type errors are currently only occurring are compile-time.
         if args.debug:
             raise
-        sys.stderr.write(f"json path type error: {err}\n")
+        sys.stderr.write(f"type error: {err}\n")
         sys.exit(1)
 
     indent = INDENT if args.pretty else None
-    json.dump(matches, args.output, indent=indent)
+    json.dump(values, args.output, indent=indent)
 
 
 def main() -> None:

jsonpath_rfc9535/environment.py

@@ -18,26 +18,26 @@
 from . import function_extensions
 from .exceptions import JSONPathNameError
 from .exceptions import JSONPathTypeError
-from .expressions import ComparisonExpression
-from .expressions import FunctionExtension
-from .expressions import JSONPathLiteral
-from .expressions import LogicalExpression
-from .expressions import Path
+from .filter_expressions import ComparisonExpression
+from .filter_expressions import FilterQuery
+from .filter_expressions import FunctionExtension
+from .filter_expressions import JSONPathLiteral
+from .filter_expressions import LogicalExpression
 from .function_extensions import ExpressionType
 from .function_extensions import FilterFunction
 from .lex import tokenize
 from .parse import Parser
-from .path import JSONPath
+from .query import JSONPathQuery
 from .tokens import TokenStream
 
 if TYPE_CHECKING:
-    from .expressions import Expression
+    from .filter_expressions import Expression
     from .node import JSONPathNode
     from .node import JSONPathNodeList
     from .tokens import Token
 
 
-JSONLikeData = Union[
+JSONValue = Union[
     List[Any],
     Dict[str, Any],
     str,
@@ -84,86 +84,65 @@ def __init__(self) -> None:
 
         self.setup_function_extensions()
 
-    def compile(self, path: str) -> JSONPath:  # noqa: A003
-        """Prepare a path string ready for repeated matching against different data.
+    def compile(self, query: str) -> JSONPathQuery:  # noqa: A003
+        """Prepare a JSONPath expression ready for repeated application.
 
         Arguments:
-            path: A JSONPath query string.
+            query: A JSONPath expression.
 
         Returns:
-            A `JSONPath` ready to match against some data.
+            A `JSONPathQuery` ready to match against a JSON-like value.
 
         Raises:
-            JSONPathSyntaxError: If _path_ is invalid.
+            JSONPathSyntaxError: If _query_ is invalid.
             JSONPathTypeError: If filter functions are given arguments of an
                 unacceptable type.
         """
-        tokens = tokenize(path)
+        tokens = tokenize(query)
         stream = TokenStream(tokens)
-        return JSONPath(env=self, segments=tuple(self.parser.parse(stream)))
+        return JSONPathQuery(env=self, segments=tuple(self.parser.parse(stream)))
 
     def finditer(
         self,
-        path: str,
-        data: JSONLikeData,
+        query: str,
+        value: JSONValue,
     ) -> Iterable[JSONPathNode]:
-        """Generate `JSONPathNode` instances for each match of _path_ in _data_.
+        """Generate `JSONPathNode` instances for each match of _query_ in _value_.
 
         Arguments:
-            path: A JSONPath query string.
-            data: JSON-like data to query, as you'd get from `json.load`.
+            query: A JSONPath expression.
+            value: JSON-like data to query, as you'd get from `json.load`.
 
         Returns:
             An iterator yielding `JSONPathNode` objects for each match.
 
         Raises:
-            JSONPathSyntaxError: If the path is invalid.
+            JSONPathSyntaxError: If the query is invalid.
             JSONPathTypeError: If a filter expression attempts to use types in
                 an incompatible way.
         """
-        return self.compile(path).finditer(data)
+        return self.compile(query).finditer(value)
 
-    def findall(
+    def find(
         self,
-        path: str,
-        data: JSONLikeData,
-    ) -> List[object]:
-        """Find all values in _data_ matching JSONPath query _path_.
-
-        Arguments:
-            path: A JSONPath query string.
-            data: JSON-like data to query, as you'd get from `json.load`.
-
-        Returns:
-            A list of matched values. If there are no matches, the list will be empty.
-
-        Raises:
-            JSONPathSyntaxError: If the path is invalid.
-            JSONPathTypeError: If a filter expression attempts to use types in
-                an incompatible way.
-        """
-        return self.compile(path).findall(data)
-
-    def query(
-        self,
-        path: str,
-        data: JSONLikeData,
+        query: str,
+        value: JSONValue,
     ) -> JSONPathNodeList:
-        """Apply the JSONPath query _path_ to JSON-like _data_.
+        """Apply the JSONPath expression _query_ to JSON-like data _value_.
 
         Arguments:
-            path: A JSONPath query string.
-            data: JSON-like data to query, as you'd get from `json.load`.
+            query: A JSONPath expression.
+            value: JSON-like data to query, as you'd get from `json.load`.
 
         Returns:
             A list of `JSONPathNode` instance.
 
         Raises:
-            JSONPathSyntaxError: If the path is invalid.
+            JSONPathSyntaxError: If the query is invalid.
             JSONPathTypeError: If a filter expression attempts to use types in
                 an incompatible way.
         """
-        return self.compile(path).query(data)
+        return self.compile(query).find(value)
 
     def setup_function_extensions(self) -> None:
         """Initialize function extensions."""
@@ -176,11 +155,7 @@ def setup_function_extensions(self) -> None:
     def validate_function_extension_signature(
         self, token: Token, args: List[Any]
     ) -> List[Any]:
-        """Compile-time validation of function extension arguments.
-
-        RFC 9535 requires us to reject paths that use filter functions with
-        too many or too few arguments.
-        """
+        """Compile-time validation of function extension arguments."""
         try:
             func = self.function_extensions[token.value]
         except KeyError as err:
@@ -211,7 +186,7 @@ def check_well_typedness(
             if typ == ExpressionType.VALUE:
                 if not (
                     isinstance(arg, JSONPathLiteral)
-                    or (isinstance(arg, Path) and arg.path.singular_query())
+                    or (isinstance(arg, FilterQuery) and arg.query.singular_query())
                     or (self._function_return_type(arg) == ExpressionType.VALUE)
                 ):
                     raise JSONPathTypeError(
@@ -220,14 +195,14 @@ def check_well_typedness(
                     )
             elif typ == ExpressionType.LOGICAL:
                 if not isinstance(
-                    arg, (Path, (LogicalExpression, ComparisonExpression))
+                    arg, (FilterQuery, (LogicalExpression, ComparisonExpression))
                 ):
                     raise JSONPathTypeError(
                         f"{token.value}() argument {idx} must be of LogicalType",
                         token=token,
                     )
             elif typ == ExpressionType.NODES and not (
-                isinstance(arg, Path)
+                isinstance(arg, FilterQuery)
                 or self._function_return_type(arg) == ExpressionType.NODES
             ):
                 raise JSONPathTypeError(

jsonpath_rfc9535/exceptions.py

@@ -32,7 +32,7 @@ def __str__(self) -> str:
 
 
 class JSONPathSyntaxError(JSONPathError):
-    """An exception raised when a error occurs during JSONPath query parsing.
+    """An exception raised when a error occurs during JSONPath expression parsing.
 
     Arguments:
         args: Arguments passed to `Exception`.