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

{dotted_notation-0.44.2 → dotted_notation-0.44.4}/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.4]
+
+### Added
+- Module-level escape hatches: `dotted.set_simple_fastpath(False)` disables
+  the get() fast path (everything goes through walk()), and
+  `dotted.set_parse_cache(size)` resizes the LRU cache behind parse()
+  (0 disables, None unbounded). Both return the previous setting.
+
+### Performance
+- `get()` fast path for simple paths (#58): a plain chain of literal
+  Key/Attr/Slot accesses (`a.b`, `a[0].b`, `a@x`) resolves with direct
+  dict/list/attr lookups, skipping the walk() machinery entirely. The
+  chain is computed once at parse time and cached on the `Dotted`
+  (`simple_chain`); unusual containers (dict subclasses, custom
+  mappings) fall back to the full traversal.
+- `Const.value`/`Numeric.value` are now computed once and cached on the
+  instance instead of recomputed per property access.
+- `Dotted.__hash__` is cached, making repeated cache lookups keyed on a
+  pre-parsed `Dotted` (e.g. `get(obj, parsed)`) much cheaper.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.2
+Version: 0.44.4
 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)
@@ -801,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
@@ -2956,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
 
@@ -3120,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:
@@ -3177,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'
@@ -3423,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.2 → dotted_notation-0.44.4}/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)
@@ -761,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
@@ -2916,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
 
@@ -3080,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:
@@ -3137,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'
@@ -3383,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.2 → dotted_notation-0.44.4}/dotted/__init__.py

@@ -58,6 +58,7 @@ For full documentation including all options and flags:
 from .api import \
     parse, is_pattern, is_template, is_reference, is_indeterminate, is_simple, \
     is_inverted, is_mutable, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
+    set_simple_fastpath, set_parse_cache, \
     register, transform, \
     assemble, assemble_multi, \
     build, build_multi, \
