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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.4
+Version: 0.43.6
 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
@@ -2801,9 +2801,11 @@ View all registered transforms with `dotted.registry()`.
 ## SQL Translation (`sqlize`)
 
 > **Under development.** The API shape, output format, and supported subset
-> of dotted features may still change. Postgres-only, SQLAlchemy-style named
-> placeholders, scalar paths plus absolute-root references. Patterns (`*`,
-> `**`, `[*]`, filter-on-array) are not supported yet.
+> of dotted features may still change. Postgres-only, SQLAlchemy-style
+> named placeholders. Pattern paths (`*`, `[*]`, `**`, filter brackets)
+> are supported only as WHERE-side existence checks via
+> `jsonb_path_exists`; pattern paths that yield sets as SELECT (needing
+> `LATERAL jsonb_path_query`) are not supported yet.
 
 `dotted.sqlize` translates a dotted path into SQL clause components — a
 `select` expression, a `where` predicate, and a `params` dict with hoisted
@@ -2871,18 +2873,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:
@@ -2901,6 +2921,41 @@ Postgres's `->` / `#>` accept runtime-computed keys:
 Relative references (`^`) and parent references (`^^+`) are not supported
 yet.
 
+### Pattern paths
+
+Paths that contain wildcards (`*`, `[*]`), recursive descent (`**`), or
+bracket filters (`[pred]`, `[*&pred]`) translate to a Postgres
+`jsonb_path_exists(…)` WHERE predicate. The dotted path becomes a JSONPath
+expression; guard values embed inline when safely literal (numbers,
+booleans, null) or flow through a `jsonb_build_object` vars argument
+(strings, substitutions).
+
+    >>> dotted.sqlize("data.users[*].age >= 30")['where']
+    "jsonb_path_exists(data, '$.users[*].age ? (@ >= 30)')"
+
+    >>> dotted.sqlize("data.**.active = True")['where']
+    "jsonb_path_exists(data, '$.**.active ? (@ == true)')"
+
+    >>> dotted.sqlize("data.users[age>=30]")['where']
+    "jsonb_path_exists(data, '$.users[*] ? (@.age >= 30)')"
+
+    >>> dotted.sqlize('data.users[*&age>=30].name = "alice"')['where']
+    "jsonb_path_exists(data, '$.users[*] ? (@.age >= 30).name ? (@ == :_p1)', jsonb_build_object('_p1', :_p1))"
+
+Pattern predicates compose with scalar ones via dotted's `&` / `,` / `!`:
+
+    >>> dotted.sqlize('(data.users[*].age >= 30 & status = "active")')['where']
+    "(jsonb_path_exists(data, '$.users[*].age ? (@ >= 30)')) AND (status = :_p1)"
+
+`select` is set to the column itself — pattern paths don't have a single
+extractable value. Use the WHERE predicate to filter rows; write your
+own SELECT for the columns you want.
+
+Not yet supported:
+- Pattern paths as SELECT (needing `LATERAL jsonb_path_query`)
+- Regex-in-access like `data./prefix_\d+/.field`
+- Pattern refs
+
 ### Output keys
 
 Returned dict may contain any subset of:
@@ -2910,7 +2965,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.6}/README.md

@@ -2764,9 +2764,11 @@ View all registered transforms with `dotted.registry()`.
 ## SQL Translation (`sqlize`)
 
 > **Under development.** The API shape, output format, and supported subset
-> of dotted features may still change. Postgres-only, SQLAlchemy-style named
-> placeholders, scalar paths plus absolute-root references. Patterns (`*`,
-> `**`, `[*]`, filter-on-array) are not supported yet.
+> of dotted features may still change. Postgres-only, SQLAlchemy-style
+> named placeholders. Pattern paths (`*`, `[*]`, `**`, filter brackets)
+> are supported only as WHERE-side existence checks via
+> `jsonb_path_exists`; pattern paths that yield sets as SELECT (needing
+> `LATERAL jsonb_path_query`) are not supported yet.
 
 `dotted.sqlize` translates a dotted path into SQL clause components — a
 `select` expression, a `where` predicate, and a `params` dict with hoisted
@@ -2834,18 +2836,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:
@@ -2864,6 +2884,41 @@ Postgres's `->` / `#>` accept runtime-computed keys:
 Relative references (`^`) and parent references (`^^+`) are not supported
 yet.
 
+### Pattern paths
+
+Paths that contain wildcards (`*`, `[*]`), recursive descent (`**`), or
+bracket filters (`[pred]`, `[*&pred]`) translate to a Postgres
+`jsonb_path_exists(…)` WHERE predicate. The dotted path becomes a JSONPath
+expression; guard values embed inline when safely literal (numbers,
+booleans, null) or flow through a `jsonb_build_object` vars argument
+(strings, substitutions).
+
+    >>> dotted.sqlize("data.users[*].age >= 30")['where']
+    "jsonb_path_exists(data, '$.users[*].age ? (@ >= 30)')"
+
+    >>> dotted.sqlize("data.**.active = True")['where']
+    "jsonb_path_exists(data, '$.**.active ? (@ == true)')"
+
+    >>> dotted.sqlize("data.users[age>=30]")['where']
+    "jsonb_path_exists(data, '$.users[*] ? (@.age >= 30)')"
+
+    >>> dotted.sqlize('data.users[*&age>=30].name = "alice"')['where']
+    "jsonb_path_exists(data, '$.users[*] ? (@.age >= 30).name ? (@ == :_p1)', jsonb_build_object('_p1', :_p1))"
+
+Pattern predicates compose with scalar ones via dotted's `&` / `,` / `!`:
+
+    >>> dotted.sqlize('(data.users[*].age >= 30 & status = "active")')['where']
+    "(jsonb_path_exists(data, '$.users[*].age ? (@ >= 30)')) AND (status = :_p1)"
+
+`select` is set to the column itself — pattern paths don't have a single
+extractable value. Use the WHERE predicate to filter rows; write your
+own SELECT for the columns you want.
+
+Not yet supported:
+- Pattern paths as SELECT (needing `LATERAL jsonb_path_query`)
+- Regex-in-access like `data./prefix_\d+/.field`
+- Pattern refs
+
 ### Output keys
 
 Returned dict may contain any subset of:
@@ -2873,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.6}/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.6}/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.6}/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.6}/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.6}/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.6}/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