crate 2.2.0__tar.gz → 2.2.1__tar.gz

{crate-2.2.0 → crate-2.2.1}/CHANGES.rst

@@ -2,6 +2,14 @@
 Changes for crate
 =================
 
+2026/06/17 2.2.1
+================
+
+- Fixed ``cursor.execute()`` with ``bulk_parameters`` and pyformat SQL: when
+  rows are dicts, both the SQL template and the rows are now converted to
+  positional format before sending to CrateDB. Positional-list rows
+  continue to work as before.
+
 2026/06/04 2.2.0
 ==========
 - Added JSON serialization support for Python's ``datetime.time`` type,

{crate-2.2.0 → crate-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crate
-Version: 2.2.0
+Version: 2.2.1
 Summary: CrateDB Python Client
 Author-email: "Crate.io" <office@crate.io>
 License-Expression: Apache-2.0

{crate-2.2.0 → crate-2.2.1}/docs/by-example/cursor.rst

@@ -266,6 +266,37 @@ For completeness' sake the cursor description is updated nonetheless:
     >>> [ desc[0] for desc in cursor.description ]
     ['name', 'position']
 
+executemany() with named parameters
+====================================
+
+``executemany()`` also accepts a :class:`py:list` of :class:`py:dict` when
+the SQL statement contains ``%(name)s`` placeholders. The client converts both the SQL
+template and all rows to positional format before sending them to CrateDB:
+
+.. Hidden: set up mocked response
+
+    >>> connection.client.set_next_response({
+    ...     "results": [
+    ...         {"rowcount": 1},
+    ...         {"rowcount": 1}
+    ...     ],
+    ...     "duration": 123,
+    ...     "cols": [],
+    ... })
+
+    >>> cursor = connection.cursor()
+
+    >>> cursor.executemany(
+    ...     "INSERT INTO t (id, val) VALUES (%(id)s, %(val)s)",
+    ...     [{"id": 1, "val": "foo"}, {"id": 2, "val": "bar"}])
+    [{'rowcount': 1}, {'rowcount': 1}]
+
+    >>> cursor.rowcount
+    2
+
+    >>> cursor.duration
+    123
+
     >>> connection.client.set_next_response({
     ...     "rows":[ [ "North West Ripple", 1 ], [ "Arkintoofle Minor", 3 ], [ "Alpha Centauri", 3 ] ],
     ...     "cols":[ "name", "position" ],

{crate-2.2.0 → crate-2.2.1}/docs/query.rst

@@ -72,20 +72,19 @@ The same parameter name may appear multiple times in the query:
     ...     "SELECT * FROM locations WHERE name = %(q)s OR kind = %(q)s",
     ...     {"q": "Quasar"})
 
-The client converts the ``%(name)s`` placeholders to positional ``?`` markers
-before sending the query to CrateDB, so no server-side changes are required.
-
-.. NOTE::
-
-    Named parameters are not yet supported by ``executemany()``. Use
-    positional ``?`` placeholders with a :class:`py:list` of tuples for bulk
-    operations.
+The client converts the ``%(name)s`` placeholders to ``$N`` positional
+markers before sending the query to CrateDB.
 
 Bulk inserts
 ------------
 
 :ref:`Bulk inserts <crate-reference:http-bulk-ops>` are possible with the
-``executemany()`` method, which takes a :class:`py:list` of tuples to insert:
+``executemany()`` method.
+
+Positional parameters
+.....................
+
+Pass a :class:`py:list` of sequences using ``?`` placeholders:
 
     >>> cursor.executemany(
     ...     "INSERT INTO locations (name, date, kind, position) VALUES (?, ?, ?, ?)",
@@ -94,10 +93,58 @@ Bulk inserts
     [{'rowcount': 1}, {'rowcount': 1}]
 
 The ``executemany()`` method returns a result :class:`dictionary <py:dict>`
-for every tuple. This dictionary always has a ``rowcount`` key, indicating
+for every row. This dictionary always has a ``rowcount`` key, indicating
 how many rows were inserted. If an error occurs, the ``rowcount`` value is
 ``-2``, and the dictionary may additionally have an ``error_message`` key.
 
+Named parameters
+................
+
+``executemany()`` also accepts a :class:`py:list` of :class:`py:dict` using
+``%(name)s`` placeholders. The client converts both the SQL template and all
+rows to positional format before sending to CrateDB:
+
+    >>> cursor.executemany(
+    ...     "INSERT INTO locations (name, date, kind, position) "
+    ...     "VALUES (%(name)s, %(date)s, %(kind)s, %(pos)s)",
+    ...     [{"name": "Cloverleaf", "date": "2007-03-11", "kind": "Quasar", "pos": 7},
+    ...      {"name": "Old Faithful", "date": "2007-03-11", "kind": "Quasar", "pos": 8}])
+    [{'rowcount': 1}, {'rowcount': 1}]
+
+Using ``bulk_parameters`` directly
+...................................
+
+``execute()``  accepts a ``bulk_parameters`` keyword argument directly:
+
+.. NOTE::
+    Please prefer ``executemany()`` for bulk inserts, it is the standard DB-API 2.0
+    interface. The ``bulk_parameters`` argument is a lower-level alternative.
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) VALUES (?, ?, ?)",
+    ...     bulk_parameters=[('Cloverleaf', 'Quasar', 7),
+    ...                      ('Old Faithful', 'Quasar', 8)])
+
+Named ``%(name)s`` placeholders are also supported. When the rows are
+:class:`py:dict` objects the SQL template and rows are fully converted,
+identical to the ``executemany()`` path:
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) "
+    ...     "VALUES (%(name)s, %(kind)s, %(pos)s)",
+    ...     bulk_parameters=[{"name": "Cloverleaf", "kind": "Quasar", "pos": 7},
+    ...                      {"name": "Old Faithful", "kind": "Quasar", "pos": 8}])
+
+When the rows are already positional lists (e.g. data coming from a
+DataFrame), only the SQL template is rewritten. In this case the caller must
+ensure the value order in each row matches the placeholder order in the SQL:
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) "
+    ...     "VALUES (%(name)s, %(kind)s, %(pos)s)",
+    ...     bulk_parameters=[['Cloverleaf', 'Quasar', 7],
+    ...                      ['Old Faithful', 'Quasar', 8]])
+
 .. _selects:
 
 Selecting data

