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

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

@@ -3,6 +3,25 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.44.3]
+
+### Fixed
+- Transforms with a dict (or other nested-container) argument, e.g.
+  `code|lookup:{"a": 1}`, no longer raise `TypeError: unhashable type: 'dict'`
+  when the path is parsed. `Transform.__hash__` now freezes container params
+  recursively.
+
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.1
+Version: 0.44.3
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -176,6 +176,7 @@ Or pick only what you need:
   - [Projection](#projection)
   - [Unpack](#unpack)
   - [Pack](#pack)
+- [Recipes](#recipes)
 - [FAQ](#faq)
   - [Why do I get a tuple for my get?](#why-do-i-get-a-tuple-for-my-get)
   - [How do I craft an efficient path?](#how-do-i-craft-an-efficient-path)
@@ -729,6 +730,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
 
@@ -771,10 +802,13 @@ normal form. All three call `unpack()` internally.
     >>> dotted.keys({'a': 1, 'b': 2}) & dotted.keys({'b': 3, 'c': 4})
     {'b'}
 
-All three accept `attrs=` (same as `unpack`):
+All three accept the same `attrs=`, `project=`, and `partial=` arguments as
+`unpack`:
 
     >>> dotted.keys({'point': Pt(3, 4)}, attrs=[dotted.Attrs.standard])
     dict_keys(['point@x', 'point@y'])
+    >>> dotted.items({'a': {'b': 1, 'c': 2}, 'x': 3}, project='a')
+    dict_items([('a.b', 1), ('a.c', 2)])
 
 <a id="build"></a>
 ### Build
@@ -2926,7 +2960,7 @@ Fragments concatenate naturally via `+` / `__radd__`; metadata merges:
     >>> r = dotted.sqlize("age >= $(min_age)", driver='asyncpg')
     >>> combined = "WHERE " + r.where
     >>> r.build(combined, min_age=30)
-    ('WHERE age >= $1::bigint', [30])
+    ('WHERE age >= $1', [30])
 
 ### Hoisted params
 
@@ -3090,7 +3124,7 @@ Pass a shared `ParamPool` to every `sqlize()` call that should compose:
     >>> r2 = dotted.sqlize('age >= 30',          driver='asyncpg', pool=pool)
     >>> combined = '(' + r1.where + ') AND (' + r2.where + ')'
     >>> dotted.Resolver.build(combined, paramstyle='dollar-numeric')
-    ('(status = $1) AND (age = $2)', ['active', 30])
+    ('(status = $1) AND (age >= $2)', ['active', 30])
 
 Substitutions by the same original name dedup across Resolvers sharing
 a pool — one slot, one value, back-referenced in the rendered SQL:
@@ -3147,7 +3181,7 @@ segment before building a `Raw`:
     Col('matched.customer')
     >>> Col('schema', 'table', 'col')
     Col('schema.table.col')
-    >>> Col('bad; DROP TABLE')
+    >>> Col('bad; DROP TABLE')                           # doctest: +IGNORE_EXCEPTION_DETAIL
     Traceback (most recent call last):
       ...
     dotted.TranslationError: Col part is not a plain identifier: 'bad; DROP TABLE'
@@ -3393,6 +3427,79 @@ example, removing an entire group without listing every key:
     echo '{"db.host": "localhost", "db.port": 5432, "app.debug": true}' | dq --pack --unpack remove -p db
     # {"app.debug": true}
 
+<a id="recipes"></a>
+## Recipes
+
+A grab-bag of one-liners that show off what the notation can do. Every example
+below runs as-is.
+
+**Flatten a nested list** (leaves only, any depth) — recurse through every slot
+with `*([*])`, then keep only the deepest match on each branch with `:-1`:
+
+    >>> import dotted
+    >>> dotted.get([1, 2, 3, [4, 5, [6, 7]]], '*([*]):-1')
+    (1, 2, 3, 4, 5, 6, 7)
+
+Because `:-1` is deepest-*per-branch*, shallow leaves survive alongside deep
+ones — a ragged list still flattens completely.
+
+**Collect every leaf value** of a nested dict — same idea with key recursion:
+
+    >>> dotted.get({'a': {'b': 1}, 'c': 2}, '**:-1')
+    (1, 2)
+
+**Find a key at any depth** — `**` recurses through dict keys, then continue
+with the key you want:
+
+    >>> dotted.get({'a': {'b': {'name': 'x'}}, 'name': 'y'}, '**.name')
+    ('x',)
+
+If the tree mixes lists and dicts, recurse through both with `*(*#, [*])`:
+
+    >>> dotted.get({'kids': [{'name': 'a'}, {'name': 'b'}]}, '*(*#, [*]).name')
+    ('a', 'b')
+
+**Find values matching a condition anywhere** — attach a value guard to the
+recursive walk:
+
+    >>> dotted.get({'a': {'b': 7, 'c': 3}, 'd': {'e': 9}}, '**>5')
+    (7, 9)
+
+**Bulk-update everything that matches** — the same pattern drives `update` and
+`remove`:
+
+    >>> dotted.update({'a': {'b': 7, 'c': 3}, 'd': 7}, '**=7', 99)
+    {'a': {'b': 99, 'c': 3}, 'd': 99}
+
+**Filter a list of dicts, then project a field** — combine a key-value filter
+with a continuation:
+
+    >>> users = [{'name': 'x', 'active': True},
+    ...          {'name': 'y', 'active': False},
+    ...          {'name': 'z', 'active': True}]
+    >>> dotted.get(users, '[*&active=true].name')
+    ('x', 'z')
+
+**Upsert** — update a list entry if it exists, else append, using cut (`#`) in a
+disjunction so the first matching branch wins:
+
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="a@x"#, +)].email', 'NEW')
+    {'emails': [{'email': 'NEW'}]}
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="z@x"#, +)]', {'email': 'z@x'})
+    {'emails': [{'email': 'a@x'}, {'email': 'z@x'}]}
+
+**Coerce on the way out** — pipe a value through transforms:
+
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'name|uppercase')
+    'BOB'
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'tags|len')
+    3
+
+See [Recursive Traversal](#recursive-traversal), [Filters](#filters), and
+[Transforms](#transforms) for the full story behind each of these.
+
 <a id="faq"></a>
 ## FAQ
 

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

@@ -136,6 +136,7 @@ Or pick only what you need:
   - [Projection](#projection)
   - [Unpack](#unpack)
   - [Pack](#pack)
+- [Recipes](#recipes)
 - [FAQ](#faq)
   - [Why do I get a tuple for my get?](#why-do-i-get-a-tuple-for-my-get)
   - [How do I craft an efficient path?](#how-do-i-craft-an-efficient-path)
@@ -689,6 +690,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
 
@@ -731,10 +762,13 @@ normal form. All three call `unpack()` internally.
     >>> dotted.keys({'a': 1, 'b': 2}) & dotted.keys({'b': 3, 'c': 4})
     {'b'}
 
-All three accept `attrs=` (same as `unpack`):
+All three accept the same `attrs=`, `project=`, and `partial=` arguments as
+`unpack`:
 
     >>> dotted.keys({'point': Pt(3, 4)}, attrs=[dotted.Attrs.standard])
     dict_keys(['point@x', 'point@y'])
+    >>> dotted.items({'a': {'b': 1, 'c': 2}, 'x': 3}, project='a')
+    dict_items([('a.b', 1), ('a.c', 2)])
 
 <a id="build"></a>
 ### Build
@@ -2886,7 +2920,7 @@ Fragments concatenate naturally via `+` / `__radd__`; metadata merges:
     >>> r = dotted.sqlize("age >= $(min_age)", driver='asyncpg')
     >>> combined = "WHERE " + r.where
     >>> r.build(combined, min_age=30)
-    ('WHERE age >= $1::bigint', [30])
+    ('WHERE age >= $1', [30])
 
 ### Hoisted params
 
@@ -3050,7 +3084,7 @@ Pass a shared `ParamPool` to every `sqlize()` call that should compose:
     >>> r2 = dotted.sqlize('age >= 30',          driver='asyncpg', pool=pool)
     >>> combined = '(' + r1.where + ') AND (' + r2.where + ')'
     >>> dotted.Resolver.build(combined, paramstyle='dollar-numeric')
-    ('(status = $1) AND (age = $2)', ['active', 30])
+    ('(status = $1) AND (age >= $2)', ['active', 30])
 
 Substitutions by the same original name dedup across Resolvers sharing
 a pool — one slot, one value, back-referenced in the rendered SQL:
@@ -3107,7 +3141,7 @@ segment before building a `Raw`:
     Col('matched.customer')
     >>> Col('schema', 'table', 'col')
     Col('schema.table.col')
-    >>> Col('bad; DROP TABLE')
+    >>> Col('bad; DROP TABLE')                           # doctest: +IGNORE_EXCEPTION_DETAIL
     Traceback (most recent call last):
       ...
     dotted.TranslationError: Col part is not a plain identifier: 'bad; DROP TABLE'
@@ -3353,6 +3387,79 @@ example, removing an entire group without listing every key:
     echo '{"db.host": "localhost", "db.port": 5432, "app.debug": true}' | dq --pack --unpack remove -p db
     # {"app.debug": true}
 
+<a id="recipes"></a>
+## Recipes
+
+A grab-bag of one-liners that show off what the notation can do. Every example
+below runs as-is.
+
+**Flatten a nested list** (leaves only, any depth) — recurse through every slot
+with `*([*])`, then keep only the deepest match on each branch with `:-1`:
+
+    >>> import dotted
+    >>> dotted.get([1, 2, 3, [4, 5, [6, 7]]], '*([*]):-1')
+    (1, 2, 3, 4, 5, 6, 7)
+
+Because `:-1` is deepest-*per-branch*, shallow leaves survive alongside deep
+ones — a ragged list still flattens completely.
+
+**Collect every leaf value** of a nested dict — same idea with key recursion:
+
+    >>> dotted.get({'a': {'b': 1}, 'c': 2}, '**:-1')
+    (1, 2)
+
+**Find a key at any depth** — `**` recurses through dict keys, then continue
+with the key you want:
+
+    >>> dotted.get({'a': {'b': {'name': 'x'}}, 'name': 'y'}, '**.name')
+    ('x',)
+
+If the tree mixes lists and dicts, recurse through both with `*(*#, [*])`:
+
+    >>> dotted.get({'kids': [{'name': 'a'}, {'name': 'b'}]}, '*(*#, [*]).name')
+    ('a', 'b')
+
+**Find values matching a condition anywhere** — attach a value guard to the
+recursive walk:
+
+    >>> dotted.get({'a': {'b': 7, 'c': 3}, 'd': {'e': 9}}, '**>5')
+    (7, 9)
+
+**Bulk-update everything that matches** — the same pattern drives `update` and
+`remove`:
+
+    >>> dotted.update({'a': {'b': 7, 'c': 3}, 'd': 7}, '**=7', 99)
+    {'a': {'b': 99, 'c': 3}, 'd': 99}
+
+**Filter a list of dicts, then project a field** — combine a key-value filter
+with a continuation:
+
+    >>> users = [{'name': 'x', 'active': True},
+    ...          {'name': 'y', 'active': False},
+    ...          {'name': 'z', 'active': True}]
+    >>> dotted.get(users, '[*&active=true].name')
+    ('x', 'z')
+
+**Upsert** — update a list entry if it exists, else append, using cut (`#`) in a
+disjunction so the first matching branch wins:
+
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="a@x"#, +)].email', 'NEW')
+    {'emails': [{'email': 'NEW'}]}
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="z@x"#, +)]', {'email': 'z@x'})
+    {'emails': [{'email': 'a@x'}, {'email': 'z@x'}]}
+
+**Coerce on the way out** — pipe a value through transforms:
+
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'name|uppercase')
+    'BOB'
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'tags|len')
+    3
+
+See [Recursive Traversal](#recursive-traversal), [Filters](#filters), and
+[Transforms](#transforms) for the full story behind each of these.
+
 <a id="faq"></a>
 ## FAQ
 

{dotted_notation-0.44.1 → dotted_notation-0.44.3}/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.3}/dotted/base.py

@@ -272,8 +272,8 @@ class Transform(Op):
         try:
             return hash(('transform', self.name, self.params))
         except TypeError:
-            return hash(('transform', self.name,
-                         tuple(tuple(p) if isinstance(p, list) else p for p in self.params)))
+            from .results import Dotted
+            return hash(('transform', self.name, Dotted._hashable(self.params)))
 
     def __eq__(self, other):
         return (isinstance(other, Transform)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.1
+Version: 0.44.3
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -176,6 +176,7 @@ Or pick only what you need:
   - [Projection](#projection)
   - [Unpack](#unpack)
   - [Pack](#pack)
+- [Recipes](#recipes)
 - [FAQ](#faq)
   - [Why do I get a tuple for my get?](#why-do-i-get-a-tuple-for-my-get)
   - [How do I craft an efficient path?](#how-do-i-craft-an-efficient-path)
@@ -729,6 +730,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
 
@@ -771,10 +802,13 @@ normal form. All three call `unpack()` internally.
     >>> dotted.keys({'a': 1, 'b': 2}) & dotted.keys({'b': 3, 'c': 4})
     {'b'}
 
-All three accept `attrs=` (same as `unpack`):
+All three accept the same `attrs=`, `project=`, and `partial=` arguments as
+`unpack`:
 
     >>> dotted.keys({'point': Pt(3, 4)}, attrs=[dotted.Attrs.standard])
     dict_keys(['point@x', 'point@y'])
+    >>> dotted.items({'a': {'b': 1, 'c': 2}, 'x': 3}, project='a')
+    dict_items([('a.b', 1), ('a.c', 2)])
 
 <a id="build"></a>
 ### Build
@@ -2926,7 +2960,7 @@ Fragments concatenate naturally via `+` / `__radd__`; metadata merges:
     >>> r = dotted.sqlize("age >= $(min_age)", driver='asyncpg')
     >>> combined = "WHERE " + r.where
     >>> r.build(combined, min_age=30)
-    ('WHERE age >= $1::bigint', [30])
+    ('WHERE age >= $1', [30])
 
 ### Hoisted params
 
@@ -3090,7 +3124,7 @@ Pass a shared `ParamPool` to every `sqlize()` call that should compose:
     >>> r2 = dotted.sqlize('age >= 30',          driver='asyncpg', pool=pool)
     >>> combined = '(' + r1.where + ') AND (' + r2.where + ')'
     >>> dotted.Resolver.build(combined, paramstyle='dollar-numeric')
-    ('(status = $1) AND (age = $2)', ['active', 30])
+    ('(status = $1) AND (age >= $2)', ['active', 30])
 
 Substitutions by the same original name dedup across Resolvers sharing
 a pool — one slot, one value, back-referenced in the rendered SQL:
@@ -3147,7 +3181,7 @@ segment before building a `Raw`:
     Col('matched.customer')
     >>> Col('schema', 'table', 'col')
     Col('schema.table.col')
-    >>> Col('bad; DROP TABLE')
+    >>> Col('bad; DROP TABLE')                           # doctest: +IGNORE_EXCEPTION_DETAIL
     Traceback (most recent call last):
       ...
     dotted.TranslationError: Col part is not a plain identifier: 'bad; DROP TABLE'
@@ -3393,6 +3427,79 @@ example, removing an entire group without listing every key:
     echo '{"db.host": "localhost", "db.port": 5432, "app.debug": true}' | dq --pack --unpack remove -p db
     # {"app.debug": true}
 
+<a id="recipes"></a>
+## Recipes
+
+A grab-bag of one-liners that show off what the notation can do. Every example
+below runs as-is.
+
+**Flatten a nested list** (leaves only, any depth) — recurse through every slot
+with `*([*])`, then keep only the deepest match on each branch with `:-1`:
+
+    >>> import dotted
+    >>> dotted.get([1, 2, 3, [4, 5, [6, 7]]], '*([*]):-1')
+    (1, 2, 3, 4, 5, 6, 7)
+
+Because `:-1` is deepest-*per-branch*, shallow leaves survive alongside deep
+ones — a ragged list still flattens completely.
+
+**Collect every leaf value** of a nested dict — same idea with key recursion:
+
+    >>> dotted.get({'a': {'b': 1}, 'c': 2}, '**:-1')
+    (1, 2)
+
+**Find a key at any depth** — `**` recurses through dict keys, then continue
+with the key you want:
+
+    >>> dotted.get({'a': {'b': {'name': 'x'}}, 'name': 'y'}, '**.name')
+    ('x',)
+
+If the tree mixes lists and dicts, recurse through both with `*(*#, [*])`:
+
+    >>> dotted.get({'kids': [{'name': 'a'}, {'name': 'b'}]}, '*(*#, [*]).name')
+    ('a', 'b')
+
+**Find values matching a condition anywhere** — attach a value guard to the
+recursive walk:
+
+    >>> dotted.get({'a': {'b': 7, 'c': 3}, 'd': {'e': 9}}, '**>5')
+    (7, 9)
+
+**Bulk-update everything that matches** — the same pattern drives `update` and
+`remove`:
+
+    >>> dotted.update({'a': {'b': 7, 'c': 3}, 'd': 7}, '**=7', 99)
+    {'a': {'b': 99, 'c': 3}, 'd': 99}
+
+**Filter a list of dicts, then project a field** — combine a key-value filter
+with a continuation:
+
+    >>> users = [{'name': 'x', 'active': True},
+    ...          {'name': 'y', 'active': False},
+    ...          {'name': 'z', 'active': True}]
+    >>> dotted.get(users, '[*&active=true].name')
+    ('x', 'z')
+
+**Upsert** — update a list entry if it exists, else append, using cut (`#`) in a
+disjunction so the first matching branch wins:
+
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="a@x"#, +)].email', 'NEW')
+    {'emails': [{'email': 'NEW'}]}
+    >>> dotted.update({'emails': [{'email': 'a@x'}]},
+    ...               'emails[(*&email="z@x"#, +)]', {'email': 'z@x'})
+    {'emails': [{'email': 'a@x'}, {'email': 'z@x'}]}
+
+**Coerce on the way out** — pipe a value through transforms:
+
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'name|uppercase')
+    'BOB'
+    >>> dotted.get({'name': 'bob', 'tags': [1, 2, 3]}, 'tags|len')
+    3
+
+See [Recursive Traversal](#recursive-traversal), [Filters](#filters), and
+[Transforms](#transforms) for the full story behind each of these.
+
 <a id="faq"></a>
 ## FAQ
 

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

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