dotted-notation 0.44.1__tar.gz → 0.44.2__tar.gz

{dotted_notation-0.44.1 → dotted_notation-0.44.2}/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.44.2]
+
+### Added
+- `unpack(obj, project=...)` keeps only the leaf paths selected by one or
+  more dotted patterns. Selection is directional (a leaf survives if it
+  `match`es a pattern), so projecting `a.b` never pulls in a shallower scalar
+  `a`. Matching defaults to `partial=True` (trailing segment is greedy); pass
+  `partial=False` for exact-depth matching, or override per field with a
+  `(pattern, partial)` tuple. `project=`/`partial=` also flow through `keys`,
+  `values`, and `items`.
+
 ## [0.44.1]
 
 ### Added

{dotted_notation-0.44.1/dotted_notation.egg-info → dotted_notation-0.44.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.1
+Version: 0.44.2
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -729,6 +729,36 @@ For example:
 
 Pass both to include all attributes: `attrs=[Attrs.standard, Attrs.special]`.
 
+Pass `project=` to keep only the leaf paths selected by one or more dotted
+patterns. Selection is *directional* — a leaf survives if it `match`es a
+projection pattern — so projecting `a.b` never drags in a shallower scalar leaf
+`a`:
+
+    >>> o = {'a': {'b': 1, 'c': 2}, 'x': {'y': {'z': 3}}, 'extra': 9}
+    >>> dotted.unpack(o, project='a')
+    {'a.b': 1, 'a.c': 2}
+    >>> dotted.unpack(o, project=['a', 'x.y.z'])
+    {'a.b': 1, 'a.c': 2, 'x.y.z': 3}
+
+Matching uses `match`'s `partial=True` by default, so a trailing segment is
+greedy (`a.*` also keeps `a.b.c`). Set `partial=False` for exact-depth matching,
+where `a.*`, `a.*.*`, and `a.**` are all distinct:
+
+    >>> deep = {'a': {'b': {'c': 1}}, 'd': 9}
+    >>> dotted.unpack(deep, project='a.*', partial=False)
+    {}
+    >>> dotted.unpack(deep, project='a.**', partial=False)
+    {'a.b.c': 1}
+
+Override `partial` per field with a `(pattern, partial)` tuple — bare patterns
+inherit the global setting. This matters for mid-pattern matches that `**`
+cannot express (e.g. `a.*.c` keeping both `a.x.c` and `a.x.c.d`):
+
+    >>> dotted.unpack(deep, project=[('a.*', True), 'd'], partial=False)
+    {'a.b.c': 1, 'd': 9}
+
+`project=` and `partial=` also flow through `keys()`, `values()`, and `items()`.
+
 <a id="pack"></a>
 ### Pack
 

{dotted_notation-0.44.1 → dotted_notation-0.44.2}/README.md

@@ -689,6 +689,36 @@ For example:
 
 Pass both to include all attributes: `attrs=[Attrs.standard, Attrs.special]`.
 
+Pass `project=` to keep only the leaf paths selected by one or more dotted
+patterns. Selection is *directional* — a leaf survives if it `match`es a
+projection pattern — so projecting `a.b` never drags in a shallower scalar leaf
+`a`:
+
+    >>> o = {'a': {'b': 1, 'c': 2}, 'x': {'y': {'z': 3}}, 'extra': 9}
+    >>> dotted.unpack(o, project='a')
+    {'a.b': 1, 'a.c': 2}
+    >>> dotted.unpack(o, project=['a', 'x.y.z'])
+    {'a.b': 1, 'a.c': 2, 'x.y.z': 3}
+
+Matching uses `match`'s `partial=True` by default, so a trailing segment is
+greedy (`a.*` also keeps `a.b.c`). Set `partial=False` for exact-depth matching,
+where `a.*`, `a.*.*`, and `a.**` are all distinct:
+
+    >>> deep = {'a': {'b': {'c': 1}}, 'd': 9}
+    >>> dotted.unpack(deep, project='a.*', partial=False)
+    {}
+    >>> dotted.unpack(deep, project='a.**', partial=False)
+    {'a.b.c': 1}
+
+Override `partial` per field with a `(pattern, partial)` tuple — bare patterns
+inherit the global setting. This matters for mid-pattern matches that `**`
+cannot express (e.g. `a.*.c` keeping both `a.x.c` and `a.x.c.d`):
+
+    >>> dotted.unpack(deep, project=[('a.*', True), 'd'], partial=False)
+    {'a.b.c': 1, 'd': 9}
+
+`project=` and `partial=` also flow through `keys()`, `values()`, and `items()`.
+
 <a id="pack"></a>
 ### Pack
 

{dotted_notation-0.44.1 → dotted_notation-0.44.2}/dotted/api.py

@@ -1099,7 +1099,7 @@ def pack(pathvalues, apply_transforms=True, strict=False, bindings=None):
     return update_multi(AUTO, pathvalues, apply_transforms=apply_transforms, strict=strict, bindings=bindings)
 
 
-def unpack(obj, attrs=None):
+def unpack(obj, attrs=None, project=None, partial=True):
     """
     Convert obj to dotted normal form.  A dict mapping dotted paths to leaf
     values, which can be replayed to regenerate the obj (see `pack`).
@@ -1117,6 +1117,27 @@ def unpack(obj, attrs=None):
     {'a.b': [1, 2, 3], 'x.y.z': [4, 5], 'extra': 'stuff'}
     >>> pack(r) == d
     True
+
+    Pass project= to keep only the leaf paths selected by one or more dotted
+    patterns.  A leaf survives if it `match`es any projection pattern, so
+    selection is directional: projecting 'a.b' never pulls in a scalar leaf
+    'a'.  project= accepts a single pattern or an iterable of them:
+
+    >>> o = {'a': {'b': 1, 'c': 2}, 'x': {'y': {'z': 3}}, 'extra': 9}
+    >>> unpack(o, project='a')
+    {'a.b': 1, 'a.c': 2}
+    >>> unpack(o, project=['a', 'x.y.z'])
+    {'a.b': 1, 'a.c': 2, 'x.y.z': 3}
+
+    Matching uses match()'s `partial=True` by default, so a trailing segment
+    is greedy ('a.*' also keeps 'a.b.c').  Set partial=False for exact-depth
+    matching, or override it per-field with a (pattern, partial) tuple:
+
+    >>> deep = {'a': {'b': {'c': 1}}, 'd': 9}
+    >>> unpack(deep, project='a.*', partial=False)
+    {}
+    >>> unpack(deep, project=[('a.*', True), 'd'])
+    {'a.b.c': 1, 'd': 9}
     """
     # Accept either `Attrs` enum members or their string values.
     attr_values = {a.value if isinstance(a, Attrs) else a for a in (attrs or ())}
@@ -1128,43 +1149,58 @@ def unpack(obj, attrs=None):
         extra = ', @/(?!__).*/'
     else:
         extra = ', @/__.*/'
-    return dict(pluck(obj, f'*(*#, [*]:!(str, bytes){extra}):-2(.*, []{extra})##, (*, []{extra})'))
+    result = dict(pluck(obj, f'*(*#, [*]:!(str, bytes){extra}):-2(.*, []{extra})##, (*, []{extra})'))
+    if project is None:
+        return result
+    if isinstance(project, str):
+        project = [project]
+    # Normalize each entry to (pattern, partial); bare patterns inherit the
+    # global `partial`, (pattern, partial) tuples override it per-field.
+    specs = [(p, partial) if isinstance(p, str) else tuple(p) for p in project]
+    return {k: v for k, v in result.items()
+            if any(match(pat, k, partial=pp) for pat, pp in specs)}
 
 
-def items(obj, attrs=None):
+def items(obj, attrs=None, project=None, partial=True):
     """
     Return (path, value) pairs of obj in normal form as a dict_items view.
-    Internally calls unpack().
+    Internally calls unpack(); accepts project=/partial= (see unpack).
 
     >>> d = {'a': {'b': 1}, 'x': 2}
     >>> sorted(items(d))
     [('a.b', 1), ('x', 2)]
+    >>> sorted(items(d, project='a'))
+    [('a.b', 1)]
     """
-    return unpack(obj, attrs=attrs).items()
+    return unpack(obj, attrs=attrs, project=project, partial=partial).items()
 
 
-def keys(obj, attrs=None):
+def keys(obj, attrs=None, project=None, partial=True):
     """
     Return the dotted paths of obj in normal form as dict_keys.
-    Internally calls unpack().
+    Internally calls unpack(); accepts project=/partial= (see unpack).
 
     >>> d = {'a': {'b': 1}, 'x': 2}
     >>> sorted(keys(d))
     ['a.b', 'x']
+    >>> sorted(keys(d, project='a'))
+    ['a.b']
     """
-    return unpack(obj, attrs=attrs).keys()
+    return unpack(obj, attrs=attrs, project=project, partial=partial).keys()
 
 
-def values(obj, attrs=None):
+def values(obj, attrs=None, project=None, partial=True):
     """
     Return the leaf values of obj in normal form.
-    Internally calls unpack().
+    Internally calls unpack(); accepts project=/partial= (see unpack).
 
     >>> d = {'a': {'b': 1}, 'x': 2}
     >>> sorted(values(d))
     [1, 2]
+    >>> sorted(values(d, project='a'))
+    [1]
     """
-    return unpack(obj, attrs=attrs).values()
+    return unpack(obj, attrs=attrs, project=project, partial=partial).values()
 
 
 #

{dotted_notation-0.44.1 → dotted_notation-0.44.2/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.1
+Version: 0.44.2
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -729,6 +729,36 @@ For example:
 
 Pass both to include all attributes: `attrs=[Attrs.standard, Attrs.special]`.
 
+Pass `project=` to keep only the leaf paths selected by one or more dotted
+patterns. Selection is *directional* — a leaf survives if it `match`es a
+projection pattern — so projecting `a.b` never drags in a shallower scalar leaf
+`a`:
+
+    >>> o = {'a': {'b': 1, 'c': 2}, 'x': {'y': {'z': 3}}, 'extra': 9}
+    >>> dotted.unpack(o, project='a')
+    {'a.b': 1, 'a.c': 2}
+    >>> dotted.unpack(o, project=['a', 'x.y.z'])
+    {'a.b': 1, 'a.c': 2, 'x.y.z': 3}
+
+Matching uses `match`'s `partial=True` by default, so a trailing segment is
+greedy (`a.*` also keeps `a.b.c`). Set `partial=False` for exact-depth matching,
+where `a.*`, `a.*.*`, and `a.**` are all distinct:
+
+    >>> deep = {'a': {'b': {'c': 1}}, 'd': 9}
+    >>> dotted.unpack(deep, project='a.*', partial=False)
+    {}
+    >>> dotted.unpack(deep, project='a.**', partial=False)
+    {'a.b.c': 1}
+
+Override `partial` per field with a `(pattern, partial)` tuple — bare patterns
+inherit the global setting. This matters for mid-pattern matches that `**`
+cannot express (e.g. `a.*.c` keeping both `a.x.c` and `a.x.c.d`):
+
+    >>> dotted.unpack(deep, project=[('a.*', True), 'd'], partial=False)
+    {'a.b.c': 1, 'd': 9}
+
+`project=` and `partial=` also flow through `keys()`, `values()`, and `items()`.
+
 <a id="pack"></a>
 ### Pack
 

{dotted_notation-0.44.1 → dotted_notation-0.44.2}/pyproject.toml

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