dotted-notation 0.43.16__tar.gz → 0.44.0__tar.gz

{dotted_notation-0.43.16 → dotted_notation-0.44.0}/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.44.0]
+
+### Changed (breaking)
+- Public-API parameter renamed from `key` to `path` across `get`,
+  `update`, `update_if`, `remove`, `remove_if`, `has`, `setdefault`,
+  `build`, `mutable`, `match`, `parse`, and all `is_*` predicates.
+  Positional calls are unaffected; keyword callers must update
+  (e.g. `update(obj, key=...)` → `update(obj, path=...)`).
+- `build_multi(obj, keys=...)` → `build_multi(obj, paths=...)`.
+- `setdefault_multi`, `update_multi`, `pack` rename `keyvalues=` to
+  `pathvalues=`.
+- `remove_multi` / `remove_if_multi` rename `keys_only=` to
+  `paths_only=`.
+- `assemble` / `assemble_multi` rename `keys`/`keys_list` to
+  `segments`/`segments_list`.
+- `remove_if` default pred signature: `lambda key: key is not None` →
+  `lambda path: path is not None`.
+- `expand_multi`, `pluck_multi`, `assemble_multi` now return a **generator**
+  instead of a tuple, aligning with `get_multi`, `match_multi`, `walk_multi`,
+  `translate_multi`, `setdefault_multi`. Callers that consumed the return as a
+  tuple (indexing, `len()`, equality) must wrap with `tuple(...)` /
+  `list(...)`. Singular forms (`expand`, `pluck`, `assemble`) unchanged.
+
+### Added
+- `is_mutable` — preferred alias for `mutable`, parallels
+  `is_pattern`, `is_template`, etc. `mutable` remains as an alias.
+
+### Rationale
+- The library distinguishes a *path* (the whole dotted expression)
+  from a *path segment* or *field* (one component), with *key field*
+  referring specifically to the dot-notation kind (vs bracket or
+  attr fields). Using bare `key` as a parameter name for the whole
+  path conflated those. Docs and API now use precise terminology.
+
 ## [0.43.16]
 
 ### Added

