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

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

@@ -3,6 +3,32 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.48.0]
+
+### Added
+- `dotted.ReferenceResolver`: what a reference means at run time, as a
+  class a host subclasses. `resolve(ref, settings, node, parents)` is
+  called for every `$$(path)` a traversal meets, in an access position,
+  a transform argument, a guard or a filter value; `super().resolve` is
+  dotted's own reading. With `literals = True` it is offered every plain
+  token in those positions too, so a host sigil such as `$sel` can be a
+  variable. `fold(segments)` is called once per path with its segment
+  strings and folds runs of them into pre-resolved keys, so a
+  multi-segment host variable, `$amount.value`, is one name. Pass a
+  resolver as `resolver=` to `get`, `update`, `remove` and the other
+  traversal calls, or install one for the process with
+  `dotted.set_resolver(r)`; `get_resolver()` reads it back.
+  `UnresolvedReference` is exported for resolvers to raise.
+- `Dotted.segments()`, each segment's plain value with its wrappers
+  aside, and slicing a parsed path, `ops[1:]`, gives a path.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.47.1
+Version: 0.48.0
 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
@@ -145,6 +145,7 @@ For faster `mutable=False` updates and removes, install the
   - [References](#references)
   - [Relative References](#relative-references)
   - [References in transforms and guards](#references-in-transforms-and-guards)
+  - [Custom resolvers](#custom-resolvers)
   - [Escaping](#escaping)
 - [Type Restrictions](#type-restrictions)
   - [Positive restrictions](#positive-restrictions)
@@ -1631,6 +1632,71 @@ 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="custom-resolvers"></a>
+### Custom resolvers
+
+What a reference means at run time is decided by a **resolver**. The default
+is dotted's own reading above. A host with its own namespaces subclasses
+`dotted.ReferenceResolver`, passes an instance as `resolver=` to `get`,
+`update`, `remove` and the rest, or installs one for the process with
+`dotted.set_resolver(r)`; `set_resolver()` with no argument restores the
+default.
+
+`resolve(ref, settings, node, parents)` is called for every `$$(...)` the
+traversal meets, in an access position, a transform argument, a guard or a
+filter value. `ref.is_reference()` is true for those, `ref.inner_path` is the
+text inside, and `super().resolve(...)` is dotted's reading, so a host can
+claim some references and leave the rest:
+
+    >>> class Store(dotted.ReferenceResolver):
+    ...     def __init__(self, store):
+    ...         self.store = store
+    ...     def resolve(self, ref, settings, node=None, parents=()):
+    ...         return dotted.get(self.store, ref.inner_path)
+    >>> store = {'lots': {'taken': 3}}
+    >>> 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
+`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):
+    ...         self.names = names
+    ...     def resolve(self, ref, settings, node=None, parents=()):
+    ...         if ref.is_reference():
+    ...             return super().resolve(ref, settings, node, parents)
+    ...         if isinstance(ref.value, str) and ref.value.startswith('$'):
+    ...             return self.names[ref.value]
+    ...         return ref.value
+    >>> users = {'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
+    ('bob',)
+
+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
+resolves as `(start, stop, value)` triples; each run becomes one segment
+whose key is the value, keeping the last segment's guard, filter and
+transforms. An inner segment of a run may carry none.
+
+    >>> class Folding(Sigils):
+    ...     def fold(self, segments):
+    ...         name = '.'.join(str(s) for s in segments)
+    ...         if name in self.names:
+    ...             return [(0, len(segments), self.names[name])]
+    ...         return []
+    >>> r = Folding({'$amount.value': 'amt'})
+    >>> dotted.get({'amt': 10}, '$amount.value|sub:3', resolver=r)
+    7
+
+A path handed in already parsed goes through `fold()` again, so a hook must
+be content to see its own output. `Dotted.segments()` gives any parsed
+path's segment values, and a slice of a parsed path, `ops[1:]`, is a path.
+
 <a id="escaping"></a>
 ### Escaping
 
@@ -1655,6 +1721,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
 

{dotted_notation-0.47.1 → dotted_notation-0.48.0}/README.md

@@ -98,6 +98,7 @@ For faster `mutable=False` updates and removes, install the
   - [References](#references)
   - [Relative References](#relative-references)
   - [References in transforms and guards](#references-in-transforms-and-guards)
+  - [Custom resolvers](#custom-resolvers)
   - [Escaping](#escaping)
 - [Type Restrictions](#type-restrictions)
   - [Positive restrictions](#positive-restrictions)
@@ -1584,6 +1585,71 @@ 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="custom-resolvers"></a>
+### Custom resolvers
+
+What a reference means at run time is decided by a **resolver**. The default
+is dotted's own reading above. A host with its own namespaces subclasses
+`dotted.ReferenceResolver`, passes an instance as `resolver=` to `get`,
+`update`, `remove` and the rest, or installs one for the process with
+`dotted.set_resolver(r)`; `set_resolver()` with no argument restores the
+default.
+
+`resolve(ref, settings, node, parents)` is called for every `$$(...)` the
+traversal meets, in an access position, a transform argument, a guard or a
+filter value. `ref.is_reference()` is true for those, `ref.inner_path` is the
+text inside, and `super().resolve(...)` is dotted's reading, so a host can
+claim some references and leave the rest:
+
+    >>> class Store(dotted.ReferenceResolver):
+    ...     def __init__(self, store):
+    ...         self.store = store
+    ...     def resolve(self, ref, settings, node=None, parents=()):
+    ...         return dotted.get(self.store, ref.inner_path)
+    >>> store = {'lots': {'taken': 3}}
+    >>> 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
+`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):
+    ...         self.names = names
+    ...     def resolve(self, ref, settings, node=None, parents=()):
+    ...         if ref.is_reference():
+    ...             return super().resolve(ref, settings, node, parents)
+    ...         if isinstance(ref.value, str) and ref.value.startswith('$'):
+    ...             return self.names[ref.value]
+    ...         return ref.value
+    >>> users = {'users': [{'name': 'alice'}, {'name': 'bob'}]}
+    >>> dotted.get(users, 'users[*&name=$sel].name', resolver=Sigils({'$sel': 'bob'}))
+    ('bob',)
+
+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
+resolves as `(start, stop, value)` triples; each run becomes one segment
+whose key is the value, keeping the last segment's guard, filter and
+transforms. An inner segment of a run may carry none.
+
+    >>> class Folding(Sigils):
+    ...     def fold(self, segments):
+    ...         name = '.'.join(str(s) for s in segments)
+    ...         if name in self.names:
+    ...             return [(0, len(segments), self.names[name])]
+    ...         return []
+    >>> r = Folding({'$amount.value': 'amt'})
+    >>> dotted.get({'amt': 10}, '$amount.value|sub:3', resolver=r)
+    7
+
+A path handed in already parsed goes through `fold()` again, so a hook must
+be content to see its own output. `Dotted.segments()` gives any parsed
+path's segment values, and a slice of a parsed path, `ops[1:]`, is a path.
+
 <a id="escaping"></a>
 ### Escaping
 
@@ -1608,6 +1674,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
 

{dotted_notation-0.47.1 → dotted_notation-0.48.0}/dotted/__init__.py

@@ -65,7 +65,7 @@ from .api import \
     parse, compile, is_pattern, is_template, is_reference, is_indeterminate, is_simple, \
     is_inverted, is_mutable, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
     set_simple_fastpath, set_parse_cache, \
-    register, transform, \
+    register, transform, set_resolver, get_resolver, \
     assemble, assemble_multi, \
     build, build_multi, \
     expand, expand_multi, \
@@ -77,10 +77,13 @@ from .api import \
     remove, remove_multi, remove_if, remove_if_multi, \
     pluck, pluck_multi, walk, walk_multi, unpack, keys, values, items
 from .sql import sqlize, TranslationError, SQLFragment, Resolver, ParamStyle, ParamPool
+# the run-time reference resolver; sqlize's Resolver, above, has the plain name
+from .base import Resolver as ReferenceResolver, UnresolvedReference
 
 __all__ = [
     # Core
     'get', 'update', 'remove', 'has', 'setdefault',
+    'ReferenceResolver', 'UnresolvedReference', 'set_resolver', 'get_resolver',
     # Multi
     'get_multi', 'update_multi', 'pack', 'update_if', 'update_if_multi', 'remove_multi', 'remove_if', 'remove_if_multi', 'setdefault_multi',
     # Pattern

{dotted_notation-0.47.1 → dotted_notation-0.48.0}/dotted/access.py

@@ -248,6 +248,16 @@ class AccessOp(SimpleOp):
         """
         return self.op.is_reference()
 
+    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.
+        """
+        if self.op.is_reference():
+            return True
+        return (settings.literals() and isinstance(self.op, matchers.Const)
+                and not isinstance(self.op, matchers.ResolvedValue))
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in the inner match op.
@@ -263,21 +273,21 @@ class AccessOp(SimpleOp):
         tuple of concrete ops (empty if the reference path is not found).
         Callers must guard with is_reference() before calling.
         """
-        root = settings.root
-        parents = settings.parents or ()
         try:
-            val = self.op.resolve_ref(root, node=node, parents=parents)
+            val = settings.resolve(self.op, node, settings.parents or ())
         except KeyError:
             return ()
+        # ResolvedValue, not Const: a resolved key is not offered to the
+        # resolver again (see _offered)
         if self.op.is_pattern():
-            return tuple(self.__class__(matchers.Const(v)) for v in val)
-        return (self.__class__(matchers.Const(val)),)
+            return tuple(self.__class__(matchers.ResolvedValue(v)) for v in val)
+        return (self.__class__(matchers.ResolvedValue(val)),)
 
     def do_update(self, ops, node, val, has_defaults, _path, nop, nop_from_unwrap=False, settings=base.SETTINGS):
         """
         Resolve references before updating.
         """
-        if self.is_reference():
+        if self._offered(settings):
             for r in self._resolved(node=node, settings=settings):
                 node = r.do_update(ops, node, val, has_defaults, _path, nop, nop_from_unwrap=nop_from_unwrap, settings=settings)
             return node
@@ -287,7 +297,7 @@ class AccessOp(SimpleOp):
         """
         Resolve references before removing.
         """
-        if self.is_reference():
+        if self._offered(settings):
             for r in self._resolved(node=node, settings=settings):
                 node = r.do_remove(ops, node, val, nop, settings=settings)
             return node
@@ -395,7 +405,7 @@ class Key(AccessOp):
         return iter(pairs)
 
     def items(self, node, settings=base.SETTINGS, filtered=True):
-        if self.is_reference():
+        if self._offered(settings):
             return self._reference_items(node, filtered, settings)
         # Dict-like: use key matching
         if hasattr(node, 'keys'):
@@ -586,7 +596,7 @@ class Attr(Key):
         yield (key, v)
 
     def items(self, node, settings=base.SETTINGS, filtered=True):
-        if self.is_reference():
+        if self._offered(settings):
             return self._reference_items(node, filtered, settings)
         all_keys = self._all_keys(node)
         keys = self.op.matches(all_keys) if filtered else all_keys
@@ -673,7 +683,7 @@ class Slot(Key):
         return '[' + self.op.quote() + ']'
 
     def items(self, node, settings=base.SETTINGS, filtered=True):
-        if self.is_reference():
+        if self._offered(settings):
             return self._reference_items(node, filtered, settings)
         if hasattr(node, 'keys'):
             if settings.strict: