dotted-notation 0.51.0__tar.gz → 0.51.2__tar.gz

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to `dotted` are recorded here. Versions prior to
 the ones listed are omitted — browse git history for earlier entries.
 
+## [0.51.2]
+
+### Added
+- `getter(path, ...)`: a read of `path` as a callable `obj -> value`,
+  returning what `get(obj, path, ...)` would, with the parse, the
+  resolver's `lex`, `fold` and `literals` and the fast-path decision
+  settled once when it is made, so repeated reads skip `get`'s setup.
+
+### Fixed
+- On `get`'s fast path, a resolver answering a reference in a trailing
+  transform's argument saw `settings.strict` as `False` whatever the
+  call's `strict`.
+
+## [0.51.1]
+
+### Added
+- `ReferenceResolver.lex` is offered a bare transform argument too,
+  `|sub:taken`, in the position `'transforms'`. Answering `None` leaves
+  it the plain string it was.
+
 ## [0.51.0]
 
 ### Added

{dotted_notation-0.51.0/dotted_notation.egg-info → dotted_notation-0.51.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.51.0
+Version: 0.51.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
@@ -437,6 +437,17 @@ Get the value at a dotted path. See the Paths, Patterns, and Operators sections
     >>> dotted.get({'a': {'b': {'c': {'d': 'nested'}}}}, 'a.b.c.d')
     'nested'
 
+A path read many times can be made into a **getter** once: a callable
+`obj -> value` that returns what `get` would, with the parse, the resolver's
+hooks and the fast-path decision settled when it is made, against the
+resolver in force then. It takes `get`'s arguments, the object aside.
+
+    >>> d_of = dotted.getter('a.b.c.d', default='none')
+    >>> d_of({'a': {'b': {'c': {'d': 'nested'}}}})
+    'nested'
+    >>> d_of({})
+    'none'
+
 <a id="update"></a>
 ### Update
 
@@ -1771,12 +1782,14 @@ path's segment values, and a slice of a parsed path, `ops[1:]`, is a path.
 
 A host's own names may stand where dotted has no reading for a bare token:
 a slot, `merged[k]`, a slice bound, `items[:n]`, a filter value,
-`[*&cur=want]`, or a guard value, `a=k`. The parse-time hook
-`lex(text, position)` is offered each such token as written, a dotted name
-whole, with its position, one of `'slots'`, `'slices'`, `'filters'` or
-`'guards'`. It answers with dotted text to read in the token's place, `None`
-to leave the `ParseError`, or raises to fail the parse at the token. The
-answer must be one token dotted reads there, and is not offered again.
+`[*&cur=want]`, a guard value, `a=k`, or a transform argument,
+`|sub:taken`. The parse-time hook `lex(text, position)` is offered each such
+token as written, a dotted name whole, with its position, one of `'slots'`,
+`'slices'`, `'filters'`, `'guards'` or `'transforms'`. It answers with dotted
+text to read in the token's place, `None` to leave the `ParseError` (a
+transform argument stays the plain string it was), or raises to fail the
+parse at the token. The answer must be one token dotted reads there, and is
+not offered again.
 
     >>> class Names(dotted.ReferenceResolver):
     ...     def lex(self, text, position):
@@ -1787,7 +1800,7 @@ answer must be one token dotted reads there, and is not offered again.
     >>> dotted.get(d, 'merged[c.account]', resolver=Names())
     2
 
-A token dotted reads, `m[$x]` or `|sub:taken`, is never offered to `lex()`;
+A token dotted reads, `m[$x]` or `|sub:$taken`, is never offered to `lex()`;
 a host that means something else by one remaps it at run time, through
 `literals`. `parse` takes `resolver=` too, and a path is cached per resolver
 that lexes.

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/README.md

@@ -389,6 +389,17 @@ Get the value at a dotted path. See the Paths, Patterns, and Operators sections
     >>> dotted.get({'a': {'b': {'c': {'d': 'nested'}}}}, 'a.b.c.d')
     'nested'
 
+A path read many times can be made into a **getter** once: a callable
+`obj -> value` that returns what `get` would, with the parse, the resolver's
+hooks and the fast-path decision settled when it is made, against the
+resolver in force then. It takes `get`'s arguments, the object aside.
+
+    >>> d_of = dotted.getter('a.b.c.d', default='none')
+    >>> d_of({'a': {'b': {'c': {'d': 'nested'}}}})
+    'nested'
+    >>> d_of({})
+    'none'
+
 <a id="update"></a>
 ### Update
 
@@ -1723,12 +1734,14 @@ path's segment values, and a slice of a parsed path, `ops[1:]`, is a path.
 
 A host's own names may stand where dotted has no reading for a bare token:
 a slot, `merged[k]`, a slice bound, `items[:n]`, a filter value,