{dotted_notation-0.43.16/dotted_notation.egg-info → dotted_notation-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.16
+Version: 0.44.0
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License: MIT
@@ -247,6 +247,39 @@ Several Python libraries handle nested data access. Here's how dotted compares:
 <a id="breaking-changes"></a>
 ## Breaking Changes
 
+### v0.44.0
+- **Parameter renamed from `key` to `path`** across the public API to align with
+  the terminology used throughout the docs (a _path_ is the whole dotted
+  expression; a _path segment_ or _field_ is one component). Positional calls
+  are unaffected; keyword callers must update:
+  - `get(obj, key=...)` → `get(obj, path=...)`
+  - `update(obj, key=...)`, `update_if(obj, key=...)` → `update(obj, path=...)`, etc.
+  - `remove(obj, key=...)`, `remove_if(obj, key=...)` → `remove(obj, path=...)`, etc.
+  - `has`, `setdefault`, `build`, `mutable`, `match` — same rename
+  - `is_pattern(key=...)`, `is_template(key=...)`, `is_reference(key=...)`,
+    `is_indeterminate(key=...)`, `is_simple(key=...)`, `is_inverted(key=...)` —
+    all take `path=` now.
+  - `parse(key=...)` → `parse(path=...)`
+  - `build_multi(obj, keys=...)` → `build_multi(obj, paths=...)`
+  - `setdefault_multi(obj, keyvalues=...)`, `update_multi(obj, keyvalues=...)` →
+    `setdefault_multi(obj, pathvalues=...)`, `update_multi(obj, pathvalues=...)`
+  - `pack(keyvalues=...)` → `pack(pathvalues=...)`
+  - `remove_multi(..., keys_only=...)`, `remove_if_multi(..., keys_only=...)` →
+    `remove_multi(..., paths_only=...)`, `remove_if_multi(..., paths_only=...)`
+  - `assemble(keys)` / `assemble_multi(keys_list)` → `assemble(segments)` /
+    `assemble_multi(segments_list)`
+  - `remove_if` default pred signature: `lambda key: key is not None` →
+    `lambda path: path is not None`
+- **`is_mutable` added as the preferred name for `mutable`** — parallels the
+  other `is_*` predicates. `mutable` remains as an alias.
+- **`expand_multi`, `pluck_multi`, `assemble_multi` now return a generator**
+  instead of a tuple, aligning with the other read-side `_multi` APIs
+  (`get_multi`, `match_multi`, `walk_multi`, `translate_multi`,
+  `setdefault_multi`). Callers that consumed the return as a tuple (indexing
+  `r[0]`, `len(r)`, equality `r == (...)`) must now materialize:
+  `tuple(pluck_multi(...))`. The singular forms (`expand`, `pluck`, `assemble`)
+  are unchanged.
+
 ### v0.43.4
 - **`is_pattern` no longer returns `True` for substitutions**. `Subst` previously
   inherited from `Pattern` in the class hierarchy, so any path containing a
@@ -327,7 +360,7 @@ Parsed dotted paths are LRU-cached (after the first parse of a given path string
 <a id="get"></a>
 ### Get
 
-See the Paths, Patterns, and Operators sections below for the full notation.
+Get the value at a dotted path. See the Paths, Patterns, and Operators sections below for the full notation.
 
     >>> import dotted
     >>> dotted.get({'a': {'b': {'c': {'d': 'nested'}}}}, 'a.b.c.d')
@@ -336,8 +369,8 @@ See the Paths, Patterns, and Operators sections below for the full notation.
 <a id="update"></a>
 ### Update
 
-Update will mutate the object if it can.  It always returns the changed object though. If
-it's not mutable, then get via the return.
+Update mutates the object when possible and always returns the result. For immutable
+objects, use the return value.
 
     >>> import dotted
     >>> l = []
@@ -448,8 +481,8 @@ Use `remove_if_multi` for batch removal with per-item `(key, val, pred)`.
 <a id="match"></a>
 ### Match
 
-Use to match a dotted-style pattern to a field.  Partial matching is on by default.  You
-can match via wildcard OR via regex.  Here's a regex example:
+Match a dotted-style pattern to a path. Partial matching is on by default. You
+can match via wildcard OR via regex. Here's a regex example:
 
     >>> import dotted
     >>> dotted.match('/a.+/', 'abced.b')
@@ -553,7 +586,7 @@ Returns `None` if no pattern matches:
 <a id="expand"></a>
 ### Expand
 
-You may wish to _expand_ all fields that match a pattern in an object.
+Expand a pattern into all matching paths in an object.
 
     >>> import dotted
     >>> d = {'hello': {'there': [1, 2, 3]}, 'bye': 7}
@@ -586,7 +619,7 @@ decide which later-branch results to suppress.
 <a id="has"></a>
 ### Has
 
-Check if a key or pattern exists in an object.
+Check if a path or pattern exists in an object.
 
     >>> import dotted
     >>> d = {'a': {'b': 1}}
@@ -625,13 +658,13 @@ This is useful when you need to know whether to use the return value:
 <a id="setdefault"></a>
 ### Setdefault
 
-Set a value only if the key doesn't already exist. Creates nested structures as needed.
+Set a value only if the path doesn't already exist. Creates nested structures as needed.
 
     >>> import dotted
     >>> d = {'a': 1}
-    >>> dotted.setdefault(d, 'a', 999)  # key exists, no change; returns value
+    >>> dotted.setdefault(d, 'a', 999)  # path exists, no change; returns value
     1
-    >>> dotted.setdefault(d, 'b', 2)    # key missing, sets value; returns it
+    >>> dotted.setdefault(d, 'b', 2)    # path missing, sets value; returns it
     2
     >>> dotted.setdefault({}, 'a.b.c', 7)  # creates nested structure; returns value
     7
@@ -639,7 +672,7 @@ Set a value only if the key doesn't already exist. Creates nested structures as
 <a id="pluck"></a>
 ### Pluck
 
-Extract (key, value) pairs from an object matching a pattern.
+Extract (path, value) pairs from an object matching a pattern.
 
     >>> import dotted
     >>> d = {'a': 1, 'b': 2, 'nested': {'x': 10}}
@@ -685,6 +718,8 @@ which attributes are included:
 - `Attrs.standard` — non-dunder attributes
 - `Attrs.special` — dunder attributes (`__name__`, etc.)
 
+For example:
+
     >>> class Pt:
     ...     def __init__(self, x, y):
     ...         self.x = x
@@ -697,7 +732,7 @@ Pass both to include all attributes: `attrs=[Attrs.standard, Attrs.special]`.
 <a id="pack"></a>
 ### Pack
 
-Build a new object from key-value pairs. The inverse of `unpack` — infers the root
+Build a new object from path-value pairs. The inverse of `unpack` — infers the root
 container type automatically.
 
     >>> import dotted
@@ -744,7 +779,7 @@ All three accept `attrs=` (same as `unpack`):
 <a id="build"></a>
 ### Build
 
-Create a default nested structure for a dotted key.
+Create a default nested structure for a dotted path.
 
     >>> import dotted
     >>> dotted.build({}, 'a.b.c')
@@ -825,7 +860,14 @@ produce `[]`.
 
 Most operations have `*_multi` variants for batch processing:
 
-**Note:** `get_multi` returns a generator (not a list or tuple). That distinguishes it from a pattern `get`, which returns a tuple of matches. It also keeps input and output in the same style when you pass an iterator or generator of paths—lazy in, lazy out.
+**Note:** The read-side `_multi` APIs — `get_multi`, `match_multi`, `expand_multi`,
+`pluck_multi`, `walk_multi`, `translate_multi`, `assemble_multi`, and
+`setdefault_multi` — return a **generator**, not a list or tuple. Consume with
+`list()` / `tuple()` / `for`. The write-side `_multi` APIs (`update_multi`,
+`remove_multi`, `build_multi`, `apply_multi`, etc.) return the mutated object.
+The generator shape keeps input and output in the same style when you pass an
+iterator or generator of paths — lazy in, lazy out — and lets callers early-exit
+before a full traversal completes.
 
     >>> import dotted
     >>> d = {'a': 1, 'b': 2, 'c': 3}

{dotted_notation-0.43.16 → dotted_notation-0.44.0}/README.md

@@ -207,6 +207,39 @@ Several Python libraries handle nested data access. Here's how dotted compares:
 <a id="breaking-changes"></a>
 ## Breaking Changes
 
+### v0.44.0
+- **Parameter renamed from `key` to `path`** across the public API to align with
+  the terminology used throughout the docs (a _path_ is the whole dotted
+  expression; a _path segment_ or _field_ is one component). Positional calls
+  are unaffected; keyword callers must update:
+  - `get(obj, key=...)` → `get(obj, path=...)`
+  - `update(obj, key=...)`, `update_if(obj, key=...)` → `update(obj, path=...)`, etc.
+  - `remove(obj, key=...)`, `remove_if(obj, key=...)` → `remove(obj, path=...)`, etc.
+  - `has`, `setdefault`, `build`, `mutable`, `match` — same rename
+  - `is_pattern(key=...)`, `is_template(key=...)`, `is_reference(key=...)`,
+    `is_indeterminate(key=...)`, `is_simple(key=...)`, `is_inverted(key=...)` —
+    all take `path=` now.
+  - `parse(key=...)` → `parse(path=...)`
+  - `build_multi(obj, keys=...)` → `build_multi(obj, paths=...)`
+  - `setdefault_multi(obj, keyvalues=...)`, `update_multi(obj, keyvalues=...)` →
+    `setdefault_multi(obj, pathvalues=...)`, `update_multi(obj, pathvalues=...)`
+  - `pack(keyvalues=...)` → `pack(pathvalues=...)`
+  - `remove_multi(..., keys_only=...)`, `remove_if_multi(..., keys_only=...)` →
+    `remove_multi(..., paths_only=...)`, `remove_if_multi(..., paths_only=...)`
+  - `assemble(keys)` / `assemble_multi(keys_list)` → `assemble(segments)` /
+    `assemble_multi(segments_list)`
+  - `remove_if` default pred signature: `lambda key: key is not None` →
+    `lambda path: path is not None`
+- **`is_mutable` added as the preferred name for `mutable`** — parallels the
+  other `is_*` predicates. `mutable` remains as an alias.
+- **`expand_multi`, `pluck_multi`, `assemble_multi` now return a generator**
+  instead of a tuple, aligning with the other read-side `_multi` APIs
+  (`get_multi`, `match_multi`, `walk_multi`, `translate_multi`,
+  `setdefault_multi`). Callers that consumed the return as a tuple (indexing
+  `r[0]`, `len(r)`, equality `r == (...)`) must now materialize:
+  `tuple(pluck_multi(...))`. The singular forms (`expand`, `pluck`, `assemble`)
+  are unchanged.
+
 ### v0.43.4
 - **`is_pattern` no longer returns `True` for substitutions**. `Subst` previously
   inherited from `Pattern` in the class hierarchy, so any path containing a
@@ -287,7 +320,7 @@ Parsed dotted paths are LRU-cached (after the first parse of a given path string
 <a id="get"></a>
 ### Get
 
-See the Paths, Patterns, and Operators sections below for the full notation.
+Get the value at a dotted path. See the Paths, Patterns, and Operators sections below for the full notation.
 
     >>> import dotted
     >>> dotted.get({'a': {'b': {'c': {'d': 'nested'}}}}, 'a.b.c.d')
@@ -296,8 +329,8 @@ See the Paths, Patterns, and Operators sections below for the full notation.
 <a id="update"></a>
 ### Update
 
-Update will mutate the object if it can.  It always returns the changed object though. If
-it's not mutable, then get via the return.
+Update mutates the object when possible and always returns the result. For immutable
+objects, use the return value.
 
     >>> import dotted
     >>> l = []
@@ -408,8 +441,8 @@ Use `remove_if_multi` for batch removal with per-item `(key, val, pred)`.
 <a id="match"></a>
 ### Match
 
-Use to match a dotted-style pattern to a field.  Partial matching is on by default.  You
-can match via wildcard OR via regex.  Here's a regex example:
+Match a dotted-style pattern to a path. Partial matching is on by default. You
+can match via wildcard OR via regex. Here's a regex example:
 
     >>> import dotted
     >>> dotted.match('/a.+/', 'abced.b')
@@ -513,7 +546,7 @@ Returns `None` if no pattern matches:
 <a id="expand"></a>
 ### Expand
 
-You may wish to _expand_ all fields that match a pattern in an object.
+Expand a pattern into all matching paths in an object.
 
     >>> import dotted
     >>> d = {'hello': {'there': [1, 2, 3]}, 'bye': 7}
@@ -546,7 +579,7 @@ decide which later-branch results to suppress.
 <a id="has"></a>
 ### Has
 
-Check if a key or pattern exists in an object.
+Check if a path or pattern exists in an object.
 
     >>> import dotted
     >>> d = {'a': {'b': 1}}
@@ -585,13 +618,13 @@ This is useful when you need to know whether to use the return value:
 <a id="setdefault"></a>
 ### Setdefault
 
-Set a value only if the key doesn't already exist. Creates nested structures as needed.
+Set a value only if the path doesn't already exist. Creates nested structures as needed.
 
     >>> import dotted
     >>> d = {'a': 1}
-    >>> dotted.setdefault(d, 'a', 999)  # key exists, no change; returns value
+    >>> dotted.setdefault(d, 'a', 999)  # path exists, no change; returns value
     1
-    >>> dotted.setdefault(d, 'b', 2)    # key missing, sets value; returns it
+    >>> dotted.setdefault(d, 'b', 2)    # path missing, sets value; returns it
     2
     >>> dotted.setdefault({}, 'a.b.c', 7)  # creates nested structure; returns value
     7
@@ -599,7 +632,7 @@ Set a value only if the key doesn't already exist. Creates nested structures as
 <a id="pluck"></a>
 ### Pluck
 
-Extract (key, value) pairs from an object matching a pattern.
+Extract (path, value) pairs from an object matching a pattern.
 
     >>> import dotted
     >>> d = {'a': 1, 'b': 2, 'nested': {'x': 10}}
@@ -645,6 +678,8 @@ which attributes are included:
 - `Attrs.standard` — non-dunder attributes
 - `Attrs.special` — dunder attributes (`__name__`, etc.)
 
+For example:
+
     >>> class Pt:
     ...     def __init__(self, x, y):
     ...         self.x = x
@@ -657,7 +692,7 @@ Pass both to include all attributes: `attrs=[Attrs.standard, Attrs.special]`.
 <a id="pack"></a>
 ### Pack
 
-Build a new object from key-value pairs. The inverse of `unpack` — infers the root
+Build a new object from path-value pairs. The inverse of `unpack` — infers the root
 container type automatically.
 
     >>> import dotted
@@ -704,7 +739,7 @@ All three accept `attrs=` (same as `unpack`):
 <a id="build"></a>
 ### Build
 
-Create a default nested structure for a dotted key.
+Create a default nested structure for a dotted path.
 
     >>> import dotted
     >>> dotted.build({}, 'a.b.c')
@@ -785,7 +820,14 @@ produce `[]`.
 
 Most operations have `*_multi` variants for batch processing:
 
-**Note:** `get_multi` returns a generator (not a list or tuple). That distinguishes it from a pattern `get`, which returns a tuple of matches. It also keeps input and output in the same style when you pass an iterator or generator of paths—lazy in, lazy out.
+**Note:** The read-side `_multi` APIs — `get_multi`, `match_multi`, `expand_multi`,
+`pluck_multi`, `walk_multi`, `translate_multi`, `assemble_multi`, and
+`setdefault_multi` — return a **generator**, not a list or tuple. Consume with
+`list()` / `tuple()` / `for`. The write-side `_multi` APIs (`update_multi`,
+`remove_multi`, `build_multi`, `apply_multi`, etc.) return the mutated object.
+The generator shape keeps input and output in the same style when you pass an
+iterator or generator of paths — lazy in, lazy out — and lets callers early-exit
+before a full traversal completes.
 
     >>> import dotted
     >>> d = {'a': 1, 'b': 2, 'c': 3}

{dotted_notation-0.43.16 → dotted_notation-0.44.0}/dotted/__init__.py

@@ -12,24 +12,24 @@ Use dotted to fetch, update, and remove data from deeply nested structures.
 
 Core Operations
 ---------------
-get(obj, key)           Get value at dotted key
-update(obj, key, val)   Update value at dotted key
-remove(obj, key)        Remove value at dotted key
-has(obj, key)           Check if key exists
-setdefault(obj, k, v)   Set value only if key missing
-mutable(obj, key)       Check if update would mutate in place
+get(obj, path)          Get value at dotted path
+update(obj, path, val)  Update value at dotted path
+remove(obj, path)       Remove value at dotted path
+has(obj, path)          Check if path exists
+setdefault(obj, p, v)   Set value only if path missing
+is_mutable(obj, path)   Check if update would mutate in place
 
 Pattern Matching
 ----------------
-match(pattern, key)     Match pattern to key
+match(pattern, path)    Match pattern to path
 replace(template, bind) Substitute $N in template path
-expand(obj, pattern)    Expand pattern to concrete keys
+expand(obj, pattern)    Expand pattern to concrete paths
 
 Building & Plucking
 -------------------
-build(obj, key)         Build default structure for key
-pack(keyvalues)         Build object from key-value pairs
-pluck(obj, pattern)     Extract field-value pairs
+build(obj, path)        Build default structure for path
+pack(pathvalues)        Build object from path-value pairs
+pluck(obj, pattern)     Extract (path, value) pairs
 walk(obj, pattern)      Yield (path, value) pairs (lazy)
 unpack(obj)             Extract to dotted normal form
 keys(obj)               Dotted paths of obj
@@ -49,7 +49,7 @@ transform(name)         Decorator for custom transforms
 Constants
 ---------
 ANY                     Match any value (for remove)
-AUTO                    Auto-infer root container type ({} or []) from first key
+AUTO                    Auto-infer root container type ({} or []) from first path
 
 For full documentation including all options and flags:
     $ pydoc dotted.api
@@ -57,7 +57,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, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
+    is_inverted, is_mutable, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
     register, transform, \
     assemble, assemble_multi, \
     build, build_multi, \
@@ -86,7 +86,7 @@ __all__ = [
     'parse', 'assemble', 'assemble_multi', 'quote',
     'is_pattern', 'is_template', 'is_reference',
     'is_indeterminate', 'is_simple',
-    'is_inverted', 'mutable',
+    'is_inverted', 'is_mutable', 'mutable',
     # SQL
     'sqlize', 'Resolver', 'SQLFragment', 'ParamStyle', 'ParamPool', 'TranslationError',
     # Constants