dotted-notation 0.49.2__tar.gz → 0.49.4__tar.gz

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.49.4]
+
+### Fixed
+- `update` through `~` around a filtered or recursive op,
+  `[(~*&k=v#, +)]` or `~*a.x`, raised `TypeError` once something
+  matched (#65). It now keeps what the `~` matches as it is and, as
+  elsewhere, still updates the path after it: `[(~*&k=1#, +)].x`
+  updates `x` in the matching items.
+
+## [0.49.3]
+
+### Added
+- A slice bound may be a reference or a substitution: `b[:$$(i)]`,
+  `b[$(n):]`, `b[$0:$1]`, `b[::$$(step)]`. It resolves as a slot's does,
+  so `b[:$$(i)]|sum` is a running total with `i` bound per element
+  (#64). A reference that does not resolve matches nothing.
+- A reference may hold parentheses of its own: `$$()` runs to the `)`
+  that closes it, so a group or a pack works inside, `$$(a.(b,c))`,
+  `$$((a[*];))`. A `)` inside quotes does not count.
+- A reference inside a container value, `=[1, $$(x)]`, `={"k": $$(x)}`,
+  `="ab"...$$(x)`, `=(1, $$(x))`, resolves as a whole guard or filter
+  value does. One whose path is a pattern branches the container, once
+  per value; pack it, `$$((x[*];))`, to compare with the tuple instead.
+  In a string or bytes glob it must resolve to `str` or `bytes`, else
+  `TypeError`; `$$(x|str)` coerces.
+- A reference in a filter key part, `[*&$$(field)="bob"]`,
+  `[*&tags[$$(^^i)]="b"]`, `[*&xs[:$$(^^n)]=[1]]`, resolves against the
+  node that part is looked up in, as `^`; in the first part that is the
+  item. A pattern reference tries each key it resolves to.
+
+### Fixed
+- An unresolved substitution inside a container value, `=[1, $(x)]`,
+  makes the path an unresolved template, so `get` and the rest raise
+  `TypeError` as for any other unresolved `$N`, rather than matching
+  nothing.
+- Resolving a recursive op's substitutions, `**&x=$(v)` or
+  `*($(k), [*])&x=1`, now resolves those in its filters, keeps the
+  filters, and keeps `*?`/`**?` first-match. `is_template` and
+  `is_reference` see a recursive op's accessors and filters, so an
+  unresolved `$N` there raises and a `$$(^^…)` gets its parents.
+- Resolving `$N` in a string or bytes glob no longer turns a `$$(path)`
+  part into the literal text of its path.
+- A slice's repr shows its step, `[1:5:2]`, rather than repeating its
+  stop.
+- `make native` on macOS, and on Linux from Python 3.14: `setup.py`
+  runs `setup()` under a `__main__` guard, since Cython's spawned
+  workers import it again.
+
 ## [0.49.2]
 
 ### Added

{dotted_notation-0.49.2/dotted_notation.egg-info → dotted_notation-0.49.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.2
+Version: 0.49.4
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.6
@@ -1163,6 +1164,14 @@ Dotted slicing works like python slicing and all that entails.
     >>> dotted.get(d, '*.there[1:]')
     ([2, 3], [5, 6])
 
+A bound may be a reference or a substitution, resolved the way a slot's is:
+
+    >>> d = {'b': [3, 0, 5], 'i': 2}
+    >>> dotted.get(d, 'b[:$$(i)]')
+    [3, 0]
+    >>> dotted.get(d, 'b[$(n):]', bindings={'n': 1})
+    [0, 5]
+
 <a id="dot-notation-for-sequence-indexing"></a>
 ### Dot notation for sequence indexing
 
@@ -1641,6 +1650,23 @@ as do the transforms before a guard:
     >>> dotted.get(data, '*|mul:$$(scale)=20')
     (2,)
 
+So does a reference inside a container value. One whose path is a pattern
+branches the container, once per value; pack it, `(…;)`, to compare with the
+tuple instead:
+
+    >>> data = {'want': [2, 3], 'items': [[1, 2], [1, 4], [1, (2, 3)]]}
+    >>> dotted.get(data, 'items[*]=[1, $$(want[*])]')
+    ([1, 2],)
+    >>> dotted.get(data, 'items[*]=[1, $$((want[*];))]')
+    ([1, (2, 3)],)
+
+A filter key may hold references too. In each part of the key, `^` is the
+node that part is looked up in, so in the first part it is the item:
+
+    >>> data = {'field': 'name', 'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(data, 'users[*&$$(field)="bob"]')
+    ({'name': 'bob'},)
+
 With `update`, the transforms apply to the value being set, so `^` is that
 value:
 

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/README.md

@@ -1116,6 +1116,14 @@ Dotted slicing works like python slicing and all that entails.
     >>> dotted.get(d, '*.there[1:]')
     ([2, 3], [5, 6])
 
+A bound may be a reference or a substitution, resolved the way a slot's is:
+
+    >>> d = {'b': [3, 0, 5], 'i': 2}
+    >>> dotted.get(d, 'b[:$$(i)]')
+    [3, 0]
+    >>> dotted.get(d, 'b[$(n):]', bindings={'n': 1})
+    [0, 5]
+
 <a id="dot-notation-for-sequence-indexing"></a>
 ### Dot notation for sequence indexing
 
@@ -1594,6 +1602,23 @@ as do the transforms before a guard:
     >>> dotted.get(data, '*|mul:$$(scale)=20')
     (2,)
 
+So does a reference inside a container value. One whose path is a pattern
+branches the container, once per value; pack it, `(…;)`, to compare with the
+tuple instead:
+
+    >>> data = {'want': [2, 3], 'items': [[1, 2], [1, 4], [1, (2, 3)]]}
+    >>> dotted.get(data, 'items[*]=[1, $$(want[*])]')
+    ([1, 2],)
+    >>> dotted.get(data, 'items[*]=[1, $$((want[*];))]')
+    ([1, (2, 3)],)
+
+A filter key may hold references too. In each part of the key, `^` is the
+node that part is looked up in, so in the first part it is the item:
+
+    >>> data = {'field': 'name', 'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(data, 'users[*&$$(field)="bob"]')
+    ({'name': 'bob'},)
+
 With `update`, the transforms apply to the value being set, so `^` is that
 value:
 

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/access.py

@@ -994,12 +994,49 @@ class Slice(SimpleOp):
         start, stop, step = self.args
         m = [s(start), s(stop)]
         if step is not None:
-            m += [s(stop)]
+            m += [s(step)]
         return '[' + ':'.join(m) + ']'
     def is_pattern(self):
         return False
     def is_slice(self):
         return True
+    def is_template(self):
+        """
+        True if a bound is an unresolved substitution.
+        """
+        return any(isinstance(a, matchers.Subst) for a in self.args)
+    def is_reference(self):
+        """
+        True if a bound is an internal reference.
+        """
+        return any(isinstance(a, matchers.Reference) for a in self.args)
+    def resolve(self, bindings, partial=False):
+        """
+        Resolve $N in the bounds.
+        """
+        if not self.is_template():
+            return self
+        args = []
+        for a in self.args:
+            r = a.resolve(bindings, partial) if isinstance(a, matchers.Subst) else a
+            # a resolved substitution is a ResolvedValue; the bound is its value
+            args.append(r.value if isinstance(r, matchers.ResolvedValue) else r)
+        return self.concrete(slice(*args))
+    def _resolved(self, node=None, settings=base.SETTINGS):
+        """
+        This slice with its $$(path) bounds resolved, or None if one does
+        not resolve.
+        """
+        args = []
+        for a in self.args:
+            if not isinstance(a, matchers.Reference):
+                args.append(a)
+                continue
+            try:
+                args.append(settings.resolve(a, node, settings.parents or ()))
+            except KeyError:
+                return None
+        return self.concrete(slice(*args))
     def operator(self, top=False):
         return str(self)
     def slice(self, node=None):
@@ -1012,6 +1049,8 @@ class Slice(SimpleOp):
         Calculate cardinality of a slice; don't both dealing with countably infinite
         set arithmetic, instead just pick a suitably large integer
         """
+        if self.is_template() or self.is_reference():
+            return 0
         s = self.slice(node)
         start = s.start or 0
         stop = s.stop or '+'
@@ -1023,7 +1062,12 @@ class Slice(SimpleOp):
         return max(0, int((stop - start) / step))
 
     def keys(self, node, settings=base.SETTINGS):
-        return (self.slice(node),)
+        if not self.is_reference():
+            return (self.slice(node),)
+        r = self._resolved(node=node, settings=settings)
+        if r is None:
+            return ()
+        return r.keys(node, settings=settings)
     def items(self, node, settings=base.SETTINGS, filtered=True):
         return self._slice_items(node, settings)
     def _slice_items(self, node, settings):
@@ -1076,6 +1120,28 @@ class Slice(SimpleOp):
     def upsert(self, node, val):
         return self.update(node, self.slice(node), val)
 
+    def do_update(self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=False, settings=base.SETTINGS):
+        """
+        Resolve references before updating.
+        """
+        if not self.is_reference():
+            return super().do_update(ops, node, val, has_defaults, _path, nop, nop_from_unwrap=nop_from_unwrap, settings=settings)
+        r = self._resolved(node=node, settings=settings)
+        if r is None:
+            return node
+        return r.do_update(ops, node, val, has_defaults, _path, nop, nop_from_unwrap=nop_from_unwrap, settings=settings)
+
+    def do_remove(self, ops, node, val, nop, settings=base.SETTINGS):
+        """
+        Resolve references before removing.
+        """
+        if not self.is_reference():
+            return super().do_remove(ops, node, val, nop, settings=settings)
+        r = self._resolved(node=node, settings=settings)
+        if r is None:
+            return node
+        return r.do_remove(ops, node, val, nop, settings=settings)
+
     def pop(self, node, key):
         try:
             del node[key]

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/containers.py

@@ -25,7 +25,7 @@ Type prefix semantics:
     fs{...}   frozenset only
 """
 import re
-from itertools import combinations
+from itertools import combinations, product
 
 from . import utils
 from . import base
@@ -46,11 +46,91 @@ def _element_matches(pattern, val):
     return any(True for _ in pattern.matches((val,)))
 
 
+def _holds(items, method):
+    """
+    True if an item, or a part of a (key, value) dict entry, answers True
+    to method: 'is_template' or 'is_reference'.
+    """
+    for x in items:
+        if isinstance(x, tuple):
+            if _holds(x, method):
+                return True
+            continue
+        test = getattr(x, method, None)
+        if test is not None and test():
+            return True
+    return False
+
+
+def _values(ref, settings, node, parents):
+    """
+    What reference ref resolves to, as a tuple: its value, or each value
+    of a pattern reference.
+    """
+    val = settings.resolve(ref, node, parents)
+    if ref.is_pattern():
+        return tuple(val)
+    return (val,)
+
+
+def _alternatives(e, settings, node, parents):
+    """
+    The forms element e takes once its references resolve: a Const per
+    value of a reference, a nested container's branches, each pairing of
+    a dict entry's key and value forms; just e when it holds none.
+    """
+    if isinstance(e, tuple):
+        return tuple(product(*(_alternatives(p, settings, node, parents) for p in e)))
+    if not _holds((e,), 'is_reference'):
+        return (e,)
+    if isinstance(e, matchers.Reference):
+        return tuple(matchers.Const(v) for v in _values(e, settings, node, parents))
+    return e.branches(settings, node, parents)
+
+
+def _fragments(part, typ, owner, settings, node, parents):
+    """
+    The fragments a string or bytes glob part stands for: a reference's
+    values, each of which must be a typ; any other part as it is.
+    """
+    if not isinstance(part, matchers.Reference):
+        return (part,)
+    vals = _values(part, settings, node, parents)
+    for v in vals:
+        if not isinstance(v, typ):
+            raise TypeError(
+                f'{owner} requires {typ.__name__}, got {type(v).__name__}'
+                f' — use $$(path|{typ.__name__}) to coerce')
+    return vals
+
+
+class ContainerOp(base.Op):
+    """
+    Base of the container value patterns. Their args are their parts, so
+    whether one holds a substitution or a reference is read from those.
+
+    A reference inside resolves as the whole value's would (see
+    results.guard_matcher). One that is a pattern branches the container:
+    branches() gives the container once per combination of values.
+    """
+    def is_template(self):
+        """
+        True if a part holds an unresolved substitution.
+        """
+        return _holds(self.args, 'is_template')
+
+    def is_reference(self):
+        """
+        True if a part holds an internal reference.
+        """
+        return _holds(self.args, 'is_reference')
+
+
 # ---------------------------------------------------------------------------
 # Glob — the ... element
 # ---------------------------------------------------------------------------
 
-class Glob(base.Op):
+class Glob(ContainerOp):
     """
     The ... element: zero or more values with optional pattern and count.
 
@@ -87,6 +167,14 @@ class Glob(base.Op):
             return self
         return Glob(new_pat, self.min_count, self.max_count)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This glob once per form of its pattern (see ContainerOp).
+        """
+        return tuple(
+            Glob(p, self.min_count, self.max_count)
+            for p in _alternatives(self.pattern, settings, node, parents))
+
     def __repr__(self):
         parts = ['...']
         if self.pattern is not None:
@@ -105,7 +193,7 @@ class Glob(base.Op):
 # DictGlobEntry — a glob entry in a dict pattern
 # ---------------------------------------------------------------------------
 
-class DictGlobEntry(base.Op):
+class DictGlobEntry(ContainerOp):
     """
     A glob entry in a dict: glob on key side with value pattern.
 
@@ -141,6 +229,15 @@ class DictGlobEntry(base.Op):
             return self
         return DictGlobEntry(new_kg, new_vp)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This entry once per pairing of its key glob's and value pattern's
+        forms (see ContainerOp).
+        """
+        keys = _alternatives(self.key_glob, settings, node, parents)
+        vals = _alternatives(self.val_pattern, settings, node, parents)
+        return tuple(DictGlobEntry(k, v) for k, v in product(keys, vals))
+
     def __repr__(self):
         val_repr = repr(self.val_pattern) if self.val_pattern is not None else ''
         key_repr = repr(self.key_glob)
@@ -156,7 +253,7 @@ class DictGlobEntry(base.Op):
 _LIST_TYPES = (list, tuple)
 
 
-class ContainerList(base.Op):
+class ContainerList(ContainerOp):
     """
     List/tuple pattern: [elem, elem, ...].
 
@@ -213,6 +310,14 @@ class ContainerList(base.Op):
             return self
         return ContainerList(*new_elems, type_prefix=self.type_prefix)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This list once per combination of its elements' forms (see
+        ContainerOp).
+        """
+        forms = (_alternatives(e, settings, node, parents) for e in self.elements)
+        return tuple(ContainerList(*c, type_prefix=self.type_prefix) for c in product(*forms))
+
     def __repr__(self):
         prefix = self.type_prefix or ''
         return prefix + '[' + ', '.join(repr(e) for e in self.elements) + ']'
@@ -222,7 +327,7 @@ class ContainerList(base.Op):
 # ContainerDict — {k: v, ...} pattern
 # ---------------------------------------------------------------------------
 
-class ContainerDict(base.Op):
+class ContainerDict(ContainerOp):
     """
     Dict pattern: {key: val, key: val, ...}.
 
@@ -280,6 +385,14 @@ class ContainerDict(base.Op):
             return self
         return ContainerDict(*new_entries, type_prefix=self.type_prefix)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This dict once per combination of its entries' forms (see
+        ContainerOp).
+        """
+        forms = (_alternatives(e, settings, node, parents) for e in self.entries)
+        return tuple(ContainerDict(*c, type_prefix=self.type_prefix) for c in product(*forms))
+
     def matchable(self, op, specials=False):
         """
         ContainerDict can match against Const values.
@@ -302,7 +415,7 @@ class ContainerDict(base.Op):
 # ContainerSet — {v, v, ...} pattern
 # ---------------------------------------------------------------------------
 
-class ContainerSet(base.Op):
+class ContainerSet(ContainerOp):
     """
     Set/frozenset pattern: {elem, elem, ...}.
 
@@ -353,6 +466,14 @@ class ContainerSet(base.Op):
             return self
         return ContainerSet(*new_elems, type_prefix=self.type_prefix)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This set once per combination of its elements' forms (see
+        ContainerOp).
+        """
+        forms = (_alternatives(e, settings, node, parents) for e in self.elements)
+        return tuple(ContainerSet(*c, type_prefix=self.type_prefix) for c in product(*forms))
+
     def matchable(self, op, specials=False):
         """
         ContainerSet can match against Const values.
@@ -368,7 +489,7 @@ class ContainerSet(base.Op):
 # StringGlob — "prefix"..."suffix" string pattern
 # ---------------------------------------------------------------------------
 
-class StringGlob(base.Op):
+class StringGlob(ContainerOp):
     """
     String glob pattern: quoted fragments with ... between them.
 
@@ -437,7 +558,8 @@ class StringGlob(base.Op):
         new_parts = []
         changed = False
         for p in self.parts:
-            if not hasattr(p, 'resolve'):
+            # a glob holds no substitution; a reference resolves when matched
+            if isinstance(p, (Glob, matchers.Reference)) or not hasattr(p, 'resolve'):
                 new_parts.append(p)
                 continue
             np = p.resolve(bindings, partial)
@@ -462,6 +584,14 @@ class StringGlob(base.Op):
             return self
         return StringGlob(*new_parts)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This glob once per combination of the strings its references
+        resolve to (see ContainerOp).
+        """
+        forms = (_fragments(p, str, 'StringGlob', settings, node, parents) for p in self.parts)
+        return tuple(StringGlob(*c) for c in product(*forms))
+
     def matches(self, vals):
         """
         Yield str vals matching the glob pattern.
@@ -493,7 +623,7 @@ class StringGlob(base.Op):
 # BytesGlob — b"prefix"...b"suffix" bytes pattern
 # ---------------------------------------------------------------------------
 
-class BytesGlob(base.Op):
+class BytesGlob(ContainerOp):
     """
     Bytes glob pattern: byte-string fragments with ... between them.
 
@@ -562,7 +692,8 @@ class BytesGlob(base.Op):
         new_parts = []
         changed = False
         for p in self.parts:
-            if not hasattr(p, 'resolve'):
+            # a glob holds no substitution; a reference resolves when matched
+            if isinstance(p, (Glob, matchers.Reference)) or not hasattr(p, 'resolve'):
                 new_parts.append(p)
                 continue
             np = p.resolve(bindings, partial)
@@ -587,6 +718,14 @@ class BytesGlob(base.Op):
             return self
         return BytesGlob(*new_parts)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This glob once per combination of the bytes its references
+        resolve to (see ContainerOp).
+        """
+        forms = (_fragments(p, bytes, 'BytesGlob', settings, node, parents) for p in self.parts)
+        return tuple(BytesGlob(*c) for c in product(*forms))
+
     def matches(self, vals):
         """
         Yield bytes vals matching the glob pattern.
@@ -618,7 +757,7 @@ class BytesGlob(base.Op):
 # ValueGroup — (val1, val2) value disjunction
 # ---------------------------------------------------------------------------
 
-class ValueGroup(base.Op):
+class ValueGroup(ContainerOp):
     """
     Value group: (val1, val2, ...) — matches any alternative.
 
@@ -652,6 +791,15 @@ class ValueGroup(base.Op):
             return self
         return ValueGroup(*new_alts)
 
+    def branches(self, settings, node=None, parents=()):
+        """
+        This group with its references resolved: one group, whose
+        alternatives are every form its alternatives take (see
+        ContainerOp).
+        """
+        alts = (f for a in self.alternatives for f in _alternatives(a, settings, node, parents))
+        return (ValueGroup(*alts),)
+
     def matchable(self, op, specials=False):
         """
         ValueGroup can match against Const values.

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/filters.py

@@ -2,6 +2,7 @@
 Filter ops: key-value filters, boolean combinators, and negation.
 """
 from . import base
+from . import matchers
 from . import predicates
 from .access import Slot, Slice
 
@@ -112,29 +113,37 @@ class FilterKey(base.MatchOp):
         if hasattr(part, 'gather'):
             yield from self._get_values(part.gather(node, settings), rest, settings)
             return
+        # a reference in a part resolves against the node the part is looked
+        # up in, as ^, and that node's ancestors above it
+        below = settings.below(node)
         if isinstance(part, Slot):
+            # only a reference goes through settings: a resolver taking
+            # literals in segments is not offered a filter key's
+            slots = part._resolved(node=node, settings=settings) if part.is_reference() else (part,)
             try:
-                for v in part.values(node):
-                    yield from self._get_values(v, rest, settings)
+                for slot in slots:
+                    for v in slot.values(node):
+                        yield from self._get_values(v, rest, below)
             except (TypeError, AttributeError):
                 yield None, False
             return
         if isinstance(part, Slice):
             try:
-                s = part.slice(node)
+                s = next(iter(part.keys(node, settings=settings)))
                 val = node[s]
-                yield from self._get_values(val, rest, settings)
-            except (TypeError, AttributeError, KeyError, IndexError):
+                yield from self._get_values(val, rest, below)
+            except (StopIteration, TypeError, AttributeError, KeyError, IndexError):
                 yield None, False
             return
         # Key-like part (Word, Wildcard, etc.)
         if not hasattr(node, 'keys'):
             yield None, False
             return
+        keys = (k for m in self._key_matchers(part, node, settings) for k in m.matches(node.keys()))
         if len(parts) == 1 and not isinstance(part, Slot):
             # Simple key - yield all matching values (existing single-key behavior)
             found_any = False
-            for km in part.matches(node.keys()):
+            for km in keys:
                 yield node[km], True
                 found_any = True
             if not found_any:
@@ -142,14 +151,31 @@ class FilterKey(base.MatchOp):
             return
         # Dotted path - traverse (first match only at each key-like level)
         found = False
-        for km in part.matches(node.keys()):
+        for km in keys:
             child = node[km]
-            yield from self._get_values(child, rest, settings)
+            yield from self._get_values(child, rest, below)
             found = True
             break
         if not found:
             yield None, False
 
+    def _key_matchers(self, part, node, settings):
+        """
+        The match ops a key-like part tests node's keys with: a reference
+        resolved against node and its ancestors, one per value when its
+        path is a pattern, none when it does not resolve; the part itself
+        otherwise.
+        """
+        if not part.is_reference():
+            return (part,)
+        try:
+            val = settings.resolve(part, node, settings.parents or ())
+        except KeyError:
+            return ()
+        if part.is_pattern():
+            return tuple(matchers.ResolvedValue(v) for v in val)
+        return (matchers.ResolvedValue(val),)
+
     def get_value(self, node):
         """
         Get first matching value from node (backwards compat)

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/grammar.py

@@ -260,8 +260,11 @@ regex = _regex.copy().set_parse_action(matchers.Regex)
 regex_first = (_regex + pp.Suppress(pp.Literal('?'))).set_parse_action(matchers.RegexFirst)
 _escaped_dollar = pp.Regex(r'\\\$\${0,2}(\([^)]*\)|[0-9]*)').set_parse_action(
     lambda t: matchers.Word(t[0][1:]))
-_reference = pp.Regex(r'\$\$\([^)]+\)').set_parse_action(
-    lambda t: matchers.Reference(t[0][3:-1]))
+# $$(path) runs to the ) that closes it, so the path may hold parentheses
+# of its own, $$((a[*];)) or $$(a.(b,c)); a ) inside quotes does not count.
+_reference = (S(pp.Regex(r'\$\$(?=\()'))
+              + pp.original_text_for(pp.nested_expr('(', ')')).add_condition(lambda t: t[0] != '()')
+              ).set_parse_action(lambda t: matchers.Reference(t[0][1:-1]))
 def _paren_subst_action(t):
     """
     Parse $(content) where content is name_or_index[|transform1|transform2...].
@@ -285,8 +288,11 @@ var = _escaped_dollar | _reference | _paren_subst | _raw_subst | _dollar_word
 # |min:$amount.value or =^lots.taken: one string, for a resolver to read
 # whole. In a segment position the . separates segments, so not there.
 _arg_sigil = pp.Regex(r'(?:\$(?![0-9($])|\^)[^' + re.escape(reserved.replace('.', '')) + r' \t\n\r]+').set_parse_action(matchers.Word)
-slice = pp.Optional(integer | plus) + ':' + pp.Optional(integer | plus) \
-         + pp.Optional(':') + pp.Optional(integer | plus)
+# A slice bound: an integer, + (the length), or a $$(path) reference or
+# $(name)/$N substitution standing for one.
+_slice_bound = integer | plus | _reference | _paren_subst | _raw_subst
+slice = pp.Optional(_slice_bound) + ':' + pp.Optional(_slice_bound) \
+         + pp.Optional(':') + pp.Optional(_slice_bound)
 
 _common_pats = wildcard_first | wildcard | var | regex_first | regex
 _commons = bytes_literal | string | _common_pats | numeric_quoted

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/recursive.py

@@ -92,9 +92,33 @@ class Recursive(BaseOp):
             s = '.' + s
         return s
 
+    def _parts(self):
+        """
+        The inner match op, the accessor ops and the filters: every part
+        that may hold a substitution or reference.
+        """
+        yield self.inner
+        for item in self.accessors or ():
+            if item is base.BRANCH_CUT or item is base.BRANCH_SOFTCUT:
+                continue
+            yield from item
+        yield from self.filters
+
+    def is_template(self):
+        """
+        True if a part contains a substitution reference.
+        """
+        return any(hasattr(p, 'is_template') and p.is_template() for p in self._parts())
+
+    def is_reference(self):
+        """
+        True if a part contains an internal reference.
+        """
+        return any(hasattr(p, 'is_reference') and p.is_reference() for p in self._parts())
+
     def resolve(self, bindings, partial=False):
         """
-        Resolve $N in inner match op and accessor branches.
+        Resolve $N in inner match op, accessor branches and filters.
         """
         new_inner = self.inner.resolve(bindings, partial) if hasattr(self.inner, 'resolve') else self.inner
         new_accessors = None
@@ -111,11 +135,16 @@ class Recursive(BaseOp):
                     acc_changed = True
                 new_accessors.append(new_branch)
             new_accessors = tuple(new_accessors)
-        if new_inner is self.inner and not acc_changed:
+        new_filters = tuple(f.resolve(bindings, partial) for f in self.filters)
+        filt_changed = not all(nf is of for nf, of in zip(new_filters, self.filters))
+        if new_inner is self.inner and not acc_changed and not filt_changed:
             return self
-        return Recursive(
+        # type(self): a RecursiveFirst stays first-match
+        r = type(self)(
             new_inner, accessors=new_accessors if new_accessors is not None else self.accessors,
             depth_start=self.depth_start, depth_stop=self.depth_stop, depth_step=self.depth_step)
+        r.filters = new_filters
+        return r
 
     def match(self, op, specials=False):
         return self.inner.matchable(op, specials=specials)
@@ -371,7 +400,7 @@ class Recursive(BaseOp):
         node[k] = v
         return node
 
-    def _update_recursive(self, ops, node, val, has_defaults, _path, nop, depth=0, guard=None, seen=frozenset(), settings=base.SETTINGS):
+    def _update_recursive(self, ops, node, val, has_defaults, _path, nop, depth=0, guard=None, seen=frozenset(), settings=base.SETTINGS, nop_from_unwrap=False):
         node_id = id(node)
         if node_id in seen:
             return node
@@ -382,7 +411,8 @@ class Recursive(BaseOp):
 
         for acc, k, v in items:
             # Recurse first (bottom-up)
-            v = self._update_recursive(ops, v, val, has_defaults, _path, nop, depth + 1, guard, seen, settings=settings)
+            v = self._update_recursive(ops, v, val, has_defaults, _path, nop, depth + 1, guard, seen, settings=settings,
+                                       nop_from_unwrap=nop_from_unwrap)
             node = self._assign(acc, node, k, v)
             if self.filters and not any(True for _ in self.filtered((v,), settings)):
                 continue
@@ -392,13 +422,15 @@ class Recursive(BaseOp):
             if guard and not guard(v):
                 continue
             if ops:
-                node = self._assign(acc, node, k, engine.updates(ops, v, val, has_defaults, _path + [(self, k)], nop, settings=settings))
+                # a ~ on this op holds back only this op, not the ops after it
+                pass_nop = nop and not nop_from_unwrap
+                node = self._assign(acc, node, k, engine.updates(ops, v, val, has_defaults, _path + [(self, k)], pass_nop, settings=settings))
             elif not nop:
                 node = self._assign(acc, node, k, val)
         return node
 
-    def do_update(self, ops, node, val, has_defaults, _path, nop, settings=base.SETTINGS):
-        return self._update_recursive(ops, node, val, has_defaults, _path, nop, settings=settings)
+    def do_update(self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=False, settings=base.SETTINGS):
+        return self._update_recursive(ops, node, val, has_defaults, _path, nop, settings=settings, nop_from_unwrap=nop_from_unwrap)
 
     def _remove_recursive(self, ops, node, val, nop, depth=0, guard=None, seen=frozenset(), settings=base.SETTINGS):
         node_id = id(node)

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/results.py

@@ -264,16 +264,23 @@ def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=(), position
     $$(^x) looks x up in it). A plain value is resolved too when the
     resolver takes literals at position, 'guards' or 'filters'. A reference
     path that is a pattern becomes a value group of what it resolves to.
+    A container value resolves the references inside it the same way; one
+    that is a pattern branches the container, so it becomes a value group
+    of the container once per value (see containers.ContainerOp).
     Raises UnresolvedReference when the reference does not resolve.
     """
-    # container values (ContainerList and kin) are ops without is_reference
     reference = hasattr(guard, 'is_reference') and guard.is_reference()
     if not (reference or (settings.literals(position) and isinstance(guard, Const))):
         return guard
+    from . import containers
+    if isinstance(guard, containers.ContainerOp):
+        branches = guard.branches(settings, node, parents)
+        if len(branches) == 1:
+            return branches[0]
+        return containers.ValueGroup(*branches)
     val = settings.resolve(guard, node, parents)
     if not guard.is_pattern():
         return Const(val)
-    from . import containers
     return containers.ValueGroup(*(Const(v) for v in val))
 
 

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/dotted/wrappers.py

@@ -314,7 +314,7 @@ class TransformWrap(Wrap):
                 val = self.apply(val, settings)
             except base.UnresolvedReference:
                 return node
-        return self.inner.do_update(ops, node, val, has_defaults, _path, nop, settings=settings)
+        return self.inner.do_update(ops, node, val, has_defaults, _path, nop, nop_from_unwrap=nop_from_unwrap, settings=settings)
 
     def do_remove(self, ops, node, val, nop, settings=base.SETTINGS):
         return self.inner.do_remove(ops, node, val, nop, settings=settings)
@@ -543,7 +543,8 @@ class ValueGuard(Wrap):
         nop = self._nop(nop)
         if self.inner.is_recursive():
             return self.inner._update_recursive(
-                ops, node, val, has_defaults, _path, nop, guard=self._guard(settings), settings=settings)
+                ops, node, val, has_defaults, _path, nop, guard=self._guard(settings), settings=settings,
+                nop_from_unwrap=nop_from_unwrap)
         if not ops and not nop:
             # the leaf: upsert() has no settings, and the guard needs them
             for k in list(self.keys(node, settings=settings)):
@@ -788,8 +789,9 @@ class FilterWrap(Wrap):
             return self
         return FilterWrap(new_inner, new_filters)
 
-    def do_update(self, ops, node, val, has_defaults, _path, nop, settings=base.SETTINGS):
-        return access.BaseOp.do_update(self, ops, node, val, has_defaults, _path, nop, settings=settings)
+    def do_update(self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=False, settings=base.SETTINGS):
+        return access.BaseOp.do_update(
+            self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=nop_from_unwrap, settings=settings)
 
     def do_remove(self, ops, node, val, nop, settings=base.SETTINGS):
         return access.BaseOp.do_remove(self, ops, node, val, nop, settings=settings)

{dotted_notation-0.49.2 → dotted_notation-0.49.4/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.2
+Version: 0.49.4
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.6
@@ -1163,6 +1164,14 @@ Dotted slicing works like python slicing and all that entails.
     >>> dotted.get(d, '*.there[1:]')
     ([2, 3], [5, 6])
 
+A bound may be a reference or a substitution, resolved the way a slot's is:
+
+    >>> d = {'b': [3, 0, 5], 'i': 2}
+    >>> dotted.get(d, 'b[:$$(i)]')
+    [3, 0]
+    >>> dotted.get(d, 'b[$(n):]', bindings={'n': 1})
+    [0, 5]
+
 <a id="dot-notation-for-sequence-indexing"></a>
 ### Dot notation for sequence indexing
 
@@ -1641,6 +1650,23 @@ as do the transforms before a guard:
     >>> dotted.get(data, '*|mul:$$(scale)=20')
     (2,)
 
+So does a reference inside a container value. One whose path is a pattern
+branches the container, once per value; pack it, `(…;)`, to compare with the
+tuple instead:
+
+    >>> data = {'want': [2, 3], 'items': [[1, 2], [1, 4], [1, (2, 3)]]}
+    >>> dotted.get(data, 'items[*]=[1, $$(want[*])]')
+    ([1, 2],)
+    >>> dotted.get(data, 'items[*]=[1, $$((want[*];))]')
+    ([1, (2, 3)],)
+
+A filter key may hold references too. In each part of the key, `^` is the
+node that part is looked up in, so in the first part it is the item:
+
+    >>> data = {'field': 'name', 'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(data, 'users[*&$$(field)="bob"]')
+    ({'name': 'bob'},)
+
 With `update`, the transforms apply to the value being set, so `^` is that
 value:
 

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dotted_notation"
-version = "0.49.2"
+version = "0.49.4"
 description = "Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms"
 readme = "README.md"
 requires-python = ">=3.6"
@@ -38,6 +38,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
 ]
@@ -78,7 +79,7 @@ Changelog = "https://github.com/freywaid/dotted/blob/master/CHANGELOG.md"
 include = ["dotted*"]
 
 [tool.cibuildwheel]
-# Compiled wheels for CPython 3.11-3.14 (the versions are listed in the
+# Compiled wheels for CPython 3.11-3.15 (the versions are listed in the
 # publish workflow, one job each); everything else installs the pure wheel.
 skip = "pp*"
 test-requires = "pytest"

{dotted_notation-0.49.2 → dotted_notation-0.49.4}/setup.py

@@ -64,4 +64,7 @@ class build_ext(_build_ext):
             self.parallel = os.cpu_count() or 1
 
 
-setup(ext_modules=extensions(), cmdclass={'build_ext': build_ext})
+# Guarded: cythonize compiles in a process pool, and a spawned worker
+# (macOS, and Linux from Python 3.14) imports this file again.
+if __name__ == '__main__':
+    setup(ext_modules=extensions(), cmdclass={'build_ext': build_ext})