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

{dotted_notation-0.43.4/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.4
+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
@@ -2871,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'}}
 
-`missing` lists names that still need a value. Fill them in before passing
-`params` to a driver:
+`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.
+
+`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:
@@ -2910,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.4 → dotted_notation-0.43.5}/README.md

@@ -2834,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'}}
 
-`missing` lists names that still need a value. Fill them in before passing
-`params` to a driver:
+`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.
+
+`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:
@@ -2873,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.4 → 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.4 → dotted_notation-0.43.5}/dotted/access.py

@@ -870,6 +870,14 @@ class SliceFilter(BaseOp):
             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.4 → 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.4 → 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.4 → dotted_notation-0.43.5}/dotted/filters.py

@@ -13,6 +13,13 @@ def _any_template(items):
     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
@@ -63,6 +70,12 @@ class FilterKey(base.MatchOp):
         """
         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.
@@ -211,6 +224,17 @@ class FilterKeyValue(FilterOp):
             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).
@@ -379,6 +403,11 @@ class FilterGroup(FilterOp):
                 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.
@@ -434,6 +463,9 @@ class FilterAnd(FilterOp):
     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.
@@ -477,6 +509,9 @@ class FilterOr(FilterOp):
     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.
@@ -527,6 +562,11 @@ class FilterKeyValueFirst(FilterOp):
                 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.
@@ -585,6 +625,11 @@ class FilterNot(FilterOp):
                 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.4 → 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.4 → 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'}}

{dotted_notation-0.43.4 → dotted_notation-0.43.5}/dotted/wrappers.py

@@ -216,6 +216,20 @@ class ValueGuard(Wrap):
                 return True
         return False
 
+    def is_reference(self):
+        """
+        True if the inner op, the guard value, or any transform contains
+        an internal reference.
+        """
+        if self.inner.is_reference():
+            return True
+        if hasattr(self.guard, 'is_reference') and self.guard.is_reference():
+            return True
+        for t in self.transforms:
+            if hasattr(t, 'is_reference') and t.is_reference():
+                return True
+        return False
+
     def is_recursive(self):
         return self.inner.is_recursive()
 
@@ -444,6 +458,17 @@ class FilterWrap(Wrap):
             hasattr(f, 'is_template') and f.is_template()
             for f in self.filters)
 
+    def is_reference(self):
+        """
+        True if the inner op or any attached filter contains an internal
+        reference.
+        """
+        if self.inner.is_reference():
+            return True
+        return any(
+            hasattr(f, 'is_reference') and f.is_reference()
+            for f in self.filters)
+
     def default(self):
         """
         Filters imply the value has structure to check against,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.4
+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
@@ -2871,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'}}
 
-`missing` lists names that still need a value. Fill them in before passing
-`params` to a driver:
+`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.
+
+`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:
@@ -2910,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.4 → dotted_notation-0.43.5}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "rt") as f:
 
 setuptools.setup(
     name="dotted_notation",
-    version="0.43.4",
+    version="0.43.5",
     author="Frey Waid",
     author_email="logophage1@gmail.com",
     description="Dotted notation for safe nested data traversal with optional chaining, pattern matching, and transforms",

{dotted_notation-0.43.4 → dotted_notation-0.43.5}/tests/test_api.py

@@ -65,6 +65,115 @@ def test_is_inverted_false():
     assert dotted.is_inverted('*') is False
 
 
+# ---- is_reference ----
+
+def test_is_reference_top_level():
+    assert dotted.is_reference('a.$$(b)') is True
+    assert dotted.is_reference('$$(x.y)') is True
+
+
+def test_is_reference_in_guard():
+    # Ref in guard position (previously missed)
+    assert dotted.is_reference('a=$$(b)') is True
+    assert dotted.is_reference('a>=$$(b)') is True
+
+
+def test_is_reference_in_filter():
+    assert dotted.is_reference('a[*&x=$$(b)]') is True
+    assert dotted.is_reference('a[$$(k)=1]') is True
+    assert dotted.is_reference('a[!x=$$(b)]') is True
+
+
+def test_is_reference_in_group():
+    assert dotted.is_reference('(a=$$(b) & c=1)') is True
+
+
+def test_is_reference_false_for_plain():
+    assert dotted.is_reference('a.b') is False
+    assert dotted.is_reference('a.*.b') is False
+
+
+def test_is_reference_false_for_template():
+    # Substitutions are not references
+    assert dotted.is_reference('a.$(x)') is False
+    assert dotted.is_reference('a=$(x)') is False
+
+
+# ---- is_indeterminate ----
+
+def test_is_indeterminate_templates():
+    assert dotted.is_indeterminate('a.$(x)') is True
+    assert dotted.is_indeterminate('a=$(x)') is True
+
+
+def test_is_indeterminate_references():
+    assert dotted.is_indeterminate('a.$$(b)') is True
+    assert dotted.is_indeterminate('a=$$(b)') is True
+
+
+def test_is_indeterminate_false_for_plain():
+    assert dotted.is_indeterminate('a.b.c') is False
+    assert dotted.is_indeterminate('a[0]') is False
+    assert dotted.is_indeterminate('a=30') is False
+
+
+def test_is_indeterminate_false_for_patterns():
+    # Patterns are not indeterminate — they describe a set inherent to
+    # the query, not a placeholder awaiting info.
+    assert dotted.is_indeterminate('a.*.b') is False
+    assert dotted.is_indeterminate('a.**') is False
+
+
+# ---- is_simple ----
+
+def test_is_simple_true_for_plain_paths():
+    assert dotted.is_simple('a') is True
+    assert dotted.is_simple('a.b.c') is True
+    assert dotted.is_simple('a[0].b') is True
+    assert dotted.is_simple('a@attr') is True
+    assert dotted.is_simple('a.b[0].c') is True
+
+
+def test_is_simple_false_for_patterns():
+    assert dotted.is_simple('a.*.b') is False
+    assert dotted.is_simple('a[*]') is False
+    assert dotted.is_simple('a.**') is False
+    assert dotted.is_simple('a=/re/') is False
+
+
+def test_is_simple_false_for_templates():
+    assert dotted.is_simple('a.$(x)') is False
+    assert dotted.is_simple('a.$0') is False
+
+
+def test_is_simple_false_for_references():
+    assert dotted.is_simple('a.$$(b)') is False
+
+
+def test_is_simple_false_for_guards():
+    assert dotted.is_simple('a=30') is False
+    assert dotted.is_simple('a.b=1') is False
+
+
+def test_is_simple_false_for_transforms():
+    assert dotted.is_simple('a|int') is False
+    assert dotted.is_simple('a.b|str') is False
+
+
+def test_is_simple_false_for_filters():
+    assert dotted.is_simple('a[*&x=1]') is False
+    assert dotted.is_simple('a[x=1]') is False
+
+
+def test_is_simple_false_for_groups():
+    assert dotted.is_simple('(a, b)') is False
+    assert dotted.is_simple('a.(b, c)') is False
+
+
+def test_is_simple_false_for_inverted():
+    assert dotted.is_simple('!a') is False
+
+
 # build / build_multi
 
 def test_build_simple():

{dotted_notation-0.43.4 → dotted_notation-0.43.5}/tests/test_sqlize.py

@@ -297,23 +297,24 @@ def test_value_sub_with_binding():
 
 
 def test_value_sub_without_binding():
-    # Unbound substitution keeps its name; listed in missing
+    # Unbound substitution: name is already a valid identifier, so it's
+    # used directly as the bind name. unbound maps bind → orig.
     result = sqlize('age>=$(min_age)')
     assert result == {
         'select': 'age',
         'where': 'age >= :min_age',
         'params': {},
-        'missing': ['min_age'],
+        'unbound': {'min_age': 'min_age'},
     }
 
 
 def test_value_sub_repeated_dedupes():
-    # Same name used twice → single :x placeholder, one missing entry
+    # Same name used twice → single placeholder, one unbound entry.
     result = sqlize('(age>=$(x) & weight=$(x))')
     assert result == {
         'where': '(age >= :x) AND (weight = :x)',
         'params': {},
-        'missing': ['x'],
+        'unbound': {'x': 'x'},
     }
 
 
@@ -322,7 +323,7 @@ def test_mixed_subst_and_literal():
     assert result == {
         'where': '(age >= :min_age) AND (weight > :_p1)',
         'params': {'_p1': 200},
-        'missing': ['min_age'],
+        'unbound': {'min_age': 'min_age'},
     }
 
 
@@ -337,39 +338,40 @@ def test_value_sub_dotted_name_with_bindings():
     }
 
 
