dotted-notation 0.46.1__tar.gz → 0.47.1__tar.gz

{dotted_notation-0.46.1 → dotted_notation-0.47.1}/CHANGELOG.md

@@ -3,6 +3,66 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.47.1]
+
+### Added
+- The `coalesce` transform: `n|coalesce:0` is `n`, or 0 when `n` is
+  `None`. Several fallbacks take the first that is not `None`, so a
+  reference may stand in first: `n|coalesce:$$(defaults.n):0`.
+
+## [0.47.0]
+
+### Added
+- References resolve in transform arguments, guard values and filter
+  values: `n|add:$$(config.offset)`, `*>$$(limit)`,
+  `users[*&name=$$(selected)]`. `$$(path)` is the root as before;
+  `$$(^path)` is the value being transformed or compared, `$$(^^path)`
+  the node holding it, and so on up. A reference that does not resolve
+  matches nothing, as in an access position.
+
+### Fixed
+- A `$(name)` substitution in a transform argument resolved through
+  `bindings=` is handed to the transform as its value; it was handed as
+  the parsed wrapper, so the transform failed and returned the value
+  unchanged. `null`, `true` and `false` arguments are likewise unwrapped.
+- A reference as a guard or filter value raised `AttributeError`.
+- A value guard after an attribute access, `o@name=5`, or after a group,
+  `(a,b)=5`, raised `ValueError` when parsed.
+- A value guard under `~` did not hold for writes: `~a=1` raised
+  `TypeError` on `update` and `remove`, and `[~0]=1` mutated.
+- `!a.b` yielded the complement of `a` and dropped the `.b`; it now
+  continues into `b` from each key other than `a`.
+
+### Changed
+- Precedence, tightest first: access ops and `:type`; `!`; then guards,
+  filters and transforms; then `&`; then `,`. A guard, filter or
+  transform applies to the whole expression on its left. After a
+  parenthesized `,`, `&` or `?` group it is shorthand for writing it on
+  every branch: `(a,b)=5` is `(a=5,b=5)`, `(first&last)>5` is
+  `(first>5&last>5)`, `(a,b)|int` is `(a|int,b|int)`, which is also how
+  `assemble` writes them. After `!` it applies to what the negation
+  yields: `!a=5` is `(!a)=5`, the non-`a` values equal to 5, where it was
+  `!(a=5)`; that reading now needs the parentheses. `a,b|int` transforms
+  only `b`. `@attr=value` is a value guard like `key=value`, honored by
+  `update` and `remove`.
+- `:type` tests the value a path yields, not the node it is applied to:
+  `x:int` is `x`, when its value is an `int`, a type guard beside `=value`
+  at the same level, so `(a|int):int` types a transformed value and
+  `*:dict` is the values that are dicts. It tested the container, so
+  `x:int` on `{'x': 3}` was `None`. A restriction on the container moves
+  one segment earlier: old `a.b:dict` is new `a:dict.b`, and
+  `*[*]:!(str, bytes)` is `*:!(str, bytes)[*]`.
+- Every op owns its transforms: `a.b|int` carries `int` on `b`, so a
+  transform can sit inside a group and `expand`, `pluck` and `unpack`
+  write it back on each concrete path. `Dotted.transforms` is the
+  trailing op's, read-only. The match-only transforms of a guard or
+  filter, `a|int=5`, are its `guard_transforms`.
+- For development: the `.pxd` files cimport `dotted.base` by its full
+  name, which the compiler's dependency scanner follows, so a change to
+  `base.pxd` rebuilds every compiled module that depends on it. Written
+  as `from . cimport base`, the dependency went unseen and stale modules
+  warned about a changed `DepthStack` size.
+
 ## [0.46.1]
 
 ### Changed