@@ -87,6 +88,7 @@ __all__ = [
     'is_pattern', 'is_template', 'is_reference',
     'is_indeterminate', 'is_simple',
     'is_inverted', 'is_mutable', 'mutable',
+    'set_simple_fastpath', 'set_parse_cache',
     # SQL
     'sqlize', 'Resolver', 'SQLFragment', 'ParamStyle', 'ParamPool', 'TranslationError',
     # Constants

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

@@ -69,6 +69,32 @@ class ParseError(Exception):
 
 _parse_lock = threading.Lock()
 
+_SIMPLE_FASTPATH = True
+
+
+def set_simple_fastpath(enable=True):
+    """
+    Enable/disable the simple-path fast path in get() (escape hatch: when
+    off, every lookup goes through the full walk() traversal). On by
+    default. Returns the previous setting.
+    """
+    global _SIMPLE_FASTPATH
+    prev = _SIMPLE_FASTPATH
+    _SIMPLE_FASTPATH = bool(enable)
+    return prev
+
+
+def set_parse_cache(size=CACHE_SIZE):
+    """
+    Resize the LRU cache behind parse(). 0 disables caching (every path
+    string is re-parsed from scratch); None makes it unbounded. Resizing
+    discards currently cached parses. Returns the previous size.
+    """
+    global _parse
+    prev = _parse.cache_info().maxsize
+    _parse = functools.lru_cache(size)(_parse.__wrapped__)
+    return prev
+
 
 @functools.lru_cache(CACHE_SIZE)
 def _parse(ops):
@@ -234,16 +260,6 @@ def is_indeterminate(path):
     return _is_template(parsed) or _is_reference(parsed)
 
 
-@functools.lru_cache(CACHE_SIZE)
-def _is_simple(ops):
-    for op in ops:
-        if not isinstance(op, (access.Key, access.Attr, access.Slot)):
-            return False
-        if not isinstance(op.op, matchers.Const):
-            return False
-    return True
-
-
 def is_simple(path):
     """
     True if the path is a plain chain of access ops (Key, Attr, Slot)
@@ -271,9 +287,7 @@ def is_simple(path):
     False
     """
     parsed = path if isinstance(path, results.Dotted) else parse(path)
-    if parsed.transforms:
-        return False
-    return _is_simple(parsed)
+    return parsed.simple_chain is not None
 
 
 def is_inverted(path):
@@ -433,6 +447,11 @@ def get(obj, path, default=None, pattern_default=(), apply_transforms=True, stri
     (7,)
     """
     ops = parse(path, bindings=bindings, partial=False)
+    chain = ops.simple_chain if _SIMPLE_FASTPATH else None
+    if chain is not None:
+        val = engine.simple_get(chain, obj, strict=strict)
+        if val is not engine.SIMPLE_BAIL:
+            return default if val is base.marker else val
     vals = engine.iter_until_cut(engine.gets(ops, obj, strict=strict))
     if apply_transforms:
         vals = ( ops.apply(v) for v in vals )

{dotted_notation-0.44.2 → dotted_notation-0.44.4}/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.2 → dotted_notation-0.44.4}/dotted/engine.py

@@ -48,6 +48,48 @@ def build(ops, node, deepcopy=True, **kwargs):
     return built or build_default([cur]+ops)
 
 
+SIMPLE_BAIL = object()
+
+
+def simple_get(chain, node, strict=False):
+    """
+    Fast path for simple paths (see Dotted.simple_chain): follow literal
+    keys with direct dict/list/attr access, skipping walk() entirely.
+    Returns the found value, base.marker when the path misses, or
+    SIMPLE_BAIL when a node's type falls outside the fast path — the
+    caller then falls back to the full traversal.
+    """
+    for kind, key in chain:
+        if kind == 'attr':
+            node = getattr(node, key, base.marker)
+            if node is base.marker:
+                return base.marker
+            continue
+        t = type(node)
+        if t is dict:
+            # strict: Slot never coerces to dict keys
+            if strict and kind == 'slot':
+                return base.marker
+            node = node.get(key, base.marker)
+            if node is base.marker:
+                return base.marker
+            continue
+        if t is list or t is tuple:
+            # strict: Key never coerces to sequence indices
+            if strict and kind == 'key':
+                return base.marker
+            if type(key) is not int:
+                return base.marker
+            try:
+                node = node[key]
+            except IndexError:
+                return base.marker
+            continue
+        # dict subclasses, custom containers, None, etc: full traversal
+        return SIMPLE_BAIL
+    return node
+
+
 def iter_until_cut(gen):
     """
     Consume a get generator until base.CUT_SENTINEL; yield values, stop on sentinel.

{dotted_notation-0.44.2 → dotted_notation-0.44.4}/dotted/matchers.py

@@ -10,6 +10,7 @@ import pyparsing as pp
 
 from . import base
 from .base import MatchOp
+from .utils import lazyprop
 from .utypes import ANY
 
 
@@ -19,8 +20,11 @@ _MISSING = object()
 class Const(MatchOp):
     _match_from = ('Const',)
 
-    @property
+    @lazyprop
     def value(self):
+        """
+        The literal value; computed once and cached on the instance.
+        """
         return self.args[0]
     def matches(self, vals):
         return (v for v in vals if self.value == v)
@@ -32,8 +36,11 @@ class Numeric(Const):
             return str(self.args[0]) == str(int(self.args[0]))
         except (ValueError, TypeError):
             return False
-    @property
+    @lazyprop
     def value(self):
+        """
+        The numeric value (int when possible); computed once and cached.
+        """
         return int(self.args[0]) if self.is_int() else float(self.args[0])
     def __repr__(self):
         return f'{self.value}'

{dotted_notation-0.44.2 → dotted_notation-0.44.4}/dotted/results.py

@@ -5,7 +5,9 @@ import itertools
 
 from . import predicates
 from . import utils
-from .access import Invert
+from .access import Attr, Invert, Key, Slot
+from .matchers import Const
+from .utils import lazyprop
 
 
 class rdoc(str):
@@ -35,6 +37,7 @@ class Dotted:
         else:
             self.guard = None
             self.guard_op = predicates.EQ
+        self._hash = None
 
     @property
     def guard_negate(self):
@@ -72,10 +75,12 @@ class Dotted:
             return tuple(sorted((k, Dotted._hashable(v)) for k, v in iterable))
         return obj
     def __hash__(self):
-        try:
-            return hash((self.ops, self.transforms, self.guard, self.guard_op))
-        except TypeError:
-            return hash((self.ops, Dotted._hashable(self.transforms), self.guard, self.guard_op))
+        if self._hash is None:
+            try:
+                self._hash = hash((self.ops, self.transforms, self.guard, self.guard_op))
+            except TypeError:
+                self._hash = hash((self.ops, Dotted._hashable(self.transforms), self.guard, self.guard_op))
+        return self._hash
     def __len__(self):
         return len(self.ops)
     def __iter__(self):
@@ -105,6 +110,28 @@ class Dotted:
     def apply(self, val):
         return apply_transforms(val, self.transforms)
 
+    @lazyprop
+    def simple_chain(self):
+        """
+        Tuple of (kind, key) pairs when this path is simple — a plain chain
+        of concrete Key/Attr/Slot accesses with no patterns, substitutions,
+        references, guards, transforms, or filters — else None. Computed
+        once and cached; drives the fast path in get() that skips walk().
+        kind is 'key', 'attr', or 'slot'.
+        """
+        if self.transforms or self.guard is not None:
+            return None
+        chain = []
+        for op in self.ops:
+            # exact types: subclasses like SlotSpecial have different semantics
+            if type(op) not in (Key, Attr, Slot):
+                return None
+            if not isinstance(op.op, Const):
+                return None
+            kind = 'attr' if isinstance(op, Attr) else 'slot' if isinstance(op, Slot) else 'key'
+            chain.append((kind, op.op.value))
+        return tuple(chain)
+
 Dotted.registry.__doc__ = rdoc()
 
 

{dotted_notation-0.44.2 → dotted_notation-0.44.4}/dotted/utils.py

@@ -2,6 +2,25 @@
 Shared type-checking helpers (duck-typing).
 """
 
+class lazyprop:
+    """
+    Non-data descriptor: compute once on first access, cache the result
+    in the instance __dict__ (which then shadows the descriptor). Like
+    functools.cached_property but lock-free and available on 3.6+.
+    """
+    def __init__(self, fn):
+        self.fn = fn
+        self.name = fn.__name__
+        self.__doc__ = fn.__doc__
+
+    def __get__(self, obj, owner=None):
+        if obj is None:
+            return self
+        val = self.fn(obj)
+        obj.__dict__[self.name] = val
+        return val
+
+
 try:
     import dataclasses as _dc
 except ImportError:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.44.2
+Version: 0.44.4
 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)
@@ -801,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
@@ -2956,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
 
@@ -3120,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:
@@ -3177,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'
@@ -3423,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.2 → dotted_notation-0.44.4}/pyproject.toml

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