-def test_value_sub_dotted_name_encoded():
-    # Dotted subst name is encoded into a plain SQL identifier.
+def test_value_sub_dotted_name_hashed():
+    # Dotted subst name hashes to an _s_<hex> bind name; unbound maps
+    # bind → orig so callers can recover the source name.
     result = sqlize('age>=$(user.min_age)')
-    assert result == {
-        'select': 'age',
-        'where': 'age >= :user_dot_min_age',
-        'params': {},
-        'missing': ['user_dot_min_age'],
-    }
-
-
-def test_value_sub_attr_name_encoded():
-    result = sqlize('age>=$(obj@attr)')
-    assert result['where'] == 'age >= :obj_at_attr'
-    assert result['missing'] == ['obj_at_attr']
+    assert result['select'] == 'age'
+    assert set(result['unbound'].values()) == {'user.min_age'}
+    [(bind, orig)] = result['unbound'].items()
+    assert bind.startswith('_s_')
+    assert orig == 'user.min_age'
+    assert result['where'] == f'age >= :{bind}'
+    assert result['params'] == {}
 
 
-def test_value_sub_slot_name_encoded():
-    result = sqlize('age>=$(arr[0])')
-    assert result['where'] == 'age >= :arr_br_0'
-    assert result['missing'] == ['arr_br_0']
+def test_value_sub_hash_is_deterministic():
+    # Same subst name → same hash across calls (still keyed by bind)
+    a = list(sqlize('age>=$(user.min_age)')['unbound'])[0]
+    b = list(sqlize('weight>=$(user.min_age)')['unbound'])[0]
+    assert a == b
 
 
-def test_value_sub_mixed_path_name_encoded():
-    result = sqlize('age>=$(users[0].name)')
-    assert result['where'] == 'age >= :users_br_0_dot_name'
-    assert result['missing'] == ['users_br_0_dot_name']
+def test_value_sub_hash_names_are_distinct():
+    # Different subst names produce different hashes
+    a = list(sqlize('age>=$(user.min_age)')['unbound'])[0]
+    b = list(sqlize('age>=$(user.max_age)')['unbound'])[0]
+    assert a != b
 
 
-def test_value_sub_unencodable_char_errors():
-    # Characters outside the supported op set raise
-    with pytest.raises(TranslationError):
-        sqlize('age>=$(user age)')
+def test_value_sub_special_char_hashed():
+    # Names with spaces / quotes / punctuation hash without erroring
+    result = sqlize("age>=$('dr pepper')")
+    assert set(result['unbound'].values()) == {"'dr pepper'"}
+    [(bind, orig)] = result['unbound'].items()
+    assert bind.startswith('_s_')
+    assert orig == "'dr pepper'"
 
 
 def test_path_sub_with_binding():