dotted-notation 0.49.0__tar.gz → 0.49.2__tar.gz

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.49.2]
+
+### Added
+- `ReferenceResolver.literals` may name the positions a resolver is
+  offered plain tokens in, as a list or tuple of `'segments'`,
+  `'transforms'`, `'guards'` and `'filters'`. A host whose variables are
+  sigiled arguments, `|add:^fee`, leaves `'segments'` out and no longer
+  pays a call per key (#63); `get` then keeps its fast path for a plain
+  chain of keys. An unknown name is a `ValueError`. `True` and `False`
+  are unchanged.
+- `ReferenceResolver(literals=...)` sets `literals` per instance,
+  overriding the class's, so a resolver need not be subclassed only to
+  change it. A subclass with its own `__init__` passes it on with
+  `super().__init__(literals)`.
+
+## [0.49.1]
+
+### Documentation
+- The README describes a reference, `$$(expr)`, as an inline evaluation
+  expression: the dotted expression inside, transforms included, is
+  evaluated during traversal and its value stands where it is written. In a
+  transform argument, guard or filter value that is the value itself; in an
+  access position it is the key looked up.
+
 ## [0.49.0]
 
 ### Added

{dotted_notation-0.49.0/dotted_notation.egg-info → dotted_notation-0.49.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.0
+Version: 0.49.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
@@ -1396,7 +1396,8 @@ To chain through the items, use a pattern instead:
 ## Substitutions and References
 
 All `$`-prefixed syntax falls into two categories: **substitutions** (resolved
-at replace time) and **references** (resolved during traversal).
+at replace time) and **references**, inline expressions evaluated during
+traversal.
 
 | Syntax | Type | Resolved against |
 |---|---|---|
@@ -1502,14 +1503,22 @@ the parsed result, so a path used many times can be compiled once:
 <a id="references"></a>
 ### References
 
-A **reference** resolves a dotted path against the root object during traversal
-and uses the result as a literal key. The syntax is `$$(path)`:
+A **reference**, `$$(expr)`, is an inline evaluation expression. The dotted
+expression inside is evaluated during traversal, as `get` would evaluate it
+against the root, and its value stands where the reference is written. The
+expression is a full dotted path, so it may carry patterns and transforms:
+`$$(config.offset|mul:10)` is the value of `config.offset`, times ten.
+
+Where the reference stands decides what its value does. In a transform
+argument, a guard value or a filter value it is the value itself (see
+[References in transforms and guards](#references-in-transforms-and-guards)).
+In an access position, as a key or slot, it is the key to look up:
 
     >>> data = {'config': {'field': 'name'}, 'name': 'Alice'}
     >>> dotted.get(data, '$$(config.field)')
     'Alice'
 
-Here `$$(config.field)` resolves to `'name'`, then looks up `data['name']`.
+Here `$$(config.field)` evaluates to `'name'`, then looks up `data['name']`.
 
 References work with all access types and in any position:
 
@@ -1606,6 +1615,12 @@ and so on:
     >>> dotted.get(data, 'n|add:$$(config.offset)')
     15
 
+The expression inside may chain transforms of its own; they apply to its value
+before it is passed:
+
+    >>> dotted.get(data, 'n|add:$$(config.offset|mul:10)')
+    105
+
     >>> data = {'items': [{'price': 100, 'rate': 1.5}, {'price': 20, 'rate': 2}]}
     >>> dotted.get(data, 'items[*].price|mul:$$(^^rate)')
     (150.0, 40)
@@ -1662,14 +1677,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1681,6 +1698,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/README.md

@@ -1349,7 +1349,8 @@ To chain through the items, use a pattern instead:
 ## Substitutions and References
 
 All `$`-prefixed syntax falls into two categories: **substitutions** (resolved
-at replace time) and **references** (resolved during traversal).
+at replace time) and **references**, inline expressions evaluated during
+traversal.
 
 | Syntax | Type | Resolved against |
 |---|---|---|
@@ -1455,14 +1456,22 @@ the parsed result, so a path used many times can be compiled once:
 <a id="references"></a>
 ### References
 
-A **reference** resolves a dotted path against the root object during traversal
-and uses the result as a literal key. The syntax is `$$(path)`:
+A **reference**, `$$(expr)`, is an inline evaluation expression. The dotted
+expression inside is evaluated during traversal, as `get` would evaluate it
+against the root, and its value stands where the reference is written. The
+expression is a full dotted path, so it may carry patterns and transforms:
+`$$(config.offset|mul:10)` is the value of `config.offset`, times ten.
+
+Where the reference stands decides what its value does. In a transform
+argument, a guard value or a filter value it is the value itself (see
+[References in transforms and guards](#references-in-transforms-and-guards)).
+In an access position, as a key or slot, it is the key to look up:
 
     >>> data = {'config': {'field': 'name'}, 'name': 'Alice'}
     >>> dotted.get(data, '$$(config.field)')
     'Alice'
 
-Here `$$(config.field)` resolves to `'name'`, then looks up `data['name']`.
+Here `$$(config.field)` evaluates to `'name'`, then looks up `data['name']`.
 
 References work with all access types and in any position:
 
@@ -1559,6 +1568,12 @@ and so on:
     >>> dotted.get(data, 'n|add:$$(config.offset)')
     15
 
+The expression inside may chain transforms of its own; they apply to its value
+before it is passed:
+
+    >>> dotted.get(data, 'n|add:$$(config.offset|mul:10)')
+    105
+
     >>> data = {'items': [{'price': 100, 'rate': 1.5}, {'price': 20, 'rate': 2}]}
     >>> dotted.get(data, 'items[*].price|mul:$$(^^rate)')
     (150.0, 40)
@@ -1615,14 +1630,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1634,6 +1651,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/dotted/access.py

@@ -251,11 +251,12 @@ class AccessOp(SimpleOp):
     def _offered(self, settings):
         """
         True if the match op goes to the resolver: a reference, or a
-        plain constant when the resolver in force takes literals.
+        plain constant when the resolver in force takes literals in path
+        segments.
         """
         if self.op.is_reference():
             return True
-        return (settings.literals() and isinstance(self.op, matchers.Const)
+        return (settings.literals('segments') and isinstance(self.op, matchers.Const)
                 and not isinstance(self.op, matchers.ResolvedValue))
 
     def resolve(self, bindings, partial=False):

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/dotted/api.py

@@ -448,9 +448,11 @@ def build(obj, path, strict=False, bindings=None, resolver=None):
 def _literals(resolver):
     """
     True if the resolver a call will run under, its own or the process
-    default, takes plain tokens: the simple fast path must then step aside.
+    default, takes plain tokens in path segments: the simple fast path must
+    then step aside. Other positions it can serve, as its transforms
+    resolve through Settings.
     """
-    return (base.RESOLVER if resolver is None else resolver).literals
+    return base.takes_literals(base.RESOLVER if resolver is None else resolver, 'segments')
 
 
 def _prepare(ops, resolver):
@@ -1365,12 +1367,11 @@ def set_resolver(resolver=None):
     restores dotted's own (see Resolver).
     >>> import dotted
     >>> class Upper(dotted.ReferenceResolver):
-    ...     literals = True
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
     ...             return super().resolve(ref, settings, node, parents)
     ...         return ref.value.upper()
-    >>> dotted.set_resolver(Upper())
+    >>> dotted.set_resolver(Upper(literals=True))
     >>> dotted.get({'A': 1}, 'a')
     1
     >>> dotted.set_resolver()

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/dotted/base.py

@@ -149,6 +149,12 @@ class NOP(metaclass=MetaNOP):
         return False
 
 
+# The positions a resolver may be offered plain tokens in, named in its
+# literals: key, slot and attr segments, transform arguments, guard values
+# and filter values.
+LITERALS = ('segments', 'transforms', 'guards', 'filters')
+
+
 class Resolver:
     """
     What a reference means at run time. Every $$(path) a traversal meets,
@@ -161,10 +167,30 @@ class Resolver:
 
     # True to be offered every plain token in a var-permitting position as
     # well: key, slot and attr segments, transform arguments, guard and
-    # filter values. The host decides which are its variables; returning
-    # ref.value leaves a token the literal it is.
+    # filter values. A list or tuple of LITERALS names to be offered them in
+    # those positions only, ('transforms', 'guards', 'filters') to leave
+    # segments out. The host decides which are its variables; returning
+    # ref.value leaves a token the literal it is. Set here, on a subclass,
+    # or per instance with literals=.
     literals = False
 
+    def __init_subclass__(cls, **kwargs):
+        """
+        Check a subclass's literals (see check_literals).
+        """
+        super().__init_subclass__(**kwargs)
+        check_literals(cls.literals)
+
+    def __init__(self, literals=None):
+        """
+        literals, when given, overrides the class's for this instance (see
+        check_literals).
+        """
+        if literals is None:
+            return
+        check_literals(literals)
+        self.literals = literals
+
     def fold(self, segments):
         """
         The path-level hook, called once with a path's segment strings
@@ -211,6 +237,33 @@ class Resolver:
 RESOLVER = Resolver()
 
 
+def check_literals(literals):
+    """
+    Raise unless literals is True, False, or a list or tuple of LITERALS
+    names.
+    """
+    if isinstance(literals, bool):
+        return
+    if not isinstance(literals, (list, tuple)):
+        raise TypeError(f'literals is True, False or a list or tuple of {LITERALS}, not {literals!r}')
+    unknown = [name for name in literals if name not in LITERALS]
+    if unknown:
+        raise ValueError(f'literals names {unknown}, not among {LITERALS}')
+
+
+def takes_literals(resolver, position):
+    """
+    True if resolver takes plain tokens at position, one of LITERALS: its
+    literals is True, or names it.
+    """
+    lit = resolver.literals
+    if lit is True:
+        return True
+    if not lit:
+        return False
+    return position in lit
+
+
 class Settings:
     """
     What holds for the whole of one traversal: the root node, the chain of
@@ -242,11 +295,12 @@ class Settings:
         """
         return RESOLVER if self.resolver is None else self.resolver
 
-    def literals(self):
+    def literals(self, position):
         """
-        True if the resolver in force wants plain tokens offered too.
+        True if the resolver in force wants plain tokens at position, one
+        of LITERALS, offered too.
         """
-        return self.resolving().literals
+        return takes_literals(self.resolving(), position)
 
     def resolve(self, ref, node=None, parents=()):
         """
@@ -551,7 +605,7 @@ class Transform(Op):
             return ()
         if settings is None:
             settings = SETTINGS
-        literals = settings.literals()
+        literals = settings.literals('transforms')
         args = []
         for p in self.params:
             if isinstance(p, Op) and (p.is_reference() or (literals and isinstance(p, matchers.Const))):

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/dotted/filters.py

@@ -285,7 +285,7 @@ class FilterKeyValue(FilterOp):
                     val = results.apply_transforms(val, self.guard_transforms, settings, parents)
             except base.UnresolvedReference:
                 continue
-            if results.guard_passes(pred_op, val, self.val, settings, val, parents):
+            if results.guard_passes(pred_op, val, self.val, settings, val, parents, 'filters'):
                 return True
         return False
 

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/dotted/results.py

@@ -256,18 +256,19 @@ def apply_transforms(val, transforms, settings=base.SETTINGS, parents=()):
     return val
 
 
-def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=()):
+def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=(), position='guards'):
     """
     The match op a guard or filter value compares with: the value as
     parsed, or a reference resolved through the traversal's resolver
     against node and parents, node being the value under test (so
-    $$(^x) looks x up in it). A reference path that is a pattern becomes
-    a value group of what it resolves to. Raises UnresolvedReference when
-    the reference does not resolve.
+    $$(^x) looks x up in it). A plain value is resolved too when the
+    resolver takes literals at position, 'guards' or 'filters'. A reference
+    path that is a pattern becomes a value group of what it resolves to.
+    Raises UnresolvedReference when the reference does not resolve.
     """
     # container values (ContainerList and kin) are ops without is_reference
     reference = hasattr(guard, 'is_reference') and guard.is_reference()
-    if not (reference or (settings.literals() and isinstance(guard, Const))):
+    if not (reference or (settings.literals(position) and isinstance(guard, Const))):
         return guard
     val = settings.resolve(guard, node, parents)
     if not guard.is_pattern():
@@ -276,13 +277,13 @@ def guard_matcher(guard, settings=base.SETTINGS, node=None, parents=()):
     return containers.ValueGroup(*(Const(v) for v in val))
 
 
-def guard_passes(pred_op, val, guard, settings=base.SETTINGS, node=None, parents=()):
+def guard_passes(pred_op, val, guard, settings=base.SETTINGS, node=None, parents=(), position='guards'):
     """
     True if val satisfies pred_op against guard (see guard_matcher); a
     guard reference that does not resolve passes nothing.
     """
     try:
-        matcher = guard_matcher(guard, settings, node, parents)
+        matcher = guard_matcher(guard, settings, node, parents, position)
     except base.UnresolvedReference:
         return False
     return any(True for _ in pred_op.matches((val,), matcher))

{dotted_notation-0.49.0 → dotted_notation-0.49.2/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.49.0
+Version: 0.49.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
@@ -1396,7 +1396,8 @@ To chain through the items, use a pattern instead:
 ## Substitutions and References
 
 All `$`-prefixed syntax falls into two categories: **substitutions** (resolved
-at replace time) and **references** (resolved during traversal).
+at replace time) and **references**, inline expressions evaluated during
+traversal.
 
 | Syntax | Type | Resolved against |
 |---|---|---|
@@ -1502,14 +1503,22 @@ the parsed result, so a path used many times can be compiled once:
 <a id="references"></a>
 ### References
 
-A **reference** resolves a dotted path against the root object during traversal
-and uses the result as a literal key. The syntax is `$$(path)`:
+A **reference**, `$$(expr)`, is an inline evaluation expression. The dotted
+expression inside is evaluated during traversal, as `get` would evaluate it
+against the root, and its value stands where the reference is written. The
+expression is a full dotted path, so it may carry patterns and transforms:
+`$$(config.offset|mul:10)` is the value of `config.offset`, times ten.
+
+Where the reference stands decides what its value does. In a transform
+argument, a guard value or a filter value it is the value itself (see
+[References in transforms and guards](#references-in-transforms-and-guards)).
+In an access position, as a key or slot, it is the key to look up:
 
     >>> data = {'config': {'field': 'name'}, 'name': 'Alice'}
     >>> dotted.get(data, '$$(config.field)')
     'Alice'
 
-Here `$$(config.field)` resolves to `'name'`, then looks up `data['name']`.
+Here `$$(config.field)` evaluates to `'name'`, then looks up `data['name']`.
 
 References work with all access types and in any position:
 
@@ -1606,6 +1615,12 @@ and so on:
     >>> dotted.get(data, 'n|add:$$(config.offset)')
     15
 
+The expression inside may chain transforms of its own; they apply to its value
+before it is passed:
+
+    >>> dotted.get(data, 'n|add:$$(config.offset|mul:10)')
+    105
+
     >>> data = {'items': [{'price': 100, 'rate': 1.5}, {'price': 20, 'rate': 2}]}
     >>> dotted.get(data, 'items[*].price|mul:$$(^^rate)')
     (150.0, 40)
@@ -1662,14 +1677,16 @@ claim some references and leave the rest:
     >>> dotted.get({'amount': 10}, 'amount|sub:$$(lots.taken)', resolver=Store(store))
     7
 
-A resolver that sets `literals = True` is also offered every plain token in
-those positions, so a host sigil such as `$sel` can be a variable. Return
+A resolver with `literals = True` is also offered every plain token in
+those positions, so a host sigil such as `$sel` can be a variable. Set it on
+the class, or per instance with `literals=` on the constructor. Return
 `ref.value` to leave a token the literal it is; a key the resolver answers
 is not offered again:
 
     >>> class Sigils(dotted.ReferenceResolver):
     ...     literals = True
-    ...     def __init__(self, names):
+    ...     def __init__(self, names, literals=None):
+    ...         super().__init__(literals)
     ...         self.names = names
     ...     def resolve(self, ref, settings, node=None, parents=()):
     ...         if ref.is_reference():
@@ -1681,6 +1698,18 @@ is not offered again:
     >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
     ('bob',)
 
+`literals` may instead name the positions it wants, as a list or tuple of
+`'segments'` (key, slot and attr segments), `'transforms'` (transform
+arguments), `'guards'` (guard values) and `'filters'` (filter values). A host
+whose variables only ever stand as arguments leaves `'segments'` out, so the
+keys of a path cost no call:
+
+    >>> r = Sigils({'$inc': 3}, literals=('transforms', 'guards', 'filters'))
+    >>> dotted.get({'n': 5}, 'n|add:$inc', resolver=r)
+    8
+
+An unknown name is a `ValueError`, on the class or the constructor.
+
 A host variable may span several segments, `$amount.value`, which dotted has
 parsed as two. The path-level hook `fold(segments)` is called once with a
 path's segment strings, `('$amount', 'value')`, and returns the runs it

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/pyproject.toml

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

{dotted_notation-0.49.0 → dotted_notation-0.49.2}/setup.py

@@ -11,6 +11,7 @@ same files run as Python.
 import os
 
 from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext as _build_ext
 
 # The engine and the ops it runs. grammar.py, the parser, is left out on
 # purpose: pyparsing inspects its parse actions as Python functions.
@@ -47,7 +48,20 @@ def extensions():
     return cythonize(
         [Extension('dotted.' + name, ['dotted/' + name + '.py'], optional=True) for name in MODULES],
         compiler_directives={'language_level': 3},
+        nthreads=os.cpu_count() or 1,
     )
 
 
-setup(ext_modules=extensions())
+class build_ext(_build_ext):
+    """
+    Compile the extensions one per core. setuptools builds them one after
+    another unless -j is given; the modules are independent, so a release
+    wheel compiles in a fraction of the time on a multi-core runner.
+    """
+    def finalize_options(self):
+        super().finalize_options()
+        if self.parallel is None:
+            self.parallel = os.cpu_count() or 1
+
+
+setup(ext_modules=extensions(), cmdclass={'build_ext': build_ext})