dotted-notation 0.47.0__tar.gz → 0.47.2__tar.gz

{dotted_notation-0.47.0 → dotted_notation-0.47.2}/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.47.2]
+
+### Added
+- `$str`, a `$` before a word, is a plain string wherever a key, guard
+  value or transform argument may stand, as `^str` already was. It was a
+  `ParseError`. `$0`, `$(name)` and `$$(path)` are unchanged.
+
+## [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

{dotted_notation-0.47.0/dotted_notation.egg-info → dotted_notation-0.47.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.47.0
+Version: 0.47.2
 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
@@ -273,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
@@ -1629,6 +1655,13 @@ Quoting also works — a quoted string is always literal:
 To use a literal `$$` as a key, escape with backslash (`\$$`) or quote it
 (`'$$(…)'`).
 
+A `$` before a word is not a substitution at all: `$str` is the plain string
+`$str`, in a segment, a guard value or a transform argument alike, just as
+`^str` is. Only `$0`, `$(name)` and `$$(path)` have meaning:
+
+    >>> dotted.get({'$amount': {'value': 2}}, '$amount.value')
+    2
+
 <a id="type-restrictions"></a>
 ## Type Restrictions
 
@@ -2958,6 +2991,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 |
@@ -3012,6 +3046,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
 

{dotted_notation-0.47.0 → dotted_notation-0.47.2}/README.md

@@ -226,6 +226,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
@@ -1582,6 +1608,13 @@ Quoting also works — a quoted string is always literal:
 To use a literal `$$` as a key, escape with backslash (`\$$`) or quote it
 (`'$$(…)'`).
 
+A `$` before a word is not a substitution at all: `$str` is the plain string
+`$str`, in a segment, a guard value or a transform argument alike, just as
+`^str` is. Only `$0`, `$(name)` and `$$(path)` have meaning:
+
+    >>> dotted.get({'$amount': {'value': 2}}, '$amount.value')
+    2
+
 <a id="type-restrictions"></a>
 ## Type Restrictions
 
@@ -2911,6 +2944,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 |
@@ -2965,6 +2999,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
 

{dotted_notation-0.47.0 → dotted_notation-0.47.2}/dotted/grammar.py

@@ -1,6 +1,7 @@
 """
 """
 import decimal
+import re
 import pyparsing as pp
 from pyparsing import pyparsing_common as ppc
 
@@ -275,7 +276,9 @@ def _paren_subst_action(t):
 _paren_subst = pp.Regex(r'\$\([^)]+\)').set_parse_action(_paren_subst_action)
 _raw_subst = pp.Regex(r'\$[0-9]+').set_parse_action(
     lambda t: matchers.Subst(int(t[0][1:])))
-var = _escaped_dollar | _reference | _paren_subst | _raw_subst
+# $str, a $ before a word: a plain string, as ^str is. Not $0, $(name) or $$(path).
+_dollar_word = pp.Regex(r'\$(?![0-9($])[^' + re.escape(reserved) + r' \t\n\r]+').set_parse_action(matchers.Word)
+var = _escaped_dollar | _reference | _paren_subst | _raw_subst | _dollar_word
 slice = pp.Optional(integer | plus) + ':' + pp.Optional(integer | plus) \
          + pp.Optional(':') + pp.Optional(integer | plus)
 

{dotted_notation-0.47.0 → dotted_notation-0.47.2}/dotted/transforms.py

@@ -104,6 +104,24 @@ def transform_none(val, *none_vals):
     return None if val in none_vals else val
 
 
+@transform('coalesce')
+def transform_coalesce(val, *fallbacks):
+    """
+    The first of val and the fallbacks that is not None
+        <dotted>|coalesce:<fallback>        fallback if val is None else val
+        <dotted>|coalesce:<f1>:<f2>         the first of val, f1, f2 not None
+    >>> import dotted
+    >>> dotted.get({'n': None}, 'n|coalesce:0')
+    0
+    >>> dotted.get({'n': 5}, 'n|coalesce:0')
+    5
+    """
+    for v in (val, *fallbacks):
+        if v is not None:
+            return v
+    return None
+
+
 @transform('strip')
 def transform_strip(val, chars=None, *modes):
     """

{dotted_notation-0.47.0 → dotted_notation-0.47.2/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.47.0
+Version: 0.47.2
 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
@@ -273,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
@@ -1629,6 +1655,13 @@ Quoting also works — a quoted string is always literal:
 To use a literal `$$` as a key, escape with backslash (`\$$`) or quote it
 (`'$$(…)'`).
 
+A `$` before a word is not a substitution at all: `$str` is the plain string
+`$str`, in a segment, a guard value or a transform argument alike, just as
+`^str` is. Only `$0`, `$(name)` and `$$(path)` have meaning:
+
+    >>> dotted.get({'$amount': {'value': 2}}, '$amount.value')
+    2
+
 <a id="type-restrictions"></a>
 ## Type Restrictions
 
@@ -2958,6 +2991,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 |
@@ -3012,6 +3046,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
 

{dotted_notation-0.47.0 → dotted_notation-0.47.2}/pyproject.toml

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