gh-108278: Deprecate passing the three first params as keyword args for sqlite3 UDF creation APIs (#108281)

Deprecate passing name, number of arguments, and the callable as keyword
arguments, for the following sqlite3.Connection APIs:

- create_function(name, nargs, callable, ...)
- create_aggregate(name, nargs, callable)

The affected parameters will become positional-only in Python 3.15.

Doc/library/sqlite3.rst

@@ -763,6 +763,11 @@ Connection objects
          ...     print(row)
          ('acbd18db4cc2f85cedef654fccc4a4d8',)
 
+   .. versionchanged:: 3.13
+
+      Passing *name*, *narg*, and *func* as keyword arguments is deprecated.
+      These parameters will become positional-only in Python 3.15.
+
 
    .. method:: create_aggregate(name, n_arg, aggregate_class)
 
@@ -817,6 +822,11 @@ Connection objects
 
          3
 
+   .. versionchanged:: 3.13
+
+      Passing *name*, *n_arg*, and *aggregate_class* as keyword arguments is deprecated.
+      These parameters will become positional-only in Python 3.15.
+
 
    .. method:: create_window_function(name, num_params, aggregate_class, /)
 

Doc/whatsnew/3.13.rst

@@ -252,7 +252,16 @@ Deprecated
 * Passing more than one positional argument to :func:`sqlite3.connect` and the
   :class:`sqlite3.Connection` constructor is deprecated. The remaining
   parameters will become keyword-only in Python 3.15.
-  (Contributed by Erlend E. Aasland in :gh:`107948`.)
+
+  Deprecate passing name, number of arguments, and the callable as keyword
+  arguments, for the following :class:`sqlite3.Connection` APIs:
+
+  * :meth:`~sqlite3.Connection.create_function`
+  * :meth:`~sqlite3.Connection.create_aggregate`
+
+  The affected parameters will become positional-only in Python 3.15.
+
+  (Contributed by Erlend E. Aasland in :gh:`107948` and :gh:`108278`.)
 
 Pending Removal in Python 3.14
 ------------------------------

Lib/test/test_sqlite3/test_userfunctions.py

@@ -421,6 +421,29 @@ def test_func_return_illegal_value(self):
         self.assertRaisesRegex(sqlite.OperationalError, msg,
                                self.con.execute, "select badreturn()")
 
+    def test_func_keyword_args(self):
+        regex = (
+            r"Passing keyword arguments 'name', 'narg' and 'func' to "
+            r"_sqlite3.Connection.create_function\(\) is deprecated. "
+            r"Parameters 'name', 'narg' and 'func' will become "
+            r"positional-only in Python 3.15."
+        )
+
+        def noop():
+            return None
+
+        with self.assertWarnsRegex(DeprecationWarning, regex) as cm:
+            self.con.create_function("noop", 0, func=noop)
+        self.assertEqual(cm.filename, __file__)
+
+        with self.assertWarnsRegex(DeprecationWarning, regex) as cm:
+            self.con.create_function("noop", narg=0, func=noop)
+        self.assertEqual(cm.filename, __file__)
+
+        with self.assertWarnsRegex(DeprecationWarning, regex) as cm:
+            self.con.create_function(name="noop", narg=0, func=noop)
+        self.assertEqual(cm.filename, __file__)
+
 
 class WindowSumInt:
     def __init__(self):

Misc/NEWS.d/next/Library/2023-08-22-13-51-10.gh-issue-108278.11d_qG.rst

@@ -0,0 +1,9 @@
+Deprecate passing name, number of arguments, and the callable as keyword
+arguments, for the following :class:`sqlite3.Connection` APIs:
+
+* :meth:`~sqlite3.Connection.create_function`
+* :meth:`~sqlite3.Connection.create_aggregate`
+
+The affected parameters will become positional-only in Python 3.15.
+
+Patch by Erlend E. Aasland.

Modules/_sqlite/clinic/connection.c.h

@@ -418,7 +418,12 @@ PyDoc_STRVAR(pysqlite_connection_create_function__doc__,
 "create_function($self, /, name, narg, func, *, deterministic=False)\n"
 "--\n"
 "\n"
-"Creates a new function.");
+"Creates a new function.\n"
+"\n"
+"Note: Passing keyword arguments \'name\', \'narg\' and \'func\' to\n"
+"_sqlite3.Connection.create_function() is deprecated. Parameters\n"
+"\'name\', \'narg\' and \'func\' will become positional-only in Python 3.15.\n"
+"");
 
 #define PYSQLITE_CONNECTION_CREATE_FUNCTION_METHODDEF    \
     {"create_function", _PyCFunction_CAST(pysqlite_connection_create_function), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pysqlite_connection_create_function__doc__},
@@ -429,6 +434,17 @@ pysqlite_connection_create_function_impl(pysqlite_Connection *self,
                                          int narg, PyObject *func,
                                          int deterministic);
 