{crate-2.2.0 → crate-2.2.1}/tests/client/test_cursor.py

@@ -125,6 +125,94 @@ def test_cursor_executemany(mocked_connection):
         assert response["results"] == result
 
 
+def test_executemany_with_named_params(mocked_connection):
+    """
+    Verify that executemany() translates pyformat %(name)s placeholders to
+    positional $N markers and converts each dict row to a positional list.
+
+    """
+    response = {
+        "col_types": [],
+        "cols": [],
+        "duration": 123,
+        "results": [{"rowcount": 1}, {"rowcount": 1}],
+    }
+    with mock.patch.object(
+        mocked_connection.client, "sql", return_value=response
+    ):
+        cursor = mocked_connection.cursor()
+        cursor.executemany(
+            "INSERT INTO characters (name, age) VALUES (%(name)s, %(age)s)",
+            [
+                {"name": "Arthur", "age": 42},
+                {"name": "Bill", "age": 35},
+            ],
+        )
+        sql, _params, bulk_args = mocked_connection.client.sql.call_args[0]
+        assert sql == "INSERT INTO characters (name, age) VALUES ($1, $2)"
+        assert bulk_args == [["Arthur", 42], ["Bill", 35]]
+
+
+def test_executemany_with_named_params_missing_key(mocked_connection):
+    """
+    Verify that executemany() raises ProgrammingError when a row is missing a
+    key that appears as a placeholder in the SQL.
+    """
+    cursor = mocked_connection.cursor()
+    with pytest.raises(
+        ProgrammingError, match="Named parameter 'age' not found"
+    ):
+        cursor.executemany(
+            "INSERT INTO characters (name, age) VALUES (%(name)s, %(age)s)",
+            [
+                {"name": "Arthur", "age": 42},
+                {"name": "Bill"},  # missing 'age'
+            ],
+        )
+    mocked_connection.client.sql.assert_not_called()
+
+
+def test_executemany_with_named_params_repeated(mocked_connection):
+    """
+    Verify that a placeholder name used multiple times in the SQL maps to the
+    same $N position in every occurrence, and the value appears only once in
+    each row's positional list.
+    """
+    response = {
+        "col_types": [],
+        "cols": [],
+        "duration": 123,
+        "results": [{"rowcount": 1}, {"rowcount": 1}],
+    }
+    with mock.patch.object(
+        mocked_connection.client, "sql", return_value=response
+    ):
+        cursor = mocked_connection.cursor()
+        cursor.executemany(
+            "INSERT INTO t (a, b) VALUES (%(x)s, %(x)s)",
+            [{"x": 1}, {"x": 2}],
+        )
+        sql, _params, bulk_args = mocked_connection.client.sql.call_args[0]
+        assert sql == "INSERT INTO t (a, b) VALUES ($1, $1)"
+        assert bulk_args == [[1], [2]]
+
+
+def test_executemany_with_mixed_param_types(mocked_connection):
+    """
+    Verify that executemany() raises a clear ProgrammingError when the
+    parameter sequence mixes dicts and non-dicts while the SQL uses pyformat.
+    """
+    cursor = mocked_connection.cursor()
+    with pytest.raises(
+        ProgrammingError, match="All bulk parameter rows must be dicts"
+    ):
+        cursor.executemany(
+            "INSERT INTO characters (name) VALUES (%(name)s)",
+            [{"name": "Arthur"}, ["Trillian"]],  # second row is a list
+        )
+    mocked_connection.client.sql.assert_not_called()
+
+
 def test_create_with_timezone_as_datetime_object(mocked_connection):
     """
     The cursor can return timezone-aware `datetime` objects when requested.
@@ -243,6 +331,68 @@ def test_execute_with_bulk_args(mocked_connection):
     mocked_connection.client.sql.assert_called_once_with(statement, None, [[1]])
 
 
+def test_execute_with_pyformat_sql_and_bulk_parameters(mocked_connection):
+    """
+    cursor.execute() converts %(name)s SQL to $N when bulk_parameters is
+    provided. Rows are already positional; only the SQL needs conversion.
+    """
+    cursor = mocked_connection.cursor()
+    sql = "INSERT INTO t (id, val) VALUES (%(id)s, %(val)s)"
+    bulk = [[1, "hello"], [2, "world"]]
+    cursor.execute(sql, bulk_parameters=bulk)
+    mocked_connection.client.sql.assert_called_once_with(
+        "INSERT INTO t (id, val) VALUES ($1, $2)", None, bulk
+    )
+
+
+def test_execute_with_pyformat_sql_and_dict_bulk_parameters(mocked_connection):
+    """
+    cursor.execute() with pyformat SQL and dict-format bulk_parameters converts
+    both the SQL template (%(x)s → $N) and the rows (dicts → positional lists).
+    """
+    cursor = mocked_connection.cursor()
+    sql = "INSERT INTO t (id, val) VALUES (%(id)s, %(val)s)"
+    bulk = [{"id": 1, "val": "hello"}, {"id": 2, "val": "world"}]
+    cursor.execute(sql, bulk_parameters=bulk)
+    mocked_connection.client.sql.assert_called_once_with(
+        "INSERT INTO t (id, val) VALUES ($1, $2)",
+        None,
+        [[1, "hello"], [2, "world"]],
+    )
+
+
+def test_execute_with_dict_bulk_parameters_mixed_types_raises(
+    mocked_connection,
+):
+    """
+    cursor.execute() raises ProgrammingError when bulk_parameters mixes
+    dict and non-dict rows with pyformat SQL.
+    """
+    cursor = mocked_connection.cursor()
+    with pytest.raises(
+        ProgrammingError, match="All bulk parameter rows must be dicts"
+    ):
+        cursor.execute(
+            "INSERT INTO t (id) VALUES (%(id)s)",
+            bulk_parameters=[{"id": 1}, [2]],
+        )
+    mocked_connection.client.sql.assert_not_called()
+
+
+def test_execute_with_pyformat_sql_and_bulk_parameters_no_placeholders(
+    mocked_connection,
+):
+    """
+    SQL without %(name)s placeholders is passed through unchanged
+    even when bulk_parameters is provided.
+    """
+    cursor = mocked_connection.cursor()
+    sql = "INSERT INTO t (id, val) VALUES (?, ?)"
+    bulk = [[1, "hello"], [2, "world"]]
+    cursor.execute(sql, bulk_parameters=bulk)
+    mocked_connection.client.sql.assert_called_once_with(sql, None, bulk)
+
+
 def test_execute_custom_converter(mocked_connection):
     """
     Verify that a custom converter is correctly applied when passed to a cursor.
@@ -565,6 +715,24 @@ def test_execute_with_named_params_missing(mocked_connection):
     mocked_connection.client.sql.assert_not_called()
 
 
+def test_execute_with_named_params_non_identifier_keys(mocked_connection):
+    """
+    Verify that %(name)s placeholders whose name contains characters outside
+    [a-zA-Z0-9_] are still converted to positional $N markers.
+
+    """
+    cursor = mocked_connection.cursor()
+
+    cursor.execute(
+        "UPDATE characters SET data['x'] = %(data['x'])s WHERE name = %(name)s",
+        {"data['x']": 42, "name": "Berlin"},
+    )
+    sql, args, _ = mocked_connection.client.sql.call_args[0]
+    assert "%" not in sql
+    assert sql == "UPDATE characters SET data['x'] = $1 WHERE name = $2"
+    assert args == [42, "Berlin"]
+
+
 def test_cursor_close(mocked_connection):
     """
     Verify that a cursor is not closed if not specifically closed.