dotted-notation 0.44.7__tar.gz → 0.44.8__tar.gz

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/CHANGELOG.md

@@ -3,6 +3,34 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.44.8]
+
+### Added
+- `match()` supports variadic ops on the *path* side. A group or
+  recursive op in the path used to fall through to `None` (or match by
+  accident, as `**` did); the path is now treated as the set of paths it
+  denotes, and the pattern must *subsume* it — cover every expansion.
+  Every branch of a path-side group must match, so
+  `match('references.*', 'references.(a,b)')` matches while
+  `match('*.*', '(a.b,c)')` does not (branch `c` is a segment short).
+  Groups on both sides compose the two rules: some pattern branch must
+  cover every path branch. A path-side recursive is covered only by a
+  recursive pattern that subsumes it — `match('**', '*b')` matches,
+  `match('*', '**')` does not. Conjunctions match on any branch (their
+  expansions are the intersection); negations, denoting an open set,
+  only by an identical negation or a bare wildcard.
+
+### Changed
+- A path-side group captures as one segment: itself, e.g.
+  `match('references.*', 'references.(a,b)', groups=True)` gives
+  `('references.(a,b)', ('references', '(a,b)'))`. When a variadic
+  pattern consumes across the group boundary the group folds into that
+  segment's capture, as nested patterns already do.
+- Match dispatch is now per-op on both sides: variadic path ops
+  implement `do_match_path` (the mirror of `do_match`), and segment
+  coverage moved onto ops as `covered_by`, replacing the ad-hoc value
+  extraction `Recursive.do_match` used to do.
+
 ## [0.44.7]
 
 ### Fixed

