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

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

@@ -3,6 +3,14 @@
 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

{dotted_notation-0.44.2/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.2
+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)
@@ -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.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)
@@ -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.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.2 → 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.2
+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)
@@ -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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dotted_notation"
-version = "0.44.2"
+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"