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

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

@@ -3,6 +3,95 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [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
+- Each compiled wheel is built and tested in its own CI job, so a
+  release takes minutes rather than the better part of an hour. The CLI
+  tests write their input files under pytest's `tmp_path`, which
+  Windows accepts.
+
+## [0.46.0]
+
+### Added
+- The engine compiles to C. Wheels for CPython 3.11-3.14 on Linux
+  (glibc and musl, x86_64 and aarch64), macOS (Apple Silicon) and
+  Windows carry the compiled engine; every other Python installs the
+  same code as pure Python from the universal wheel. `DOTTED_NATIVE=0`
+  in the environment runs the Python engine regardless;
+  `dotted.native.active()` says which is loaded. Wildcard reads are
+  about 2.9x faster than 0.45.1 compiled and writes about 3.5x; pure
+  Python is faster too, writes by about a third.
+- For development: `make test` and `make bench` run both engines,
+  `test.python`/`test.native` and `bench.python`/`bench.native` one;
+  `make test.wheel` runs the suite against a wheel built from the
+  source distribution.
+
+### Changed
+- The `all` extra now means all of them: `formats` and `copium`. It was
+  an alias for `formats`, deprecated since 0.44.9.
+- A concrete key present in a node is no longer looked for among the
+  node's keys to return the node's own key object: it matches as
+  written. Concrete writes and `expand`, `pluck` and `unpack` on a
+  concrete key cost the same wherever the key sits in a large dict
+  (`update` of the 996th key of 1000: 11.5us to 3.3us compiled). The
+  one visible difference: a rendered path shows the key as written
+  where the node spells it differently but equal, `users.1` for a key
+  `1.0`, `RED` for a `StrEnum` member.
+
 ## [0.45.1]
 
 ### Changed

dotted_notation-0.47.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+recursive-include dotted *.pxd
+recursive-exclude dotted *.c *.so *.pyd
+prune tests

{dotted_notation-0.45.1 → dotted_notation-0.47.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.45.1
+Version: 0.47.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
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/freywaid/dotted
 Project-URL: Source, https://github.com/freywaid/dotted
 Project-URL: Changelog, https://github.com/freywaid/dotted/blob/master/CHANGELOG.md
 Keywords: dotted,nested,path,pattern-matching,json,jsonb,sql,traversal
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
@@ -21,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.6
@@ -39,6 +39,7 @@ Requires-Dist: PyYAML>=5.0; extra == "formats"
 Requires-Dist: tomli>=1.0; extra == "formats"
 Requires-Dist: tomli_w>=1.0; extra == "formats"
 Provides-Extra: all
+Requires-Dist: copium>=0.1.0; extra == "all"
 Requires-Dist: PyYAML>=5.0; extra == "all"
 Requires-Dist: tomli>=1.0; extra == "all"
 Requires-Dist: tomli_w>=1.0; extra == "all"
@@ -73,8 +74,9 @@ Or pick only what you need:
 
     pip install dotted-notation[yaml,toml]
 
-> **Deprecated:** the `all` extra is an alias for `formats` and will be removed
-> in a future release. Use `formats` instead.
+Or everything, formats and copium (below) alike:
+
+    pip install dotted-notation[all]
 
 For faster `mutable=False` updates and removes, install the
 [copium](https://github.com/Bobronium/copium) extra, a C implementation of
@@ -142,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)
@@ -1372,6 +1375,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
@@ -1557,6 +1561,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
 
@@ -1584,17 +1632,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`.
@@ -1624,17 +1674,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>
@@ -1646,11 +1695,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))')
@@ -1660,11 +1721,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:
@@ -2015,27 +2077,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
@@ -2414,8 +2494,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')
@@ -2434,6 +2514,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, ...}`):
 
@@ -2521,6 +2614,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
 
@@ -2836,7 +2932,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]