Merge pull request #56 from jg-rp/doc-comments

Improve docs and doc comments.

Author: jg-rp

docs/syntax.md

@@ -199,7 +199,6 @@ This is a list of things that you might find in other JSONPath implementation th
 - We do not support arithmetic in filter expression.
 - We don't allow dotted array indices. An array index must be surrounded by square brackets.
 - Python JSONPath is strictly read only. There are no update "selectors", but we do provide methods for converting `JSONPathMatch` instances to `JSONPointer`s, and a `JSONPatch` builder API for modifying JSON-like data structures using said pointers.
-- We don't attempt to handle JSON documents without a top-level array or object (or equivalent Python objects).
 
 And this is a list of areas where we deviate from [RFC 9535](https://datatracker.ietf.org/doc/html/rfc9535).
 
@@ -209,14 +208,18 @@ And this is a list of areas where we deviate from [RFC 9535](https://datatracker
 - We don't require the recursive descent segment to have a selector. `$..` is equivalent to `$..*`.
 - We support explicit comparisons to `undefined` as well as implicit existence tests.
 - Float literals without a fractional digit are OK. `1.` is equivalent to `1.0`.
-- We treat literals (such as `true` and `false`) as valid "basic" expressions. So `$[?true || false]` does not raise a syntax error, which is and invalid query according to RFC 9535.
+- We treat literals (such as `true` and `false`) as valid "basic" expressions. For example, `$[?true || false]`, without an existence test or comparison either side of logical _or_, does not raise a syntax error.
+- By default, `and` is equivalent to `&&` and `or` is equivalent to `||`.
+- `none` and `nil` are aliases for `null`.
+- `null` (and its aliases), `true` and `false` can start with an upper or lower case letter.
 
 And this is a list of features that are uncommon or unique to Python JSONPath.
 
 - We support membership operators `in` and `contains`, plus list/array literals.
 - `|` 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 filter context identifier. With usage similar to `$` and `@`, `_` exposes arbitrary data from the `filter_context` argument to `findall()` and `finditer()`.
 - `~` is a "keys" or "properties" selector.
 - `^` is a "fake root" identifier. It is equivalent to `$`, but wraps the target JSON document in a single-element array, so the root value can be conditionally selected with a filter selector.
+- `=~` is the the regex match operator, matching a value to a JavaScript-style regex literal.

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 @@
 
 
 class JSONPathSelector(ABC):
-    """Base class for all JSONPath selectors."""
+    """Base class for all JSONPath segments and selectors."""
 
     __slots__ = ("env", "token")
 
@@ -38,7 +38,17 @@ def __init__(self, *, env: JSONPathEnvironment, token: Token) -> None:
 
     @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 @@ def resolve_async(
 
 
 class PropertySelector(JSONPathSelector):
-    """A JSONPath property."""
+    """A shorthand or bracketed property selector."""
 
     __slots__ = ("name", "shorthand")
 
@@ -115,7 +125,12 @@ async def resolve_async(
 
 
 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 @@ async def resolve_async(
 
 
 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 @@ async def resolve_async(
 
 
 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 @@ async def resolve_async(
 
 
 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 @@ async def resolve_async(
 
 
 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 @@ async def resolve_async(  # noqa: PLR0912
 
 
 class FilterContext:
-    """A filter expression context."""
+    """Contextual information and data for evaluating a filter expression."""
 
     __slots__ = (
         "current_key",