gh-133595: Clean up sqlite3.Connection APIs (GH-133605)

* All parameters of sqlite3.connect() except "database" are now keyword-only.
* The first three parameters of methods create_function() and
  create_aggregate() are now positional-only.
* The first parameter of methods set_authorizer(), set_progress_handler()
  and set_trace_callback() is now positional-only.

Author: serhiy-storchaka

Doc/library/sqlite3.rst

@@ -259,10 +259,10 @@ Reference
 Module functions
 ^^^^^^^^^^^^^^^^
 
-.. function:: connect(database, timeout=5.0, detect_types=0, \
+.. function:: connect(database, *, timeout=5.0, detect_types=0, \
                       isolation_level="DEFERRED", check_same_thread=True, \
                       factory=sqlite3.Connection, cached_statements=128, \
-                      uri=False, *, \
+                      uri=False, \
                       autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)
 
    Open a connection to an SQLite database.
@@ -355,11 +355,8 @@ Module functions
    .. versionchanged:: 3.12
       Added the *autocommit* parameter.
 
-   .. versionchanged:: 3.13
-      Positional use of the parameters *timeout*, *detect_types*,
-      *isolation_level*, *check_same_thread*, *factory*, *cached_statements*,
-      and *uri* is deprecated.
-      They will become keyword-only parameters in Python 3.15.
+   .. versionchanged:: 3.15
+      All parameters except *database* are now keyword-only.
 
 .. function:: complete_statement(statement)
 
@@ -693,7 +690,7 @@ Connection objects
       :meth:`~Cursor.executescript` on it with the given *sql_script*.
       Return the new cursor object.
 
-   .. method:: create_function(name, narg, func, *, deterministic=False)
+   .. method:: create_function(name, narg, func, /, *, deterministic=False)
 
       Create or remove a user-defined SQL function.
 
@@ -719,6 +716,9 @@ Connection objects
       .. versionchanged:: 3.8
          Added the *deterministic* parameter.
 
+      .. versionchanged:: 3.15
+         The first three parameters are now positional-only.
+
       Example:
 
       .. doctest::
@@ -733,13 +733,8 @@ Connection objects
          ('acbd18db4cc2f85cedef654fccc4a4d8',)
          >>> con.close()
 
-      .. 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)
+   .. method:: create_aggregate(name, n_arg, aggregate_class, /)
 
       Create or remove a user-defined SQL aggregate function.
 
@@ -763,6 +758,9 @@ Connection objects
           Set to ``None`` to remove an existing SQL aggregate function.
       :type aggregate_class: :term:`class` | None
 
+      .. versionchanged:: 3.15
+         All three parameters are now positional-only.
+
       Example:
 
       .. testcode::
@@ -792,11 +790,6 @@ 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, /)
 
@@ -937,7 +930,7 @@ Connection objects
       Aborted queries will raise an :exc:`OperationalError`.
 
 
-   .. method:: set_authorizer(authorizer_callback)
+   .. method:: set_authorizer(authorizer_callback, /)
 
       Register :term:`callable` *authorizer_callback* to be invoked
       for each attempt to access a column of a table in the database.
@@ -962,12 +955,11 @@ Connection objects
       .. versionchanged:: 3.11
          Added support for disabling the authorizer using ``None``.
 
-      .. versionchanged:: 3.13
-         Passing *authorizer_callback* as a keyword argument is deprecated.
-         The parameter will become positional-only in Python 3.15.
+      .. versionchanged:: 3.15
+         The only parameter is now positional-only.
 
 
-   .. method:: set_progress_handler(progress_handler, n)
+   .. method:: set_progress_handler(progress_handler, /, n)
 
       Register :term:`callable` *progress_handler* to be invoked for every *n*
       instructions of the SQLite virtual machine. This is useful if you want to
@@ -981,12 +973,11 @@ Connection objects
       currently executing query and cause it to raise a :exc:`DatabaseError`
       exception.
 
-      .. versionchanged:: 3.13
-         Passing *progress_handler* as a keyword argument is deprecated.
-         The parameter will become positional-only in Python 3.15.
+      .. versionchanged:: 3.15
+         The first parameter is now positional-only.
 
 
-   .. method:: set_trace_callback(trace_callback)
+   .. method:: set_trace_callback(trace_callback, /)
 
       Register :term:`callable` *trace_callback* to be invoked
       for each SQL statement that is actually executed by the SQLite backend.
