dotted-notation 0.49.1__tar.gz → 0.49.3__tar.gz

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [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
+- `ReferenceResolver.literals` may name the positions a resolver is
+  offered plain tokens in, as a list or tuple of `'segments'`,
+  `'transforms'`, `'guards'` and `'filters'`. A host whose variables are
+  sigiled arguments, `|add:^fee`, leaves `'segments'` out and no longer
+  pays a call per key (#63); `get` then keeps its fast path for a plain
+  chain of keys. An unknown name is a `ValueError`. `True` and `False`
+  are unchanged.
+- `ReferenceResolver(literals=...)` sets `literals` per instance,
+  overriding the class's, so a resolver need not be subclassed only to
+  change it. A subclass with its own `__init__` passes it on with
+  `super().__init__(literals)`.
+
 ## [0.49.1]
 
 ### Documentation

{dotted_notation-0.49.1/dotted_notation.egg-info → dotted_notation-0.49.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.1
+Version: 0.49.3
 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:
 
@@ -1677,14 +1703,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1696,6 +1724,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/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:
 
@@ -1630,14 +1655,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1649,6 +1676,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/dotted/access.py

@@ -251,11 +251,12 @@ class AccessOp(SimpleOp):
     def _offered(self, settings):
         """
         True if the match op goes to the resolver: a reference, or a
-        plain constant when the resolver in force takes literals.
+        plain constant when the resolver in force takes literals in path
+        segments.
         """
         if self.op.is_reference():
             return True
-        return (settings.literals() and isinstance(self.op, matchers.Const)
+        return (settings.literals('segments') and isinstance(self.op, matchers.Const)
                 and not isinstance(self.op, matchers.ResolvedValue))
 
     def resolve(self, bindings, partial=False):
@@ -993,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):
@@ -1011,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 '+'
@@ -1022,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):
@@ -1075,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.1 → dotted_notation-0.49.3}/dotted/api.py

@@ -448,9 +448,11 @@ def build(obj, path, strict=False, bindings=None, resolver=None):
 def _literals(resolver):
     """
     True if the resolver a call will run under, its own or the process
-    default, takes plain tokens: the simple fast path must then step aside.
+    default, takes plain tokens in path segments: the simple fast path must
+    then step aside. Other positions it can serve, as its transforms
+    resolve through Settings.
     """
-    return (base.RESOLVER if resolver is None else resolver).literals
+    return base.takes_literals(base.RESOLVER if resolver is None else resolver, 'segments')
 
 
 def _prepare(ops, resolver):
@@ -1365,12 +1367,11 @@ def set_resolver(resolver=None):
     restores dotted's own (see Resolver).
     >>> import dotted
     >>> class Upper(dotted.ReferenceResolver):
-    ...     literals = True
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
     ...             return super().resolve(ref, settings, node, parents)
     ...         return ref.value.upper()
-    >>> dotted.set_resolver(Upper())
+    >>> dotted.set_resolver(Upper(literals=True))
     >>> dotted.get({'A': 1}, 'a')
     1
     >>> dotted.set_resolver()

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/dotted/base.py

@@ -149,6 +149,12 @@ class NOP(metaclass=MetaNOP):
         return False
 
 
+# The positions a resolver may be offered plain tokens in, named in its
+# literals: key, slot and attr segments, transform arguments, guard values
+# and filter values.
+LITERALS = ('segments', 'transforms', 'guards', 'filters')
+
+
 class Resolver:
     """
     What a reference means at run time. Every $$(path) a traversal meets,
@@ -161,10 +167,30 @@ class Resolver:
 
     # True to be offered every plain token in a var-permitting position as
     # well: key, slot and attr segments, transform arguments, guard and
-    # filter values. The host decides which are its variables; returning
-    # ref.value leaves a token the literal it is.
+    # filter values. A list or tuple of LITERALS names to be offered them in
+    # those positions only, ('transforms', 'guards', 'filters') to leave
+    # segments out. The host decides which are its variables; returning
+    # ref.value leaves a token the literal it is. Set here, on a subclass,
+    # or per instance with literals=.
     literals = False
 
+    def __init_subclass__(cls, **kwargs):
+        """
+        Check a subclass's literals (see check_literals).
+        """
+        super().__init_subclass__(**kwargs)
+        check_literals(cls.literals)
+
+    def __init__(self, literals=None):
+        """
+        literals, when given, overrides the class's for this instance (see
+        check_literals).
+        """
+        if literals is None:
+            return
+        check_literals(literals)
+        self.literals = literals
+
     def fold(self, segments):
         """
         The path-level hook, called once with a path's segment strings