{dotted_notation-0.44.7/dotted_notation.egg-info → dotted_notation-0.44.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.7
+Version: 0.44.8
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -519,6 +519,47 @@ single group, and counts as one pattern position:
     >>> dotted.match('x.(a.b)', 'x.a.b', groups=True)
     ('x.a.b', ('x', 'a.b'))
 
+The path may itself be a pattern, in which case `match` asks whether the
+pattern *subsumes* it — covers everything the path denotes:
+
+    >>> dotted.match('*', '*.*')
+    '*.*'
+    >>> dotted.match('*.*', '*')
+
+A group on the path side denotes all of its expansions, so every branch
+must be covered. It captures as a single segment: itself.
+
+    >>> dotted.match('references.*', 'references.(a,b)')
+    'references.(a,b)'
+    >>> dotted.match('references.*', 'references.(a,b)', groups=True)
+    ('references.(a,b)', ('references', '(a,b)'))
+
+A branch that outruns the pattern is only covered when partial matching
+is on, and never when the pattern needs more segments than the branch
+has:
+
+    >>> dotted.match('*', '(a.b,c)')
+    '(a.b,c)'
+    >>> dotted.match('*', '(a.b,c)', partial=False)
+    >>> dotted.match('*.*', '(a.b,c)')
+
+Groups on both sides compose the two rules — the pattern matches if
+*some* branch of it covers *every* branch of the path:
+
+    >>> dotted.match('(a,b)', '(a.b,b)')
+    '(a.b,b)'
+    >>> dotted.match('(a,b)', '(a.b,b)', partial=False)
+    >>> dotted.match('(a,b)', '(a.b,c)')
+
+A recursive op on the path side denotes unboundedly many expansions, so
+only a recursive pattern that subsumes it will match:
+
+    >>> dotted.match('**', 'a.**')
+    'a.**'
+    >>> dotted.match('**', '*b')
+    '*b'
+    >>> dotted.match('*', '**')
+
 <a id="replace"></a>
 ### Replace
 

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/README.md

@@ -479,6 +479,47 @@ single group, and counts as one pattern position:
     >>> dotted.match('x.(a.b)', 'x.a.b', groups=True)
     ('x.a.b', ('x', 'a.b'))
 
+The path may itself be a pattern, in which case `match` asks whether the
+pattern *subsumes* it — covers everything the path denotes:
+
+    >>> dotted.match('*', '*.*')
+    '*.*'
+    >>> dotted.match('*.*', '*')
+
+A group on the path side denotes all of its expansions, so every branch
+must be covered. It captures as a single segment: itself.
+
+    >>> dotted.match('references.*', 'references.(a,b)')
+    'references.(a,b)'
+    >>> dotted.match('references.*', 'references.(a,b)', groups=True)
+    ('references.(a,b)', ('references', '(a,b)'))
+
+A branch that outruns the pattern is only covered when partial matching
+is on, and never when the pattern needs more segments than the branch
+has:
+
+    >>> dotted.match('*', '(a.b,c)')
+    '(a.b,c)'
+    >>> dotted.match('*', '(a.b,c)', partial=False)
+    >>> dotted.match('*.*', '(a.b,c)')
+
+Groups on both sides compose the two rules — the pattern matches if
+*some* branch of it covers *every* branch of the path:
+
+    >>> dotted.match('(a,b)', '(a.b,b)')
+    '(a.b,b)'
+    >>> dotted.match('(a,b)', '(a.b,b)', partial=False)
+    >>> dotted.match('(a,b)', '(a.b,c)')
+
+A recursive op on the path side denotes unboundedly many expansions, so
+only a recursive pattern that subsumes it will match:
+
+    >>> dotted.match('**', 'a.**')
+    'a.**'
+    >>> dotted.match('**', '*b')
+    '*b'
+    >>> dotted.match('*', '**')
+
 <a id="replace"></a>
 ### Replace
 

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/dotted/api.py

@@ -775,6 +775,33 @@ def match(pattern, path, groups=False, partial=True, strict=False):
     >>> match('*b', 'b.b.b')
     'b.b.b'
     >>> match('*b', 'a.b.c')
+
+    A group on the *path* side denotes all its expansions; the pattern
+    must cover every branch (subsumption).  The group captures as one
+    segment: itself.
+    >>> match('references.*', 'references.(a,b)')
+    'references.(a,b)'
+    >>> match('references.*', 'references.(a,b)', groups=True)
+    ('references.(a,b)', ('references', '(a,b)'))
+    >>> match('**.z', '(a.b,c).z', groups=True)
+    ('(a.b,c).z', ('(a.b,c)', 'z'))
+    >>> match('*', '(a.b,c)')
+    '(a.b,c)'
+    >>> match('*', '(a.b,c)', partial=False)
+    >>> match('*.*', '(a.b,c)')
+    >>> match('(a,b)', '(a.b,c)')
+    >>> match('(a,b)', '(a.b,b)')
+    '(a.b,b)'
+    >>> match('**.z', '(a.b,c).z')
+    '(a.b,c).z'
+
+    A recursive op on the path side is covered only by a recursive
+    pattern that subsumes it:
+    >>> match('**', 'a.**')
+    'a.**'
+    >>> match('**', '*b')
+    '*b'
+    >>> match('*', '**')
     """
     # groups can be a bool, a GroupMode member, or its string value.
     _patterns_only = (groups == GroupMode.patterns
@@ -791,8 +818,9 @@ def match(pattern, path, groups=False, partial=True, strict=False):
     path_ops = parse(path)
 
     # Variadic ops (recursive, groups) consume variable-length path
-    # segments — use the recursive matcher
-    if any(op.is_variadic() for op in pats):
+    # segments — use the recursive matcher.  On the path side they make
+    # the path denote multiple expansions, which likewise needs it.
+    if any(op.is_variadic() for op in pats) or any(op.is_variadic() for op in path_ops):
         result = base.match_ops(list(pats), list(path_ops), partial)
         if result is None:
             return returns(None, [])

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/dotted/base.py

@@ -46,9 +46,13 @@ def match_ops(pats, path_ops, partial):
     """
     Match a list of pattern ops against a list of path ops.
     Returns a list of (value, is_pattern) capture pairs on success, None
-    on failure.  Dispatches to each op's do_match, which decides how
-    many path segments it consumes.
+    on failure.  Dispatch is per-op on both sides: a variadic op at the
+    head of the path (group, recursive) decides how the pattern must
+    cover it via do_match_path; otherwise the head pattern op decides
+    how many path segments it consumes via do_match.
     """
+    if path_ops and path_ops[0].is_variadic():
+        return path_ops[0].do_match_path(list(pats), list(path_ops[1:]), partial)
     if pats:
         return pats[0].do_match(pats[1:], path_ops, partial)
     if not path_ops:
@@ -207,6 +211,15 @@ class TraversalOp(Op):
         """
         return False
 
+    def covered_by(self, matcher):
+        """
+        True if *matcher* (a match op) matches every segment this op
+        denotes when it appears on the path side.  Simple ops denote a
+        single concrete segment; variadic ops override.
+        """
+        val = getattr(getattr(self, 'op', self), 'value', self)
+        return has_any(matcher.matches((val,)))
+
     def do_match(self, rest_pats, path_ops, partial):
         """
         Match this op against exactly one path segment, then continue with

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/dotted/groups.py

@@ -128,6 +128,85 @@ class OpGroup(base.TraversalOp):
                 return [(combined, True)] + rest
         return None
 
+    def do_match_path(self, pats, rest_path, partial):
+        """
+        Match when this group appears on the *path* side.  The path
+        denotes every expansion of the group's branches, so the pattern
+        must cover all of them (subsumption): each branch is spliced
+        into the path in the group's place and matched; one failing
+        branch fails the whole match.
+
+        The group captures as itself — one capture — via an aligned
+        decomposition (a pattern prefix covering every branch), or
+        assembled into a variadic pattern segment's capture when the
+        pattern crosses the group boundary; only when neither
+        decomposition exists do captures fall back to the first
+        branch's expansion.
+        """
+        fallback = self._verify_covered(pats, rest_path, partial)
+        if fallback is None:
+            return None
+        r = self._aligned_captures(pats, rest_path, partial)
+        if r is not None:
+            return r
+        if pats and pats[0].is_variadic():
+            r = pats[0].do_match(pats[1:], [self] + list(rest_path), partial)
+            if r is not None:
+                return r
+        return fallback
+
+    def _verify_covered(self, pats, rest_path, partial):
+        """
+        Subsumption check over expansions: splice each branch into the
+        path and match.  Returns the first branch's result (the capture
+        fallback) or None when any branch is uncovered.
+        """
+        first = base.marker
+        for branch in base.branches_only(self.branches):
+            r = base.match_ops(pats, list(branch) + list(rest_path), partial)
+            if r is None:
+                return None
+            if first is base.marker:
+                first = r
+        if first is base.marker:
+            return base.match_ops(pats, list(rest_path), partial)
+        return first
+
+    def _aligned_captures(self, pats, rest_path, partial):
+        """
+        Group-as-itself captures: find a pattern prefix that covers the
+        branch set exactly (or up to a partial tail when the pattern
+        ends inside the group); the group then captures as one segment
+        and the remaining pattern matches the remaining path.
+        """
+        from . import results
+        for k in range(1, len(pats) + 1):
+            head = list(pats[:k])
+            tail_partial = partial and k == len(pats) and not rest_path
+            if not self._covers_branches(head, tail_partial):
+                continue
+            rest = base.match_ops(list(pats[k:]), list(rest_path), partial)
+            if rest is None:
+                continue
+            is_pat = any(p.is_pattern() for p in head)
+            return [(results.assemble([self]), is_pat)] + rest
+        return None
+
+    def _covers_branches(self, head_pats, tail_partial=False):
+        """
+        True if head_pats covers every branch of this group.
+        """
+        return all(base.match_ops(head_pats, list(b), tail_partial) is not None
+                   for b in base.branches_only(self.branches))
+
+    def covered_by(self, matcher):
+        """
+        A group path op is covered when every segment of every branch is.
+        """
+        return all(op.covered_by(matcher)
+                   for branch in base.branches_only(self.branches)
+                   for op in branch)
+
     def _render(self, top=True):
         """
         Render the group as a string. Subclasses override this.