-`[*&cur=want]`, or a guard value, `a=k`. The parse-time hook
-`lex(text, position)` is offered each such token as written, a dotted name
-whole, with its position, one of `'slots'`, `'slices'`, `'filters'` or
-`'guards'`. It answers with dotted text to read in the token's place, `None`
-to leave the `ParseError`, or raises to fail the parse at the token. The
-answer must be one token dotted reads there, and is not offered again.
+`[*&cur=want]`, a guard value, `a=k`, or a transform argument,
+`|sub:taken`. The parse-time hook `lex(text, position)` is offered each such
+token as written, a dotted name whole, with its position, one of `'slots'`,
+`'slices'`, `'filters'`, `'guards'` or `'transforms'`. It answers with dotted
+text to read in the token's place, `None` to leave the `ParseError` (a
+transform argument stays the plain string it was), or raises to fail the
+parse at the token. The answer must be one token dotted reads there, and is
+not offered again.
 
     >>> class Names(dotted.ReferenceResolver):
     ...     def lex(self, text, position):
@@ -1739,7 +1752,7 @@ answer must be one token dotted reads there, and is not offered again.
     >>> dotted.get(d, 'merged[c.account]', resolver=Names())
     2
 
-A token dotted reads, `m[$x]` or `|sub:taken`, is never offered to `lex()`;
+A token dotted reads, `m[$x]` or `|sub:$taken`, is never offered to `lex()`;
 a host that means something else by one remaps it at run time, through
 `literals`. `parse` takes `resolver=` too, and a path is cached per resolver
 that lexes.

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/dotted/__init__.py

@@ -71,7 +71,7 @@ from .api import \
     expand, expand_multi, \
     match, match_multi, replace, overlaps, translate, translate_multi, \
     apply, apply_multi, \
-    get, get_multi, \
+    get, get_multi, getter, \
     has, setdefault, setdefault_multi, \
     update, update_multi, pack, update_if, update_if_multi, \
     remove, remove_multi, remove_if, remove_if_multi, \