@@ -1009,9 +1000,8 @@ Connection objects
 
       .. versionadded:: 3.3
 
-      .. versionchanged:: 3.13
-         Passing *trace_callback* as a keyword argument is deprecated.
-         The parameter will become positional-only in Python 3.15.
+      .. versionchanged:: 3.15
+         The first parameter is now positional-only.
 
 
    .. method:: enable_load_extension(enabled, /)

Doc/whatsnew/3.15.rst

@@ -143,7 +143,16 @@ New features
 Porting to Python 3.15
 ----------------------
 
-* TODO
+* :class:`sqlite3.Connection` APIs has been cleaned up.
+
+  * All parameters of :func:`sqlite3.connect` except *database* are now keyword-only.
+  * The first three parameters of methods :meth:`~sqlite3.Connection.create_function`
+    and :meth:`~sqlite3.Connection.create_aggregate` are now positional-only.
+  * The first parameter of methods :meth:`~sqlite3.Connection.set_authorizer`,
+    :meth:`~sqlite3.Connection.set_progress_handler` and
+    :meth:`~sqlite3.Connection.set_trace_callback` is now positional-only.
+
+  (Contributed by Serhiy Storchaka in :gh:`133595`.)
 
 Deprecated C APIs
 -----------------

Include/internal/pycore_global_objects_fini_generated.h

@@ -283,7 +283,6 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(add_done_callback)
         STRUCT_FOR_ID(after_in_child)
         STRUCT_FOR_ID(after_in_parent)
-        STRUCT_FOR_ID(aggregate_class)
         STRUCT_FOR_ID(alias)
         STRUCT_FOR_ID(align)
         STRUCT_FOR_ID(all)
@@ -300,7 +299,6 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(ast)
         STRUCT_FOR_ID(athrow)
         STRUCT_FOR_ID(attribute)
-        STRUCT_FOR_ID(authorizer_callback)
         STRUCT_FOR_ID(autocommit)
         STRUCT_FOR_ID(backtick)
         STRUCT_FOR_ID(base)
@@ -599,15 +597,13 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(msg)
         STRUCT_FOR_ID(mutex)
         STRUCT_FOR_ID(mycmp)
-        STRUCT_FOR_ID(n_arg)
         STRUCT_FOR_ID(n_fields)
         STRUCT_FOR_ID(n_sequence_fields)
         STRUCT_FOR_ID(n_unnamed_fields)
         STRUCT_FOR_ID(name)
         STRUCT_FOR_ID(name_from)
         STRUCT_FOR_ID(namespace_separator)
         STRUCT_FOR_ID(namespaces)
-        STRUCT_FOR_ID(narg)
         STRUCT_FOR_ID(ndigits)
         STRUCT_FOR_ID(nested)
         STRUCT_FOR_ID(new_file_name)
@@ -665,7 +661,6 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(print_file_and_line)
         STRUCT_FOR_ID(priority)
         STRUCT_FOR_ID(progress)
-        STRUCT_FOR_ID(progress_handler)
         STRUCT_FOR_ID(progress_routine)
         STRUCT_FOR_ID(proto)
         STRUCT_FOR_ID(protocol)
@@ -771,7 +766,6 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(timetuple)
         STRUCT_FOR_ID(timeunit)
         STRUCT_FOR_ID(top)
-        STRUCT_FOR_ID(trace_callback)
         STRUCT_FOR_ID(traceback)
         STRUCT_FOR_ID(trailers)
         STRUCT_FOR_ID(translate)

Include/internal/pycore_global_strings.h

@@ -550,17 +550,9 @@ def test_connection_config(self):
                 cx.execute("insert into u values(0)")
 
     def test_connect_positional_arguments(self):
-        regex = (
-            r"Passing more than 1 positional argument to sqlite3.connect\(\)"
-            " is deprecated. Parameters 'timeout', 'detect_types', "
-            "'isolation_level', 'check_same_thread', 'factory', "
-            "'cached_statements' and 'uri' will become keyword-only "
-            "parameters in Python 3.15."
-        )
-        with self.assertWarnsRegex(DeprecationWarning, regex) as cm:
-            cx = sqlite.connect(":memory:", 1.0)
-            cx.close()
-        self.assertEqual(cm.filename, __file__)
+        with self.assertRaisesRegex(TypeError,
+                r'connect\(\) takes at most 1 positional arguments'):
+            sqlite.connect(":memory:", 1.0)
 
     def test_connection_resource_warning(self):
         with self.assertWarns(ResourceWarning):