dotted-notation 0.43.7__tar.gz → 0.43.8__tar.gz

{dotted_notation-0.43.7/dotted_notation.egg-info → dotted_notation-0.43.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.7
+Version: 0.43.8
 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
@@ -2977,10 +2977,26 @@ Not yet supported:
 
 ### Paramstyles
 
-`Resolver.build(sql, paramstyle='named', **bindings)` defaults to
-PEP 249 named style (`:name`). For Postgres-native `$N` (what asyncpg
-and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
-— the output changes to positional:
+`Resolver.build(sql, paramstyle='named', **bindings)` renders the
+fragment in the chosen PEP 249 paramstyle. Supported:
+
+| paramstyle        | placeholder    | output shape | typical driver            |
+|-------------------|----------------|--------------|---------------------------|
+| `named`           | `:name`        | dict         | SQLAlchemy `text`, sqlite3 |
+| `pyformat`        | `%(name)s`     | dict         | psycopg (v2/v3) named     |
+| `qmark`           | `?`            | list         | sqlite3, ODBC             |
+| `format`          | `%s`           | list         | psycopg positional        |
+| `numeric`         | `:1, :2`       | list         | Oracle-style              |
+| `dollar-numeric`  | `$1, $2`       | list         | asyncpg, native Postgres  |
+
+The dict styles (`named`, `pyformat`) and the numbered positional
+styles (`numeric`, `dollar-numeric`) have **back-reference**: a
+substitution used in multiple places in the SQL shares a single bind
+entry. `qmark` and `format` have no back-reference — each occurrence
+consumes its own arg, so a repeated substitution emits its value
+multiple times.
+
+Examples:
 
     >>> r = dotted.sqlize('(age >= 18 & status = "active")')
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric')
@@ -2990,8 +3006,16 @@ and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric', min_age=30)
     ('age >= $1', [30])
 
-Under `'dollar-numeric'`, the second element is a list of positional
-args ready for `await conn.execute(sql, *args)` asyncpg style.
+    >>> dotted.Resolver.build(r.where, paramstyle='pyformat', min_age=30)
+    ('age >= %(min_age)s', {'min_age': 30})
+
+Back-reference vs no-backref on repeated substitutions:
+
+    >>> r = dotted.sqlize('(age >= $(x) & weight = $(x))')
+    >>> dotted.Resolver.build(r.where, paramstyle='numeric', x=42)
+    ('(age >= :1) AND (weight = :1)', [42])
+    >>> dotted.Resolver.build(r.where, paramstyle='qmark', x=42)
+    ('(age >= ?) AND (weight = ?)', [42, 42])
 
 A `ParamStyle` `StrEnum` is also available for autocomplete and type
 checking:

{dotted_notation-0.43.7 → dotted_notation-0.43.8}/README.md

@@ -2940,10 +2940,26 @@ Not yet supported:
 
 ### Paramstyles
 
-`Resolver.build(sql, paramstyle='named', **bindings)` defaults to
-PEP 249 named style (`:name`). For Postgres-native `$N` (what asyncpg
-and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
-— the output changes to positional:
+`Resolver.build(sql, paramstyle='named', **bindings)` renders the
+fragment in the chosen PEP 249 paramstyle. Supported:
+
+| paramstyle        | placeholder    | output shape | typical driver            |
+|-------------------|----------------|--------------|---------------------------|
+| `named`           | `:name`        | dict         | SQLAlchemy `text`, sqlite3 |
+| `pyformat`        | `%(name)s`     | dict         | psycopg (v2/v3) named     |
+| `qmark`           | `?`            | list         | sqlite3, ODBC             |
+| `format`          | `%s`           | list         | psycopg positional        |
+| `numeric`         | `:1, :2`       | list         | Oracle-style              |
+| `dollar-numeric`  | `$1, $2`       | list         | asyncpg, native Postgres  |
+
+The dict styles (`named`, `pyformat`) and the numbered positional
+styles (`numeric`, `dollar-numeric`) have **back-reference**: a
+substitution used in multiple places in the SQL shares a single bind
+entry. `qmark` and `format` have no back-reference — each occurrence
+consumes its own arg, so a repeated substitution emits its value
+multiple times.
+
+Examples:
 
     >>> r = dotted.sqlize('(age >= 18 & status = "active")')
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric')
@@ -2953,8 +2969,16 @@ and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric', min_age=30)
     ('age >= $1', [30])
 
-Under `'dollar-numeric'`, the second element is a list of positional
-args ready for `await conn.execute(sql, *args)` asyncpg style.
+    >>> dotted.Resolver.build(r.where, paramstyle='pyformat', min_age=30)
+    ('age >= %(min_age)s', {'min_age': 30})
+
+Back-reference vs no-backref on repeated substitutions:
+
+    >>> r = dotted.sqlize('(age >= $(x) & weight = $(x))')
+    >>> dotted.Resolver.build(r.where, paramstyle='numeric', x=42)
+    ('(age >= :1) AND (weight = :1)', [42])
+    >>> dotted.Resolver.build(r.where, paramstyle='qmark', x=42)
+    ('(age >= ?) AND (weight = ?)', [42, 42])
 
 A `ParamStyle` `StrEnum` is also available for autocomplete and type
 checking:

{dotted_notation-0.43.7 → dotted_notation-0.43.8}/dotted/sqlize.py

@@ -198,9 +198,22 @@ class ParamStyle(enum.StrEnum):
 
     `StrEnum` — members compare equal to their string values, so callers
     can pass either `ParamStyle.named` or `'named'`.
+
+    Output shape:
+      - `named` / `pyformat`: `(sql, params_dict)`. Repeated markers
+        share one binding entry (back-reference by name).
+      - `dollar-numeric` / `numeric`: `(sql, args_list)`. Repeated
+        markers share one position (back-reference by number).
+      - `qmark` / `format`: `(sql, args_list)`. Each marker occurrence
+        produces a separate arg — these styles have no back-reference
+        so a repeated substitution's value is emitted multiple times.
     """
-    named = 'named'                    # :name     (SQLAlchemy, sqlite3, etc.)
-    dollar_numeric = 'dollar-numeric'  # $1, $2    (asyncpg, native PG)
+    named = 'named'                    # :name         (SQLAlchemy, sqlite3)
+    pyformat = 'pyformat'              # %(name)s      (psycopg)
+    qmark = 'qmark'                    # ?             (sqlite3 positional)
+    format = 'format'                  # %s            (psycopg positional)
+    numeric = 'numeric'                # :1, :2        (Oracle-style)
+    dollar_numeric = 'dollar-numeric'  # $1, $2        (asyncpg, native PG)
 
 
 _PARAMSTYLES = tuple(ps.value for ps in ParamStyle)
@@ -280,20 +293,23 @@ class SQLFragment:
         """
         Return self.text with every `{marker}` replaced by the return
         value of `replacer(marker_name)`. Text-level operation: the
-        caller decides what placeholder form to emit (`:name`, `$N`, or
-        anything else) and is responsible for tracking per-marker values
+        caller decides what placeholder form to emit (`:name`, `$N`,
+        `?`, etc.) and is responsible for tracking per-marker values
         externally. Literal braces in the fragment (doubled as `{{`/
-        `}}`) are unescaped to single braces in the output, as per
-        Python `str.format` rules.
+        `}}`) are unescaped to single braces in the output, per Python
+        format-string rules.
 
-        `replacer(name)` is called at most once per unique marker; the
-        result is reused for subsequent occurrences.
+        `replacer(name)` is called **once per occurrence**, in source
+        order. Callers that want back-referencing semantics (e.g.
+        `:name` or `$N` sharing one slot across multiple occurrences)
+        must cache results themselves.
         """
-        mapping = {}
-        for _, name, _, _ in _FORMATTER.parse(self.text):
-            if name is not None and name not in mapping:
-                mapping[name] = replacer(name)
-        return self.text.format(**mapping)
+        parts = []
+        for literal, name, _, _ in _FORMATTER.parse(self.text):
+            parts.append(literal)
+            if name is not None:
+                parts.append(replacer(name))
+        return ''.join(parts)
 
 
 class Resolver:
@@ -370,19 +386,26 @@ class Resolver:
                 f'unknown binding(s) for this fragment: {sorted(extra)}'
             )
 
-        # Build a per-paramstyle replacer that both collects output
-        # params/args and returns the placeholder text for each marker.
+        # Build a per-paramstyle replacer. Replacers are called once
+        # per marker occurrence — name-keyed styles cache results so
+        # repeated markers share a single param; positional back-ref
+        # styles (numeric, dollar-numeric) cache by position; qmark /
+        # format emit a fresh arg for every occurrence.
         missing = []
-        if paramstyle == 'named':
+        if paramstyle in ('named', 'pyformat'):
             out_params = {}
+            fmt = ':{name}' if paramstyle == 'named' else '%({name})s'
 
             def replacer(marker):
                 value = cls._lookup_value(sql, marker, bindings, missing)
                 if value is _MISSING:
-                    return ''   # errored below
+                    return ''
                 out_params[marker] = value
-                return f':{marker}'
-        else:  # dollar-numeric
+                return fmt.format(name=marker)
+
+            out_values = out_params
+        elif paramstyle in ('numeric', 'dollar-numeric'):
+            prefix = '$' if paramstyle == 'dollar-numeric' else ':'
             out_args = []
             pos_by_marker = {}
 
@@ -393,10 +416,24 @@ class Resolver:
                 if value is _MISSING:
                     return ''
                 out_args.append(value)
-                ph = f'${len(out_args)}'
+                ph = f'{prefix}{len(out_args)}'
                 pos_by_marker[marker] = ph
                 return ph
 
+            out_values = out_args
+        else:  # qmark, format — no back-reference
+            placeholder = '?' if paramstyle == 'qmark' else '%s'
+            out_args = []
+
+            def replacer(marker):
+                value = cls._lookup_value(sql, marker, bindings, missing)
+                if value is _MISSING:
+                    return ''
+                out_args.append(value)
+                return placeholder
+
+            out_values = out_args
+
         final = sql.substitute(replacer)
 
         if missing:
@@ -404,9 +441,7 @@ class Resolver:
                 f'missing binding(s) for substitution(s): '
                 f'{sorted(set(missing))}'
             )
-        if paramstyle == 'named':
-            return final, out_params
-        return final, out_args
+        return final, out_values
 
     @staticmethod
     def _lookup_value(sql, marker, bindings, missing):

{dotted_notation-0.43.7 → dotted_notation-0.43.8/dotted_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotted_notation
-Version: 0.43.7
+Version: 0.43.8
 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
@@ -2977,10 +2977,26 @@ Not yet supported:
 
 ### Paramstyles
 
-`Resolver.build(sql, paramstyle='named', **bindings)` defaults to
-PEP 249 named style (`:name`). For Postgres-native `$N` (what asyncpg
-and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
-— the output changes to positional:
+`Resolver.build(sql, paramstyle='named', **bindings)` renders the
+fragment in the chosen PEP 249 paramstyle. Supported:
+
+| paramstyle        | placeholder    | output shape | typical driver            |
+|-------------------|----------------|--------------|---------------------------|
+| `named`           | `:name`        | dict         | SQLAlchemy `text`, sqlite3 |
+| `pyformat`        | `%(name)s`     | dict         | psycopg (v2/v3) named     |
+| `qmark`           | `?`            | list         | sqlite3, ODBC             |
+| `format`          | `%s`           | list         | psycopg positional        |
+| `numeric`         | `:1, :2`       | list         | Oracle-style              |
+| `dollar-numeric`  | `$1, $2`       | list         | asyncpg, native Postgres  |
+
+The dict styles (`named`, `pyformat`) and the numbered positional
+styles (`numeric`, `dollar-numeric`) have **back-reference**: a
+substitution used in multiple places in the SQL shares a single bind
+entry. `qmark` and `format` have no back-reference — each occurrence
+consumes its own arg, so a repeated substitution emits its value
+multiple times.
+
+Examples:
 
     >>> r = dotted.sqlize('(age >= 18 & status = "active")')
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric')
@@ -2990,8 +3006,16 @@ and other raw PG drivers accept), pass `paramstyle='dollar-numeric'`
     >>> dotted.Resolver.build(r.where, paramstyle='dollar-numeric', min_age=30)
     ('age >= $1', [30])
 
-Under `'dollar-numeric'`, the second element is a list of positional
-args ready for `await conn.execute(sql, *args)` asyncpg style.
+    >>> dotted.Resolver.build(r.where, paramstyle='pyformat', min_age=30)
+    ('age >= %(min_age)s', {'min_age': 30})
+
+Back-reference vs no-backref on repeated substitutions:
+
+    >>> r = dotted.sqlize('(age >= $(x) & weight = $(x))')
+    >>> dotted.Resolver.build(r.where, paramstyle='numeric', x=42)
+    ('(age >= :1) AND (weight = :1)', [42])
+    >>> dotted.Resolver.build(r.where, paramstyle='qmark', x=42)
+    ('(age >= ?) AND (weight = ?)', [42, 42])
 
 A `ParamStyle` `StrEnum` is also available for autocomplete and type
 checking:

{dotted_notation-0.43.7 → dotted_notation-0.43.8}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "rt") as f:
 
 setuptools.setup(
     name="dotted_notation",
-    version="0.43.7",
+    version="0.43.8",
     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.7 → dotted_notation-0.43.8}/tests/test_sqlize.py

@@ -12,7 +12,14 @@ from dotted.sqlize import (
 
 # All supported paramstyles as fixture values. Used to parametrize
 # scenario tests so each runs under every paramstyle.
-PARAMSTYLES = ['named', 'dollar-numeric']
+PARAMSTYLES = ['named', 'pyformat', 'qmark', 'format', 'numeric', 'dollar-numeric']
+
+# Styles that share bindings by back-reference (repeated markers collapse
+# to one entry). qmark/format have no back-reference and repeat values.
+BACKREF_STYLES = ['named', 'pyformat', 'numeric', 'dollar-numeric']
+
+# Styles that return a dict vs a list.
+DICT_STYLES = ['named', 'pyformat']
 
 
 # ---------------- scalar columns ----------------
@@ -522,7 +529,7 @@ def test_unsupported_flavor_errors():
 def test_unsupported_paramstyle_errors():
     r = sqlize('age=30')
     with pytest.raises(TranslationError, match='unsupported paramstyle'):
-        Resolver.build(r.where, paramstyle='qmark')
+        Resolver.build(r.where, paramstyle='bogus')
 
 
 # ---------------- identifier quoting ----------------
@@ -567,20 +574,32 @@ def test_dollar_numeric_with_subst():
 def _placeholder(paramstyle, name, position):
     """
     Return the expected placeholder string for a given paramstyle.
-    name: the bind name (for named) — ignored for positional.
+    name: the bind name (for name-keyed styles) — ignored for positional.
     position: 1-based position in the final SQL.
     """
     if paramstyle == 'named':
         return f':{name}'
-    return f'${position}'
+    if paramstyle == 'pyformat':
+        return f'%({name})s'
+    if paramstyle == 'numeric':
+        return f':{position}'
+    if paramstyle == 'dollar-numeric':
+        return f'${position}'
+    if paramstyle == 'qmark':
+        return '?'
+    if paramstyle == 'format':
+        return '%s'
+    raise ValueError(paramstyle)
 
 
 def _values(paramstyle, items):
     """
     Build the expected params (dict) or args (list) from an ordered
-    list of (bind_name, value) tuples.
+    list of (bind_name, value) tuples. Each test passes items in the
+    canonical named-paramstyle shape; this helper converts for
+    positional styles.
     """
-    if paramstyle == 'named':
+    if paramstyle in DICT_STYLES:
         return dict(items)
     return [v for _, v in items]
 
@@ -687,8 +706,9 @@ def test_ps_subst(paramstyle):
     assert values == _values(paramstyle, [('min_age', 30)])
 
 
-@pytest.mark.parametrize('paramstyle', PARAMSTYLES)
-def test_ps_subst_repeated_shares(paramstyle):
+@pytest.mark.parametrize('paramstyle', BACKREF_STYLES)
+def test_ps_subst_repeated_backref(paramstyle):
+    """Styles with back-reference share one slot across occurrences."""
     r = sqlize('(age >= $(x) & weight = $(x))')
     sql, values = Resolver.build(r.where, paramstyle=paramstyle, x=42)
     ph = _placeholder(paramstyle, 'x', 1)
@@ -696,6 +716,16 @@ def test_ps_subst_repeated_shares(paramstyle):
     assert values == _values(paramstyle, [('x', 42)])
 
 
+@pytest.mark.parametrize('paramstyle', ['qmark', 'format'])
+def test_ps_subst_repeated_no_backref(paramstyle):
+    """qmark/format repeat the value (no back-reference)."""
+    r = sqlize('(age >= $(x) & weight = $(x))')
+    sql, values = Resolver.build(r.where, paramstyle=paramstyle, x=42)
+    ph = _placeholder(paramstyle, 'x', 1)
+    assert sql == f'(age >= {ph}) AND (weight = {ph})'
+    assert values == [42, 42]
+
+
 @pytest.mark.parametrize('paramstyle', PARAMSTYLES)
 def test_ps_pattern_with_literal_inline(paramstyle):
     r = sqlize('data.users[*].age >= 30')
@@ -746,7 +776,7 @@ def test_ps_mixed_pattern_and_scalar(paramstyle):
 
 # ---------------- ParamStyle enum accepted ----------------
 
-@pytest.mark.parametrize('style', [ParamStyle.named, ParamStyle.dollar_numeric])
+@pytest.mark.parametrize('style', list(ParamStyle))
 def test_paramstyle_enum_member_accepted(style):
     """Enum members work interchangeably with their string values."""
     r = sqlize('age = 30')