@@ -82,7 +82,7 @@ from .base import Resolver as ReferenceResolver, UnresolvedReference
 
 __all__ = [
     # Core
-    'get', 'update', 'remove', 'has', 'setdefault',
+    'get', 'getter', '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',

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/dotted/api.py

@@ -511,8 +511,25 @@ def get(obj, path, default=None, pattern_default=(), apply_transforms=True, stri
     >>> get({'a': {'b': 7, 'c': 3}}, '**=7')
     (7,)
     """
+    ops, chain = _get_setup(path, bindings, resolver)
+    return _get_read(obj, ops, chain, default, pattern_default, apply_transforms, strict, resolver)
+
+
+def _get_setup(path, bindings, resolver):
+    """
+    What a read of path settles before it sees an object: the parsed path,
+    with its resolver's lex and fold, and the fast path's chain, None when
+    the read takes the full traversal.
+    """
     ops = _prepare(parse(path, bindings=bindings, partial=False, resolver=resolver), resolver)
     chain = ops.simple_chain if _SIMPLE_FASTPATH and not _literals(resolver) else None
+    return ops, chain
+
+
+def _get_read(obj, ops, chain, default, pattern_default, apply_transforms, strict, resolver):
+    """
+    A read of obj through ops, set up by _get_setup.
+    """
     if chain is not None:
         val = engine.simple_get(chain, obj, strict=strict)
         if val is not engine.SIMPLE_BAIL:
@@ -521,7 +538,7 @@ def get(obj, path, default=None, pattern_default=(), apply_transforms=True, stri
             if not (apply_transforms and ops.transforms):
                 return val
             try:
-                return ops.apply(val, base.Settings(obj, resolver=resolver))
+                return ops.apply(val, base.Settings(obj, strict, resolver=resolver))
             except base.UnresolvedReference:
                 return default
     found = tuple(engine.values(ops, obj, strict=strict, resolver=resolver, transforms=apply_transforms))
@@ -530,6 +547,31 @@ def get(obj, path, default=None, pattern_default=(), apply_transforms=True, stri
     return found if found else pattern_default
 
 
+def getter(path, default=None, pattern_default=(), apply_transforms=True, strict=False, bindings=None, resolver=None):
+    """
+    A read of path as a callable obj -> value, as get(obj, path, ...)
+    returns it. The parse, the resolver's lex, fold and literals and the
+    fast-path decision are settled once, here, against the resolver in
+    force now, so a call is the read and nothing else.
+
+    >>> first = getter('hello.there[0]')
+    >>> first({'hello': {'there': [1, 2]}})
+    1
+    >>> getter('[*].a')([{'a': 1}, {'a': 2}])
+    (1, 2)
+    """
+    r = base.RESOLVER if resolver is None else resolver
+    ops, chain = _get_setup(path, bindings, r)
+
+    def read(obj):
+        """
+        obj read through the getter's path.
+        """
+        return _get_read(obj, ops, chain, default, pattern_default, apply_transforms, strict, r)
+
+    return read
+
+
 def get_multi(obj, iterable, apply_transforms=True, strict=False, bindings=None, resolver=None):
     """
     Get all values from obj in iterable; return iterable

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/dotted/base.py

@@ -155,8 +155,8 @@ class NOP(metaclass=MetaNOP):
 LITERALS = ('segments', 'transforms', 'guards', 'filters')
 
 # The positions a resolver's lex() may be offered a token in: a slot, a
-# slice bound, a filter value and a guard value.
-LEXED = ('slots', 'slices', 'filters', 'guards')
+# slice bound, a filter value, a guard value and a transform argument.
+LEXED = ('slots', 'slices', 'filters', 'guards', 'transforms')
 
 
 class Resolver:
@@ -203,7 +203,8 @@ class Resolver:
         position it stands in, one of LEXED. A dotted name is one token,
         merged[a.b] offering 'a.b'. It answers with dotted text to read
         in the token's place, '$$(k)' making the path merged[$$(k)], or
-        None to leave the path unparsed; raising fails the parse at the
+        None to leave the path unparsed (a transform argument, |sub:k,
+        a plain string, as it was); raising fails the parse at the
         token. The text is read in that position as one token, and is
         not offered to lex() again. A token dotted reads is never
         offered: a host that means something else by one says so at run

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/dotted/grammar.py

@@ -686,8 +686,11 @@ guard_value = (value + _ends) | Lexed('guards', value, _value_stops, end=True)
 _key_atom = _commons | numeric_extended | non_integer | numeric_key | word
 _slot_atom = _commons | numeric_extended | numeric_slot
 
-# Transform: |name or |name:param — defined early so filters and guards can reference it
-targ = concrete_value | _arg_sigil | var | quoted | ppc.number | none | true | false | pp.CharsNotIn('|:')
+# Transform: |name or |name:param — defined early so filters and guards can reference it.
+# A param dotted has no reading for is offered to the lexer before it is
+# taken as a plain string, so a lexer answering None leaves it one.
+_targ_read = concrete_value | _arg_sigil | var | quoted | ppc.number | none | true | false
+targ = (_targ_read + _ends) | Lexed('transforms', _targ_read, '|:', end=True) | pp.CharsNotIn('|:')
 param = (colon + targ) | colon.copy().set_parse_action(lambda: [None])
 transform = (transform_name.copy() + ZM(param)).set_parse_action(lambda s, loc, t: base.Transform(*t))
 transforms = ZM(pipe + transform)

{dotted_notation-0.51.0 → dotted_notation-0.51.2/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.51.0
+Version: 0.51.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
@@ -437,6 +437,17 @@ Get the value at a dotted path. See the Paths, Patterns, and Operators sections
     >>> dotted.get({'a': {'b': {'c': {'d': 'nested'}}}}, 'a.b.c.d')
     'nested'
 
+A path read many times can be made into a **getter** once: a callable
+`obj -> value` that returns what `get` would, with the parse, the resolver's
+hooks and the fast-path decision settled when it is made, against the
+resolver in force then. It takes `get`'s arguments, the object aside.
+
+    >>> d_of = dotted.getter('a.b.c.d', default='none')
+    >>> d_of({'a': {'b': {'c': {'d': 'nested'}}}})
+    'nested'
+    >>> d_of({})
+    'none'
+
 <a id="update"></a>
 ### Update
 
@@ -1771,12 +1782,14 @@ path's segment values, and a slice of a parsed path, `ops[1:]`, is a path.
 
 A host's own names may stand where dotted has no reading for a bare token:
 a slot, `merged[k]`, a slice bound, `items[:n]`, a filter value,
-`[*&cur=want]`, or a guard value, `a=k`. The parse-time hook
-`lex(text, position)` is offered each such token as written, a dotted name
-whole, with its position, one of `'slots'`, `'slices'`, `'filters'` or
-`'guards'`. It answers with dotted text to read in the token's place, `None`
-to leave the `ParseError`, or raises to fail the parse at the token. The
-answer must be one token dotted reads there, and is not offered again.
+`[*&cur=want]`, a guard value, `a=k`, or a transform argument,
+`|sub:taken`. The parse-time hook `lex(text, position)` is offered each such
+token as written, a dotted name whole, with its position, one of `'slots'`,
+`'slices'`, `'filters'`, `'guards'` or `'transforms'`. It answers with dotted
+text to read in the token's place, `None` to leave the `ParseError` (a
+transform argument stays the plain string it was), or raises to fail the
+parse at the token. The answer must be one token dotted reads there, and is
+not offered again.
 
     >>> class Names(dotted.ReferenceResolver):
     ...     def lex(self, text, position):
@@ -1787,7 +1800,7 @@ answer must be one token dotted reads there, and is not offered again.
     >>> dotted.get(d, 'merged[c.account]', resolver=Names())
     2
 
-A token dotted reads, `m[$x]` or `|sub:taken`, is never offered to `lex()`;
+A token dotted reads, `m[$x]` or `|sub:$taken`, is never offered to `lex()`;
 a host that means something else by one remaps it at run time, through
 `literals`. `parse` takes `resolver=` too, and a path is cached per resolver
 that lexes.

{dotted_notation-0.51.0 → dotted_notation-0.51.2}/pyproject.toml

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