@@ -211,6 +237,33 @@ class Resolver:
 RESOLVER = Resolver()
 
 
+def check_literals(literals):
+    """
+    Raise unless literals is True, False, or a list or tuple of LITERALS
+    names.
+    """
+    if isinstance(literals, bool):
+        return
+    if not isinstance(literals, (list, tuple)):
+        raise TypeError(f'literals is True, False or a list or tuple of {LITERALS}, not {literals!r}')
+    unknown = [name for name in literals if name not in LITERALS]
+    if unknown:
+        raise ValueError(f'literals names {unknown}, not among {LITERALS}')
+
+
+def takes_literals(resolver, position):
+    """
+    True if resolver takes plain tokens at position, one of LITERALS: its
+    literals is True, or names it.
+    """
+    lit = resolver.literals
+    if lit is True:
+        return True
+    if not lit:
+        return False
+    return position in lit
+
+
 class Settings:
     """
     What holds for the whole of one traversal: the root node, the chain of
@@ -242,11 +295,12 @@ class Settings:
         """
         return RESOLVER if self.resolver is None else self.resolver
 
-    def literals(self):
+    def literals(self, position):
         """
-        True if the resolver in force wants plain tokens offered too.
+        True if the resolver in force wants plain tokens at position, one
+        of LITERALS, offered too.
         """
-        return self.resolving().literals
+        return takes_literals(self.resolving(), position)
 
     def resolve(self, ref, node=None, parents=()):
         """
@@ -551,7 +605,7 @@ class Transform(Op):
             return ()
         if settings is None:
             settings = SETTINGS
-        literals = settings.literals()
+        literals = settings.literals('transforms')
         args = []
         for p in self.params:
             if isinstance(p, Op) and (p.is_reference() or (literals and isinstance(p, matchers.Const))):

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/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.1 → dotted_notation-0.49.3}/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)
@@ -285,7 +311,7 @@ class FilterKeyValue(FilterOp):
                     val = results.apply_transforms(val, self.guard_transforms, settings, parents)
             except base.UnresolvedReference:
                 continue
-            if results.guard_passes(pred_op, val, self.val, settings, val, parents):
+            if results.guard_passes(pred_op, val, self.val, settings, val, parents, 'filters'):
                 return True
         return False
 

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/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.1 → dotted_notation-0.49.3}/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)

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/dotted/results.py

@@ -256,33 +256,41 @@ def apply_transforms(val, transforms, settings=base.SETTINGS, parents=()):
     return val
 
 
-def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=()):
+def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=(), position='guards'):
     """
     The match op a guard or filter value compares with: the value as
     parsed, or a reference resolved through the traversal's resolver
     against node and parents, node being the value under test (so
-    $$(^x) looks x up in it). A reference path that is a pattern becomes
-    a value group of what it resolves to. Raises UnresolvedReference when
-    the reference does not resolve.
+    $$(^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() and isinstance(guard, Const))):
+    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))
 
 
-def guard_passes(pred_op, val, guard, settings=base.SETTINGS, node=None, parents=()):
+def guard_passes(pred_op, val, guard, settings=base.SETTINGS, node=None, parents=(), position='guards'):
     """
     True if val satisfies pred_op against guard (see guard_matcher); a
     guard reference that does not resolve passes nothing.
     """
     try:
-        matcher = guard_matcher(guard, settings, node, parents)
+        matcher = guard_matcher(guard, settings, node, parents, position)
     except base.UnresolvedReference:
         return False
     return any(True for _ in pred_op.matches((val,), matcher))

{dotted_notation-0.49.1 → dotted_notation-0.49.3/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.1
+Version: 0.49.3
 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:
 
@@ -1677,14 +1703,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1696,6 +1724,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.1 → dotted_notation-0.49.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dotted_notation"
-version = "0.49.1"
+version = "0.49.3"
 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.1 → dotted_notation-0.49.3}/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})