+// Emit compiler warnings when we get to Python 3.15.
+#if PY_VERSION_HEX >= 0x030f00C0
+#  error "Update the clinic input of '_sqlite3.Connection.create_function'."
+#elif PY_VERSION_HEX >= 0x030f00A0
+#  ifdef _MSC_VER
+#    pragma message ("Update the clinic input of '_sqlite3.Connection.create_function'.")
+#  else
+#    warning "Update the clinic input of '_sqlite3.Connection.create_function'."
+#  endif
+#endif
+
 static PyObject *
 pysqlite_connection_create_function(pysqlite_Connection *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
 {
@@ -469,6 +485,16 @@ pysqlite_connection_create_function(pysqlite_Connection *self, PyTypeObject *cls
     if (!args) {
         goto exit;
     }
+    if (nargs < 3) {
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                "Passing keyword arguments 'name', 'narg' and 'func' to "
+                "_sqlite3.Connection.create_function() is deprecated. Parameters "
+                "'name', 'narg' and 'func' will become positional-only in Python "
+                "3.15.", 1))
+        {
+            goto exit;
+        }
+    }
     if (!PyUnicode_Check(args[0])) {
         _PyArg_BadArgument("create_function", "argument 'name'", "str", args[0]);
         goto exit;
@@ -582,7 +608,13 @@ PyDoc_STRVAR(pysqlite_connection_create_aggregate__doc__,
 "create_aggregate($self, /, name, n_arg, aggregate_class)\n"
 "--\n"
 "\n"
-"Creates a new aggregate.");
+"Creates a new aggregate.\n"
+"\n"
+"Note: Passing keyword arguments \'name\', \'n_arg\' and \'aggregate_class\'\n"
+"to _sqlite3.Connection.create_aggregate() is deprecated. Parameters\n"
+"\'name\', \'n_arg\' and \'aggregate_class\' will become positional-only in\n"
+"Python 3.15.\n"
+"");
 
 #define PYSQLITE_CONNECTION_CREATE_AGGREGATE_METHODDEF    \
     {"create_aggregate", _PyCFunction_CAST(pysqlite_connection_create_aggregate), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pysqlite_connection_create_aggregate__doc__},
@@ -593,6 +625,17 @@ pysqlite_connection_create_aggregate_impl(pysqlite_Connection *self,
                                           const char *name, int n_arg,
                                           PyObject *aggregate_class);
 
+// Emit compiler warnings when we get to Python 3.15.
+#if PY_VERSION_HEX >= 0x030f00C0
+#  error "Update the clinic input of '_sqlite3.Connection.create_aggregate'."
+#elif PY_VERSION_HEX >= 0x030f00A0
+#  ifdef _MSC_VER
+#    pragma message ("Update the clinic input of '_sqlite3.Connection.create_aggregate'.")
+#  else
+#    warning "Update the clinic input of '_sqlite3.Connection.create_aggregate'."
+#  endif
+#endif
+
 static PyObject *
 pysqlite_connection_create_aggregate(pysqlite_Connection *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
 {
@@ -631,6 +674,16 @@ pysqlite_connection_create_aggregate(pysqlite_Connection *self, PyTypeObject *cl
     if (!args) {
         goto exit;
     }
+    if (nargs < 3) {
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                "Passing keyword arguments 'name', 'n_arg' and 'aggregate_class' "
+                "to _sqlite3.Connection.create_aggregate() is deprecated. "
+                "Parameters 'name', 'n_arg' and 'aggregate_class' will become "
+                "positional-only in Python 3.15.", 1))
+        {
+            goto exit;
+        }
+    }
     if (!PyUnicode_Check(args[0])) {
         _PyArg_BadArgument("create_aggregate", "argument 'name'", "str", args[0]);
         goto exit;
@@ -1681,4 +1734,4 @@ exit:
 #ifndef DESERIALIZE_METHODDEF
     #define DESERIALIZE_METHODDEF
 #endif /* !defined(DESERIALIZE_METHODDEF) */
-/*[clinic end generated code: output=bc31bec42067a8bf input=a9049054013a1b77]*/
+/*[clinic end generated code: output=f80eb1d02cf698e4 input=a9049054013a1b77]*/

Modules/_sqlite/connection.c

@@ -1139,6 +1139,7 @@ _sqlite3.Connection.create_function as pysqlite_connection_create_function
     name: str
     narg: int
     func: object
+    / [from 3.15]
     *
     deterministic: bool = False
 
@@ -1150,7 +1151,7 @@ pysqlite_connection_create_function_impl(pysqlite_Connection *self,
                                          PyTypeObject *cls, const char *name,
                                          int narg, PyObject *func,
                                          int deterministic)
-/*[clinic end generated code: output=8a811529287ad240 input=b3e8e1d8ddaffbef]*/
+/*[clinic end generated code: output=8a811529287ad240 input=c7c313b0ca8b519e]*/
 {
     int rc;
     int flags = SQLITE_UTF8;
@@ -1341,6 +1342,7 @@ _sqlite3.Connection.create_aggregate as pysqlite_connection_create_aggregate
     name: str
     n_arg: int
     aggregate_class: object
+    / [from 3.15]
 
 Creates a new aggregate.
 [clinic start generated code]*/
@@ -1350,7 +1352,7 @@ pysqlite_connection_create_aggregate_impl(pysqlite_Connection *self,
                                           PyTypeObject *cls,
                                           const char *name, int n_arg,
                                           PyObject *aggregate_class)
-/*[clinic end generated code: output=1b02d0f0aec7ff96 input=68a2a26366d4c686]*/
+/*[clinic end generated code: output=1b02d0f0aec7ff96 input=8087056db6eae1cf]*/
 {
     int rc;