{dotted_notation-0.46.1/dotted_notation.egg-info → dotted_notation-0.47.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.46.1
+Version: 0.47.1
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Author-email: Frey Waid <logophage1@gmail.com>
 License-Expression: MIT
@@ -144,6 +144,7 @@ For faster `mutable=False` updates and removes, install the
   - [Template bindings](#template-bindings)
   - [References](#references)
   - [Relative References](#relative-references)
+  - [References in transforms and guards](#references-in-transforms-and-guards)
   - [Escaping](#escaping)
 - [Type Restrictions](#type-restrictions)
   - [Positive restrictions](#positive-restrictions)
@@ -272,6 +273,32 @@ Several Python libraries handle nested data access. Here's how dotted compares:
 <a id="breaking-changes"></a>
 ## Breaking Changes
 
+### v0.47.0
+- **`!` binds tighter than guards, filters and transforms.** `!a=5` is now
+  `(!a)=5`, the values other than `a`'s that equal 5; the old meaning,
+  everything but an `a` equal to 5, is written `!(a=5)`. Likewise `!a&k=v`
+  filters what `!a` yields and `!a|int` transforms it. See
+  [Precedence](#precedence).
+- **A guard, filter or transform after a group distributes to every branch.**
+  `(a,b)=5` is `(a=5,b=5)`, `(first&last)>5` is `(first>5&last>5)`,
+  `(a,b)|int` is `(a|int,b|int)`, and `assemble` writes the distributed form.
+  These used to fail to parse.
+- **`a,b|int` transforms only `b`.** A transform binds to the expression on
+  its left before `,` and `&`; `(a,b)|int` transforms both.
+- **`:type` tests the value a path yields, not the node it is applied to.**
+  `x:int` on `{'x': 3}` is `3`; it was `None`. Restrict a container one
+  segment earlier: `a.b:dict` → `a:dict.b`, and
+  `*[*]:!(str, bytes)` → `*:!(str, bytes)[*]`. `**:!(str, bytes)` and
+  `*(*, [*]):!(str, bytes)` now drop string values themselves, not only
+  their decomposition.
+- **`!a.b` continues into `b`.** It yielded the complement of `a` and
+  ignored `.b`; it now yields `.b` of every key other than `a`, as
+  `match` always read it.
+- **Ops own their transforms.** `Dotted.transforms` is read-only and
+  reflects the trailing op; `parse('a.b|int')` reprs as
+  `Dotted([a, b|int])`. A guard's or filter's match-only transforms,
+  `a|int=5`, are `guard_transforms`, not `transforms`.
+
 ### 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
@@ -1374,6 +1401,7 @@ at replace time) and **references** (resolved during traversal).
 | `$$(path)` | Reference | Root object during traversal |
 | `$$(^path)` | Relative reference | Current node during traversal |
 | `$$(^^path)` | Relative reference | Parent node during traversal |
+| `$$(^path)` in a transform, guard or filter | Relative reference | The value under test; `^^` the node holding it |
 
 <a id="substitution"></a>
 ### Substitution
@@ -1559,6 +1587,50 @@ Relative references combine with patterns:
     >>> dotted.get(data, 'a.$$(^config.*.field)')
     ('Alice', 30)
 
+<a id="references-in-transforms-and-guards"></a>
+### References in transforms and guards
+
+A reference can also stand in for a transform argument, a guard value or a
+filter value. It resolves when the transform or comparison runs, against the
+value under test: `$$(path)` is the root as always, `$$(^path)` is the value
+itself, `$$(^^path)` the node holding it, `$$(^^^path)` that node's parent,
+and so on:
+
+    >>> data = {'config': {'offset': 10}, 'n': 5}
+    >>> dotted.get(data, 'n|add:$$(config.offset)')
+    15
+
+    >>> data = {'items': [{'price': 100, 'rate': 1.5}, {'price': 20, 'rate': 2}]}
+    >>> dotted.get(data, 'items[*].price|mul:$$(^^rate)')
+    (150.0, 40)
+
+Each `price` is the value being transformed, so `^^rate` is the `rate` beside
+it. Guard and filter values resolve the same way:
+
+    >>> data = {'limit': 10, 'a': 5, 'b': 15}
+    >>> dotted.get(data, '*>$$(limit)')
+    (15,)
+    >>> data = {'selected': 'bob', 'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(data, 'users[*&name=$$(selected)].name')
+    ('bob',)
+
+as do the transforms before a guard:
+
+    >>> data = {'scale': 10, 'a': 1, 'b': 2}
+    >>> dotted.get(data, '*|mul:$$(scale)=20')
+    (2,)
+
+With `update`, the transforms apply to the value being set, so `^` is that
+value:
+
+    >>> dotted.update({'n': 5, 'inc': 3}, 'n|add:$$(inc)', 10)
+    {'n': 13, 'inc': 3}
+
+A reference that does not resolve matches nothing, as in an access position:
+
+    >>> dotted.get({'a': 1}, 'a|add:$$(missing)', default='fallback')
+    'fallback'
+
 <a id="escaping"></a>
 ### Escaping
 
@@ -1586,17 +1658,19 @@ To use a literal `$$` as a key, escape with backslash (`\$$`) or quote it
 <a id="type-restrictions"></a>
 ## Type Restrictions
 
-A **type restriction** constrains a path segment so it only applies when the
-current node is a specific type. Append `:type` after any accessor — key,
-slot, or attr:
+A **type restriction** keeps a value only if it is of a given type. Append
+`:type` to a path: `x:int` is `x`, when its value is an `int`, so it reads
+like a guard, `x=5`, with a type in place of a value:
 
     >>> import dotted
     >>> d = {'a': {'b': 1}, 'c': [1, 2], 'd': 'hello'}
+    >>> dotted.get(d, '*:dict')
+    ({'b': 1},)
     >>> dotted.get(d, '*:dict.*')
     (1,)
 
-Here `*:dict` matches all keys but only descends into values that are dicts.
-The list and string are skipped.
+Here `*:dict` keeps the values that are dicts, and `.*` continues into them.
+The list and string are dropped.
 
 Supported types: `str`, `bytes`, `int`, `float`, `dict`, `list`, `tuple`,
 `set`, `frozenset`, `bool`.
@@ -1626,17 +1700,16 @@ Supported types: `str`, `bytes`, `int`, `float`, `dict`, `list`, `tuple`,
 
 Type restrictions work on slot and attr accessors too:
 
-    >>> dotted.get([10, 20], '[0]:list')
-    10
-    >>> dotted.get((10, 20), '[0]:list', 'missing')
+    >>> dotted.get([10, 'x', 20], '[*]:int')
+    (10, 20)
+    >>> dotted.get([10, 20], '[0]:list', 'missing')
     'missing'
-    >>> dotted.get((10, 20), '[0]:tuple')
-    10
 
-Use `:!(str, bytes)` on slot wildcards to prevent string and bytes decomposition:
+A string or bytes value decomposes under `[*]`; to keep that from happening,
+restrict the value before the slot:
 
     >>> d = {'s': 'abc', 'b': b'xyz', 'l': [1, 2]}
-    >>> dotted.get(d, '*[*]:!(str, bytes)')
+    >>> dotted.get(d, '*:!(str, bytes)[*]')
     (1, 2)
 
 <a id="combining-with-filters"></a>
@@ -1648,11 +1721,23 @@ Type restrictions compose with filters. The restriction goes before the filter:
     >>> dotted.get(d, '*:dict&x=1.*')
     (1, 2)
 
+<a id="typing-a-transformed-value"></a>
+### Typing a transformed value
+
+A restriction after a parenthesized group applies to what the group yields,
+transforms included. A `:` directly after a transform name is a parameter,
+`a|int:16`, so the parentheses are what make it a type:
+
+    >>> dotted.get({'a': '5', 'b': 'x'}, '(*|int):int')
+    (5,)
+
+Here `|int` leaves `'x'` as it was, and `:int` drops it.
+
 <a id="recursive-traversal-with-type-restrictions"></a>
 ### Recursive traversal with type restrictions
 
-Type restrictions are especially useful in recursive accessor groups to control
-which containers are traversed:
+Type restrictions are especially useful in recursive accessor groups to keep
+the traversal to values of certain types:
 
     >>> d = {'a': {'b': [1, 2]}, 'c': 'hello'}
     >>> dotted.get(d, '*(*#, [*]:!(str, bytes))')
@@ -1662,11 +1747,12 @@ Without `:!(str, bytes)`, the `[*]` slot accessor would decompose `'hello'`
 into individual characters.
 
 A type restriction can also be applied to an entire group, which distributes it
-to every accessor in the group:
+to every accessor in the group. Here it drops the string `'hello'` as well,
+since the `*` accessor yields it too:
 
     >>> d = {'a': {'b': [1, 2]}, 'c': 'hello'}
     >>> dotted.get(d, '*(*#, [*]):!(str, bytes)')
-    ({'b': [1, 2]}, [1, 2], 1, 2, 'hello')
+    ({'b': [1, 2]}, [1, 2], 1, 2)
 
 The `**` shorthand accepts a type restriction too. It can be combined with a
 depth slice — the type restriction comes first:
@@ -2017,27 +2103,45 @@ Updates and removes apply to all non-matching keys:
 <a id="precedence"></a>
 ### Precedence
 
-Access ops (`.`, `@`, `[]`) bind tightest—they build compound paths
-before any operator sees them. Then `!`, then `&`, then `,`:
+Tightest first:
+
+| Level | Operators | Example |
+|-------|-----------|---------|
+| 1 | access ops `.` `@` `[]`, parentheses | `!a.b` is `!(a.b)` |
+| 2 | `!` negation | `!a=5` is `(!a)=5` |
+| 3 | `:type`, `\|transform`, guard `=value`, filter `&key=value` | `!a\|int=5` tests `int` of each `(!a)` value |
+| 4 | `&` conjunction | `!a=5&b` is `((!a)=5)&b` |
+| 5 | `,` disjunction | `a,b\|int` is `a,(b\|int)` |
 
-| Precedence | Operator | Example |
-|------------|----------|---------|
-| tightest   | `.` `@` `[]` (access ops) | `a.b` is one path |
-|            | `!` (negation) | `!a.b` = `!(a.b)` |
-|            | `&` (conjunction) | `!a&b` = `(!a)&b` |
-| loosest    | `,` (disjunction) | `!a&b,c` = `((!a)&b),c` |
+A guard, filter or transform applies to the whole expression on its left:
+an access path (on its last segment), a `!` expression (on what it
+yields), or a parenthesized group, where it is shorthand for writing it on
+every branch: `(a,b)=5` is `(a=5,b=5)` and `(a,b)|int` is `(a|int,b|int)`,
+which is also how `assemble` writes them.
 
     >>> d = {'a': 1, 'b': 2, 'c': 3}
-    >>> dotted.get(d, '!a&b,c')       # parsed as ((!a)&b), c
+    >>> dotted.get(d, '!a&b,c')       # ((!a)&b), c
     (2, 3, 2, 3)
+    >>> dotted.get(d, '!a=3')         # (!a)=3: the values other than a's equal to 3
+    (3,)
+    >>> dotted.get(d, '!(a=3)')       # everything but an a equal to 3
+    (1, 2, 3)
+    >>> dotted.get({'a': '1', 'b': '2'}, '(a,b)|int')
+    (1, 2)
+    >>> dotted.get({'a': '1', 'b': '2'}, 'a,b|int')
+    ('1', 2)
 
-Since `.` binds tightest, `!a.b&c` is `(!a.b) & c`, not `!(a.b&c)`:
+Since access ops bind tightest, `!a.b` negates `a` and continues into `b`
+from every other key, and `!a.b&x` conjoins that with `x`:
 
-    >>> d = {'a': {'b': 1}, 'c': 2, 'x': 3}
-    >>> dotted.get(d, '!a.b&c')       # (!a.b)&c — negate a.b, conjoin with c
-    (2, 3, 2)
-    >>> dotted.get(d, '!(a.b&c)')     # negate the conjunction as a unit
-    (3,)
+    >>> d = {'a': {'b': 1}, 'c': {'b': 2}, 'x': 3}
+    >>> dotted.get(d, '!a.b')
+    (2,)
+    >>> dotted.get(d, '!a.b&x')
+    (2, 3)
+
+A `:` after a transform name is always a parameter, `a|int:16`; to type a
+transformed value, parenthesize: `(a|int):int`.
 
 <a id="operators"></a>
 ## Operators
@@ -2416,8 +2520,8 @@ Filters support `True`, `False`, and `None` as values:
 ### Value guard
 
 A **value guard** tests the value at a path and yields it only if it matches.
-Use `key=value` or `[slot]=value` after accessing a field. All comparison
-operators (`=`, `!=`, `<`, `>`, `<=`, `>=`) are supported:
+Use `key=value`, `[slot]=value` or `@attr=value` after accessing a field. All
+comparison operators (`=`, `!=`, `<`, `>`, `<=`, `>=`) are supported:
 
     >>> d = {'first': 7, 'last': 3}
     >>> dotted.get(d, 'first=7')
@@ -2436,6 +2540,19 @@ For lists of primitive values, use `[*]=value`:
     >>> dotted.get(data, '[0]=1')
     1
 
+A guard after a parenthesized group is shorthand for a guard on every
+branch: `(first,last)>5` is `(first>5,last>5)`, and `(first&last)>5` is
+`(first>5&last>5)`, which yields nothing unless both pass. After `!` it
+tests what the negation yields, so `!first=3` is the non-`first` values
+equal to 3; see [Precedence](#precedence).
+
+    >>> dotted.get(d, '(first,last)>5')
+    (7,)
+    >>> dotted.get(d, '(first&last)>5')
+    ()
+    >>> dotted.get(d, '!first=3')
+    (3,)
+
 Guards support all value types: numbers, `None`, `True`/`False`, strings, regex, `*`,
 and [container patterns](#container-filter-values) (`[1, ...]`, `{"a": 1, ...: *}`, `{1, 2, ...}`):
 
@@ -2523,6 +2640,9 @@ Guard transforms compose with `update`, `remove`, and `has`:
     >>> dotted.has({'val': '7'}, 'val|int=7')
     True
 
+Both the transform arguments and the value compared with may be
+[references](#references-in-transforms-and-guards).
+
 <a id="container-filter-values"></a>
 ### Container filter values
 
@@ -2838,7 +2958,9 @@ Filter keys can include slice notation so the comparison applies to a slice of t
 You can optionally add transforms to the end of dotted notation. These will
 be applied on `get` and `update`. Transforms are separated by the `|` operator
 and multiple may be chained together. Transforms may be parameterized using
-the `:` operator.
+the `:` operator; a parameter may be a `$$(reference)`, resolved when the
+transform runs (see
+[References in transforms and guards](#references-in-transforms-and-guards)).
 
     >>> import dotted
     >>> d = [1, '2', 3]
@@ -2862,6 +2984,7 @@ decorator.
 | `float` | `raises` | Convert to float |
 | `decimal` | `raises` | Convert to `Decimal` |
 | `none` | values... | Return `None` if falsy or matches values: `\|none::null:empty` |
+| `coalesce` | fallbacks... | The first of the value and the fallbacks that is not `None`: `\|coalesce:0` |
 | `strip` | `chars`, `raises` | Strip whitespace or specified chars |
 | `len` | `default` | Get length. Optional default if not sized: `\|len:0` |
 | `lowercase` | `raises` | Convert string to lowercase |
@@ -2916,6 +3039,19 @@ Comparison and membership transforms return `True`/`False`:
     >>> dotted.get({'n': 2}, 'n|in:[1, 2, 3]')
     True
 
+`coalesce` stands in a fallback for `None`, as SQL's does; with several
+fallbacks the first that is not `None` wins, which matters when a fallback is
+a [reference](#references-in-transforms-and-guards) that may itself be `None`:
+
+    >>> d = {'n': None, 'defaults': {'n': 7}}
+    >>> dotted.get(d, 'n|coalesce:0')
+    0
+    >>> dotted.get(d, 'n|coalesce:$$(defaults.n):0')
+    7
+
+A transform only runs on a value the path yields, so `coalesce` does not fill
+a missing key; `get(..., default=)` does that.
+
 <a id="container-transform-arguments"></a>
 ### Container transform arguments