@@ -429,6 +508,25 @@ class OpGroupAnd(OpGroup):
     def __repr__(self):
         return self._render(top=True)
 
+    def _verify_covered(self, pats, rest_path, partial):
+        """
+        A conjunction's expansions are the intersection of its
+        branches', so a pattern covering any single branch covers the
+        whole (sufficient, conservatively incomplete).
+        """
+        for branch in base.branches_only(self.branches):
+            r = base.match_ops(pats, list(branch) + list(rest_path), partial)
+            if r is not None:
+                return r
+        return None
+
+    def _covers_branches(self, head_pats, tail_partial=False):
+        """
+        Any single covered branch suffices for a conjunction.
+        """
+        return any(base.match_ops(head_pats, list(b), tail_partial) is not None
+                   for b in base.branches_only(self.branches))
+
     def push_children(self, stack, frame, paths):
         """
         All branches must match. Collect results per branch;
@@ -566,6 +664,42 @@ class OpGroupNot(OpGroup):
         seg_val = getattr(getattr(kop, 'op', kop), 'value', kop)
         return [(seg_val, True)] + rest
 
+    def do_match_path(self, pats, rest_path, partial):
+        """
+        Match when this negation appears on the *path* side.  It denotes
+        every segment its inner pattern excludes — an open set — so it
+        is covered only by an identical negation or by a bare wildcard
+        segment.
+        """
+        from . import results
+        if not pats:
+            return [] if partial else None
+        head = pats[0]
+        if head != self and not self._wildcard_covers(head):
+            return None
+        rest = base.match_ops(pats[1:], rest_path, partial)
+        if rest is None:
+            return None
+        return [(results.assemble([self]), True)] + rest
+
+    def _wildcard_covers(self, head):
+        """
+        True if pattern op *head* is a bare single-segment wildcard and
+        this negation excludes only single segments.
+        """
+        from . import matchers
+        if any(len(b) != 1 for b in base.branches_only(self.branches)):
+            return False
+        return isinstance(getattr(head, 'op', None), matchers.Wildcard)
+
+    def covered_by(self, matcher):
+        """
+        A negation denotes an open set of segments; only a wildcard
+        covers them all.
+        """
+        from . import matchers
+        return isinstance(matcher, matchers.Wildcard)
+
     def do_update(self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=False, **kwargs):
         inner = self.inner
         if not inner:

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/dotted/recursive.py

@@ -125,9 +125,7 @@ class Recursive(BaseOp):
         """
         from . import results
         for n in range(1, len(path_ops) + 1):
