dotted-notation 0.43.3__tar.gz → 0.43.5__tar.gz

{dotted_notation-0.43.3/dotted_notation.egg-info → dotted_notation-0.43.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.3
+Version: 0.43.5
 Summary: Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms
 Home-page: https://github.com/freywaid/dotted
 Author: Frey Waid
@@ -244,6 +244,14 @@ Several Python libraries handle nested data access. Here's how dotted compares:
 <a id="breaking-changes"></a>
 ## Breaking Changes
 
+### v0.43.4
+- **`is_pattern` no longer returns `True` for substitutions**. `Subst` previously
+  inherited from `Pattern` in the class hierarchy, so any path containing a
+  substitution in an access position (e.g. `a.$(x)`, `a.$0`) reported as a
+  pattern. Substitutions resolve to a single key, not a set — that was a
+  misclassification. Use `is_template(path)` to check "contains a
+  substitution."
+
 ### v0.40.0
 - **`unpack()` now returns a `dict`**: Previously returned a tuple of
   `(path, value)` pairs. Now returns `{path: value, ...}` directly.
@@ -2863,18 +2871,36 @@ time:
 
     >>> r = dotted.sqlize("age >= $(min_age)")
     >>> r
-    {'select': 'age', 'where': 'age >= :min_age', 'params': {}, 'missing': ['min_age']}
+    {'select': 'age', 'where': 'age >= :min_age', 'params': {},
+     'unbound': {'min_age': 'min_age'}}
+
+`unbound` is a dict keyed by the **SQL bind parameter name** — the name
+that appears in the SQL `:placeholder` and as a key in `params`. Each
+value is the **original substitution name** (what was inside `$(...)`),
+kept as provenance so callers can trace a bind back to its source.
 
-`missing` lists names that still need a value. Fill them in before passing
-`params` to a driver:
+`unbound.keys()` is the list of bind slots the caller needs to fill.
+Most often you just fill `params` by bind name directly:
 
     >>> r['params']['min_age'] = 30
     >>> # hand (r['where'], r['params']) to cursor.execute / session.execute / etc.
 
-Repeated uses of the same name share one placeholder automatically:
+Non-identifier names (dotted paths, quoted keys, spaces, etc.) hash to a
+deterministic `_s_<hex>` bind name — the bind-side name is different
+from what appeared in source, but the original is preserved in the
+`unbound` value:
+
+    >>> r = dotted.sqlize('age >= $(user.min_age)')
+    >>> r['where']    # doctest: +ELLIPSIS
+    'age >= :_s_...'
+    >>> list(r['unbound'].values())
+    ['user.min_age']
+
+Repeated uses of the same name share one entry automatically:
 
     >>> dotted.sqlize('(age >= $(x) & weight = $(x))')
-    {'where': '(age >= :x) AND (weight = :x)', 'params': {}, 'missing': ['x']}
+    {'where': '(age >= :x) AND (weight = :x)', 'params': {},
+     'unbound': {'x': 'x'}}
 
 If you pass `bindings=`, substitutions are resolved at sqlize time and hoisted
 like any other literal:
@@ -2902,7 +2928,7 @@ Returned dict may contain any subset of:
 | `select`  | `str`       | Expression yielding the value dotted would return   |
 | `where`   | `str`       | Predicate from guards / filters / boolean groups    |
 | `params`  | `dict`      | Hoisted values keyed by name                        |
-| `missing` | `list[str]` | Substitution names still awaiting a value           |
+| `unbound` | `dict`      | Deferred substitutions: `{bind_param_name: original_name}` |
 
 `select` is omitted when combining predicates across different columns
 (e.g. top-level groups), since there's no single meaningful expression.

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/README.md

@@ -207,6 +207,14 @@ Several Python libraries handle nested data access. Here's how dotted compares:
 <a id="breaking-changes"></a>
 ## Breaking Changes
 
+### v0.43.4
+- **`is_pattern` no longer returns `True` for substitutions**. `Subst` previously
+  inherited from `Pattern` in the class hierarchy, so any path containing a
+  substitution in an access position (e.g. `a.$(x)`, `a.$0`) reported as a
+  pattern. Substitutions resolve to a single key, not a set — that was a
+  misclassification. Use `is_template(path)` to check "contains a
+  substitution."
+
 ### v0.40.0
 - **`unpack()` now returns a `dict`**: Previously returned a tuple of
   `(path, value)` pairs. Now returns `{path: value, ...}` directly.
@@ -2826,18 +2834,36 @@ time:
 
     >>> r = dotted.sqlize("age >= $(min_age)")
     >>> r
-    {'select': 'age', 'where': 'age >= :min_age', 'params': {}, 'missing': ['min_age']}
+    {'select': 'age', 'where': 'age >= :min_age', 'params': {},
+     'unbound': {'min_age': 'min_age'}}
+
+`unbound` is a dict keyed by the **SQL bind parameter name** — the name
+that appears in the SQL `:placeholder` and as a key in `params`. Each
+value is the **original substitution name** (what was inside `$(...)`),
+kept as provenance so callers can trace a bind back to its source.
 
-`missing` lists names that still need a value. Fill them in before passing
-`params` to a driver:
+`unbound.keys()` is the list of bind slots the caller needs to fill.
+Most often you just fill `params` by bind name directly:
 
     >>> r['params']['min_age'] = 30
     >>> # hand (r['where'], r['params']) to cursor.execute / session.execute / etc.
 
-Repeated uses of the same name share one placeholder automatically:
+Non-identifier names (dotted paths, quoted keys, spaces, etc.) hash to a
+deterministic `_s_<hex>` bind name — the bind-side name is different
+from what appeared in source, but the original is preserved in the
+`unbound` value:
+
+    >>> r = dotted.sqlize('age >= $(user.min_age)')
+    >>> r['where']    # doctest: +ELLIPSIS
+    'age >= :_s_...'
+    >>> list(r['unbound'].values())
+    ['user.min_age']
+
+Repeated uses of the same name share one entry automatically:
 
     >>> dotted.sqlize('(age >= $(x) & weight = $(x))')
-    {'where': '(age >= :x) AND (weight = :x)', 'params': {}, 'missing': ['x']}
+    {'where': '(age >= :x) AND (weight = :x)', 'params': {},
+     'unbound': {'x': 'x'}}
 
 If you pass `bindings=`, substitutions are resolved at sqlize time and hoisted
 like any other literal:
@@ -2865,7 +2891,7 @@ Returned dict may contain any subset of:
 | `select`  | `str`       | Expression yielding the value dotted would return   |
 | `where`   | `str`       | Predicate from guards / filters / boolean groups    |
 | `params`  | `dict`      | Hoisted values keyed by name                        |
-| `missing` | `list[str]` | Substitution names still awaiting a value           |
+| `unbound` | `dict`      | Deferred substitutions: `{bind_param_name: original_name}` |
 
 `select` is omitted when combining predicates across different columns
 (e.g. top-level groups), since there's no single meaningful expression.

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/__init__.py

@@ -56,7 +56,8 @@ For full documentation including all options and flags:
     or see README.md
 """
 from .api import \
-    parse, is_pattern, is_template, is_inverted, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
+    parse, is_pattern, is_template, is_reference, is_indeterminate, is_simple, \
+    is_inverted, mutable, quote, ANY, AUTO, Attrs, GroupMode, \
     register, transform, \
     assemble, assemble_multi, \
     build, build_multi, \
@@ -82,7 +83,10 @@ __all__ = [
     # Transform
     'apply', 'apply_multi', 'register', 'transform',
     # Utility
-    'parse', 'assemble', 'assemble_multi', 'quote', 'is_pattern', 'is_template', 'is_inverted', 'mutable',
+    'parse', 'assemble', 'assemble_multi', 'quote',
+    'is_pattern', 'is_template', 'is_reference',
+    'is_indeterminate', 'is_simple',
+    'is_inverted', 'mutable',
     # SQL
     'sqlize', 'TranslationError',
     # Constants

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/access.py

@@ -862,6 +862,22 @@ class SliceFilter(BaseOp):
     def is_pattern(self):
         return False
 
+    def is_template(self):
+        """
+        True if any attached filter contains a substitution reference.
+        """
+        return any(
+            hasattr(f, 'is_template') and f.is_template()
+            for f in self.filters)
+
+    def is_reference(self):
+        """
+        True if any attached filter contains an internal reference.
+        """
+        return any(
+            hasattr(f, 'is_reference') and f.is_reference()
+            for f in self.filters)
+
     def is_empty(self, node):
         return not node
 

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/api.py

@@ -188,6 +188,94 @@ def is_template(key):
     return _is_template(parse(key))
 
 
+@functools.lru_cache(CACHE_SIZE)
+def _is_reference(ops):
+    if not ops:
+        return False
+    if ops[0].is_reference():
+        return True
+    return _is_reference(ops[1:])
+
+
+def is_reference(key):
+    """
+    True if dotted path contains internal references ($$(...)).
+    Walks into wraps, filters, and group branches.
+
+    >>> is_reference('a.$$(b)')
+    True
+    >>> is_reference('a.b')
+    False
+    >>> is_reference('a.$(x)')
+    False
+    """
+    if isinstance(key, results.Dotted):
+        return _is_reference(key)
+    return _is_reference(parse(key))
+
+
+def is_indeterminate(key):
+    """
+    True if the path contains substitutions or references — anything
+    whose access target isn't pinned down by the source alone and
+    requires bindings or data to resolve. Patterns are not indeterminate:
+    they describe a set inherent to the query.
+
+    >>> is_indeterminate('a.$(x)')
+    True
+    >>> is_indeterminate('a.$$(b)')
+    True
+    >>> is_indeterminate('a.b')
+    False
+    >>> is_indeterminate('a.*.b')
+    False
+    """
+    parsed = key if isinstance(key, results.Dotted) else parse(key)
+    return _is_template(parsed) or _is_reference(parsed)
+
+
+@functools.lru_cache(CACHE_SIZE)
+def _is_simple(ops):
+    for op in ops:
+        if not isinstance(op, (access.Key, access.Attr, access.Slot)):
+            return False
+        if not isinstance(op.op, matchers.Const):
+            return False
+    return True
+
+
+def is_simple(key):
+    """
+    True if the path is a plain chain of access ops (Key, Attr, Slot)
+    with literal matchers — no patterns, substitutions, references,
+    guards, transforms, filters, groups, or other decorations.
+
+    This is the strictest classification: paths that spell out one
+    specific access target character-for-character.
+
+    >>> is_simple('a.b.c')
+    True
+    >>> is_simple('a[0].b')
+    True
+    >>> is_simple('a@attr')
+    True
+    >>> is_simple('a.*.b')
+    False
+    >>> is_simple('a=30')
+    False
+    >>> is_simple('a|int')
+    False
+    >>> is_simple('a.$(x)')
+    False
+    >>> is_simple('a.$$(b)')
+    False
+    """
+    parsed = key if isinstance(key, results.Dotted) else parse(key)
+    if parsed.transforms:
+        return False
+    return _is_simple(parsed)
+
+
 def is_inverted(key):
     """
     True if an inverted style pattern

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/base.py

@@ -179,6 +179,12 @@ class TraversalOp(Op):
         """
         return False
 
+    def is_reference(self):
+        """
+        True if this op contains an internal reference.
+        """
+        return False
+
 
 class MatchOp(Op):
     """

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/filters.py

@@ -6,6 +6,20 @@ from . import predicates
 from .access import Slot, Slice
 
 
+def _any_template(items):
+    """
+    True if any item in an iterable has is_template() returning True.
+    """
+    return any(hasattr(x, 'is_template') and x.is_template() for x in items)
+
+
+def _any_reference(items):
+    """
+    True if any item in an iterable has is_reference() returning True.
+    """
+    return any(hasattr(x, 'is_reference') and x.is_reference() for x in items)
+
+
 class FilterOp(base.MatchOp):
     def is_pattern(self):
         return False
@@ -50,6 +64,18 @@ class FilterKey(base.MatchOp):
     def is_dotted(self):
         return len(self.parts) > 1
 
+    def is_template(self):
+        """
+        True if any part of the filter key contains a substitution reference.
+        """
+        return _any_template(self.parts)
+
+    def is_reference(self):
+        """
+        True if any part of the filter key contains an internal reference.
+        """
+        return _any_reference(self.parts)
+
     def get_values(self, node):
         """
         Get all values from node matching this key, traversing dotted path if needed.
@@ -188,6 +214,27 @@ class FilterKeyValue(FilterOp):
         t_str = ''.join('|' + t.operator() for t in self.transforms) if self.transforms else ''
         return f'{self.key}{t_str}{self._eq_str}{self.val}'
 
+    def is_template(self):
+        """
+        True if the key, value, or any transform contains a substitution.
+        """
+        if hasattr(self.key, 'is_template') and self.key.is_template():
+            return True
+        if hasattr(self.val, 'is_template') and self.val.is_template():
+            return True
+        return _any_template(self.transforms)
+
+    def is_reference(self):
+        """
+        True if the key, value, or any transform contains an internal
+        reference.
+        """
+        if hasattr(self.key, 'is_reference') and self.key.is_reference():
+            return True
+        if hasattr(self.val, 'is_reference') and self.val.is_reference():
+            return True
+        return _any_reference(self.transforms)
+
     def _eq_match(self, node):
         """
         True if any value from self.key in node matches self.val (after transforms).
@@ -351,6 +398,16 @@ class FilterGroup(FilterOp):
             return None
         return self.inner.match(op.inner)
 
+    def is_template(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_template')
+                and self.inner.is_template())
+
+    def is_reference(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_reference')
+                and self.inner.is_reference())
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in inner filter.
@@ -403,6 +460,12 @@ class FilterAnd(FilterOp):
             results.append(m)
         return FilterAnd(*results)
 
+    def is_template(self):
+        return _any_template(self.filters)
+
+    def is_reference(self):
+        return _any_reference(self.filters)
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in each filter.
@@ -443,6 +506,12 @@ class FilterOr(FilterOp):
                     seen.add(item_id)
                     yield item
 
+    def is_template(self):
+        return _any_template(self.filters)
+
+    def is_reference(self):
+        return _any_reference(self.filters)
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in each filter.
@@ -488,6 +557,16 @@ class FilterKeyValueFirst(FilterOp):
             return self.inner.match(op.inner)
         return None
 
+    def is_template(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_template')
+                and self.inner.is_template())
+
+    def is_reference(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_reference')
+                and self.inner.is_reference())
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in inner filter.
@@ -541,6 +620,16 @@ class FilterNot(FilterOp):
             return None
         return self.inner.match(op.inner)
 
+    def is_template(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_template')
+                and self.inner.is_template())
+
+    def is_reference(self):
+        return (self.inner is not None
+                and hasattr(self.inner, 'is_reference')
+                and self.inner.is_reference())
+
     def resolve(self, bindings, partial=False):
         """
         Resolve $N in inner filter.

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/groups.py

@@ -42,6 +42,16 @@ class OpGroup(base.TraversalOp):
                     return True
         return False
 
+    def is_reference(self):
+        """
+        True if any branch contains an internal reference.
+        """
+        for branch in base.branches_only(self.branches):
+            for op in branch:
+                if hasattr(op, 'is_reference') and op.is_reference():
+                    return True
+        return False
+
     def default(self):
         """
         Derive default from the first branch's first op, so auto-creation works

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/matchers.py

@@ -150,12 +150,16 @@ class Pattern(MatchOp):
         return True
 
 
-class Subst(Pattern):
+class Subst(MatchOp):
     """
     Substitution op: $0, $(name), $(0|transform), $(name|int), etc.
     Resolves against bindings via __getitem__: list for positional,
     dict for named or numeric keys.  Optional transforms applied
     after lookup.
+
+    Not a Pattern subclass — substitutions resolve to a single key, not
+    a set of keys. is_template() is the right check for "contains a
+    substitution".
     """
     def __init__(self, *args, transforms=(), **kwargs):
         super().__init__(*args, **kwargs)

{dotted_notation-0.43.3 → dotted_notation-0.43.5}/dotted/sqlize.py

@@ -1,7 +1,7 @@
 """
 Translate a dotted path into SQL clause components.
 
-Returns a dict with keys select, where, from, params, missing. Only keys that
+Returns a dict with keys select, where, from, params, unbound. Only keys that
 apply to the given path are included. Callers stitch the fragments into a
 full statement, e.g.:
 
@@ -13,10 +13,12 @@ navigation inside it.
 
 Placeholders are emitted in SQLAlchemy named style (`:name`). Literals on the
 RHS of guards are hoisted into `params` under generated names (`_p1`, `_p2`,
-…). Unresolved substitutions keep their declared names and appear in
-`missing`; callers fill them in by name before executing.
+…). Unresolved substitutions appear in `unbound` as a dict mapping
+`bind_param_name → original_name`; callers fill the params dict by the bind
+name before executing.
 """
 import decimal
+import hashlib
 import re
 
 from . import access
@@ -46,44 +48,29 @@ def _quote_ident(name):
     return '"' + name.replace('"', '""') + '"'
 
 
-# Subst names may themselves be dotted paths. To survive as SQL bind
-# parameter names (which must be plain identifiers), the access operators
-# are encoded with mnemonic tokens. This preserves the distinction
-# between `a.b`, `a@b`, and `a[0]` in the placeholder name.
-_OP_ENCODE = {
-    '.': '_dot_',
-    '@': '_at_',
-    '[': '_br_',
-    ']': '',
-}
+# Substitution names that aren't already valid SQL identifiers are mapped
+# to a hash-based name for use as a SQL bind parameter. Deterministic —
+# the same subst name always produces the same hashed param.
+_HASH_PREFIX = '_s_'
+_GEN_PREFIX = '_p'
+_RESERVED_PREFIXES = (_HASH_PREFIX, _GEN_PREFIX)
 
 
-def _encode_subst_name(name):
+def _param_name_for_subst(name):
     """
-    Encode a subst name (a dotted path) into a plain SQL identifier.
-    Recognised access ops become mnemonic tokens; unsupported characters
-    raise TranslationError.
+    Return a SQL identifier-safe bind parameter name for a substitution.
+
+    Plain identifiers pass through unchanged. Anything else — dotted
+    paths, quoted keys, special characters — hashes to a deterministic
+    `_s_<hex>` name. Names that collide with our reserved generated-name
+    prefixes (`_p<N>`, `_s_`) are also hashed so they can never clobber
+    hoisted literals.
     """
-    if _IDENT_RE.fullmatch(name):
+    if _IDENT_RE.fullmatch(name) and not any(
+            name.startswith(p) for p in _RESERVED_PREFIXES):
         return name
-    out = []
-    for c in name:
-        if c in _OP_ENCODE:
-            out.append(_OP_ENCODE[c])
-        elif c.isalnum() or c == '_':
-            out.append(c)
-        else:
-            raise TranslationError(
-                f'cannot encode character {c!r} in substitution name {name!r}; '
-                'resolve via bindings= at sqlize time'
-            )
-    encoded = ''.join(out)
-    if not _IDENT_RE.fullmatch(encoded):
-        raise TranslationError(
-            f'substitution name {name!r} does not encode to a valid '
-            'SQL identifier'
-        )
-    return encoded
+    h = hashlib.sha256(name.encode('utf-8')).hexdigest()[:12]
+    return f'{_HASH_PREFIX}{h}'
 
 
 def _pg_path_segment(seg):
@@ -112,38 +99,41 @@ def _pg_string_literal(s):
 class _ParamState:
     """
     Shared state for hoisted params across a translate call and its
-    sub-translators. Generated param names use the `_p{n}` convention;
-    substitution param names come from the substitution itself.
+    sub-translators. Generated literal names use `_p{N}`; deferred
+    substitutions use their name when it's already a valid identifier,
+    or a `_s_<hex>` hash otherwise.
     """
 
     def __init__(self):
-        self.params = {}          # name → resolved value
-        self.missing = []         # list of substitution names awaiting a value
+        self.params = {}   # bind name → resolved value
+        self.unbound = {}  # bind name → original subst name
         self._gen_counter = 0
+        self._by_orig = {}  # original subst name → bind name (dedup)
 
     def hoist_literal(self, value):
         """
         Hoist a concrete literal into a generated-name slot.
         """
         self._gen_counter += 1
-        name = f'_p{self._gen_counter}'
+        name = f'{_GEN_PREFIX}{self._gen_counter}'
         self.params[name] = value
         return name
 
     def hoist_named(self, name):
         """
-        Hoist a named substitution. If a value is supplied later it lands
-        under the encoded name; until then it's recorded in `missing`.
-
-        Names that already are plain identifiers are used as-is. Dotted
-        paths (`$(user.age)`, `$(users[0].name)`, `$(obj@attr)`) are
-        encoded into plain identifiers using mnemonic tokens for access
-        ops so they can serve as SQL bind-parameter names.
+        Hoist a named substitution. If the name is already a valid SQL
+        identifier it's used directly as the bind parameter; otherwise a
+        deterministic `_s_<hash>` name is generated. The bind parameter
+        name keys the mapping in `unbound`, with the original source
+        name as the value. Repeated uses share one entry.
         """
-        encoded = _encode_subst_name(str(name))
-        if encoded not in self.params and encoded not in self.missing:
-            self.missing.append(encoded)
-        return encoded
+        name = str(name)
+        if name in self._by_orig:
+            return self._by_orig[name]
+        param = _param_name_for_subst(name)
+        self._by_orig[name] = param
+        self.unbound[param] = name
+        return param
 
 
 class _Translator:
@@ -196,8 +186,8 @@ class _Translator:
     def _result(self, **kw):
         d = {k: v for k, v in kw.items() if v is not None}
         d['params'] = dict(self.state.params)
-        if self.state.missing:
-            d['missing'] = list(self.state.missing)
+        if self.state.unbound:
+            d['unbound'] = dict(self.state.unbound)
         return d
 
     def _column_name(self, op):
@@ -490,20 +480,23 @@ def sqlize(path, *, bindings=None, flavor='postgres', format='sqlalchemy'):
     Translate a dotted path into SQL clause components.
 
     Returns a dict with some subset of keys select, where, from, params,
-    missing.
+    unbound.
 
     path — dotted path string or pre-parsed Dotted result.
     bindings — optional mapping/list used to resolve substitutions before
         translation. Path-position substitutions must be resolved or a
         TranslationError is raised. Unresolved value-position substitutions
-        keep their declared names and appear in 'missing'.
+        appear in 'unbound'.
     flavor — SQL flavor for JSONB operators; only 'postgres' is implemented.
     format — placeholder style. Only 'sqlalchemy' (`:name`) is supported in v1.
 
     Literals on the RHS of guards are hoisted into params under generated
-    names (`_p1`, `_p2`, …). Named substitutions keep their original names.
-    Callers fill any names still in 'missing' before handing params to a
-    driver.
+    names (`_p1`, `_p2`, …). Substitutions are hoisted under their own
+    name when it's a valid SQL identifier; otherwise a deterministic
+    `_s_<hash>` bind name is generated. Unresolved substitutions appear
+    in 'unbound' as a dict mapping bind_param_name → original_name so
+    callers can fill params by bind name and recover the source name
+    when needed.
 
     >>> sqlize("status = 'active'")
     {'select': 'status', 'where': 'status = :_p1', 'params': {'_p1': 'active'}}