-            kop = path_ops[n - 1]
-            seg_val = getattr(getattr(kop, 'op', kop), 'value', kop)
-            if not any(True for _ in self.inner.matches((seg_val,))):
+            if not path_ops[n - 1].covered_by(self.inner):
                 return None
             rest = base.match_ops(rest_pats, path_ops[n:], partial)
             if rest is None:
@@ -136,6 +134,54 @@ class Recursive(BaseOp):
             return [(combined, True)] + rest
         return None
 
+    def do_match_path(self, pats, rest_path, partial):
+        """
+        Match when this recursive op appears on the *path* side.  It
+        denotes unboundedly many expansions, so only a pattern segment
+        that itself covers arbitrary depth can subsume it: a recursive
+        whose inner pattern covers this op's chain segments.  The
+        subsuming pattern op is tried both consumed and retained, since
+        a recursive pattern may keep covering segments after the group.
+        """
+        from . import results
+        if not pats:
+            return [] if partial else None
+        head = pats[0]
+        if not isinstance(head, Recursive):
+            return None
+        if not self._subsumed_by(head):
+            return None
+        rest = base.match_ops(pats[1:], rest_path, partial)
+        if rest is None:
+            rest = base.match_ops(pats, rest_path, partial)
+        if rest is None:
+            return None
+        return [(results.assemble([self]), True)] + rest
+
+    def _subsumed_by(self, pat):
+        """
+        True if recursive pattern op *pat* covers every expansion of
+        this path op.  Identical recursives cover; otherwise an
+        unsliced recursive with the same accessors whose inner matcher
+        covers every chain segment this op can produce.
+        """
+        if pat == self:
+            return True
+        if pat.depth_start is not None or pat.depth_stop is not None or pat.depth_step is not None:
+            return False
+        if pat.accessors != self.accessors:
+            return False
+        return self.covered_by(pat.inner)
+
+    def covered_by(self, matcher):
+        """
+        A recursive path op denotes unboundedly many segments; only a
+        wildcard, or this op's own inner matcher, covers them all.
+        """
+        if isinstance(matcher, matchers.Wildcard):
+            return True
+        return matcher == self.inner
+
     def _effective_branches(self):
         """
         Return accessor branches that drive recursion.

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/dotted/wrappers.py

@@ -84,6 +84,21 @@ class Wrap(base.TraversalOp):
             return self.inner.do_match(rest_pats, path_ops, partial)
         return super().do_match(rest_pats, path_ops, partial)
 
+    def do_match_path(self, pats, rest_path, partial):
+        """
+        Delegate path-side matching to the wrapped op (only reached for
+        variadic inners, via is_variadic).
+        """
+        return self.inner.do_match_path(pats, rest_path, partial)
+
+    def covered_by(self, matcher):
+        """
+        Delegate segment coverage to the wrapped op.
+        """
+        if hasattr(self.inner, 'covered_by'):
+            return self.inner.covered_by(matcher)
+        return super().covered_by(matcher)
+
     def concrete(self, val):
         return self.inner.concrete(val)
 

{dotted_notation-0.44.7 → dotted_notation-0.44.8/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.7
+Version: 0.44.8
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -519,6 +519,47 @@ single group, and counts as one pattern position:
     >>> dotted.match('x.(a.b)', 'x.a.b', groups=True)
     ('x.a.b', ('x', 'a.b'))
 
+The path may itself be a pattern, in which case `match` asks whether the
+pattern *subsumes* it — covers everything the path denotes:
+
+    >>> dotted.match('*', '*.*')
+    '*.*'
+    >>> dotted.match('*.*', '*')
+
+A group on the path side denotes all of its expansions, so every branch
+must be covered. It captures as a single segment: itself.
+
+    >>> dotted.match('references.*', 'references.(a,b)')
+    'references.(a,b)'
+    >>> dotted.match('references.*', 'references.(a,b)', groups=True)
+    ('references.(a,b)', ('references', '(a,b)'))
+
+A branch that outruns the pattern is only covered when partial matching
+is on, and never when the pattern needs more segments than the branch
+has:
+
+    >>> dotted.match('*', '(a.b,c)')
+    '(a.b,c)'
+    >>> dotted.match('*', '(a.b,c)', partial=False)
+    >>> dotted.match('*.*', '(a.b,c)')
+
+Groups on both sides compose the two rules — the pattern matches if
+*some* branch of it covers *every* branch of the path:
+
+    >>> dotted.match('(a,b)', '(a.b,b)')
+    '(a.b,b)'
+    >>> dotted.match('(a,b)', '(a.b,b)', partial=False)
+    >>> dotted.match('(a,b)', '(a.b,c)')
+
+A recursive op on the path side denotes unboundedly many expansions, so
+only a recursive pattern that subsumes it will match:
+
+    >>> dotted.match('**', 'a.**')
+    'a.**'
+    >>> dotted.match('**', '*b')
+    '*b'
+    >>> dotted.match('*', '**')
+
 <a id="replace"></a>
 ### Replace
 

{dotted_notation-0.44.7 → dotted_notation-0.44.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dotted_notation"
-version = "0.44.7"
+version = "0.44.8"
 description = "Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms"
 readme = "README.md"
 requires-python = ">=3.6"