Skip to content

gh-133595: Clean up sqlite3.Connection APIs #133605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
May 8, 2025
Merged

gh-133595: Clean up sqlite3.Connection APIs #133605

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d60e936
gh-133595: Clean up sqlite3.Connection APIs
serhiy-storchaka May 7, 2025
4e52335
Updated also What's New.
serhiy-storchaka May 7, 2025
685f534
Merge upstream test fixes
zware May 7, 2025
cde32c2
Revert upstream warningignore additions
zware May 7, 2025
37957a0
Fix the remaining warning.
serhiy-storchaka May 7, 2025
cff53e3
Add the issue reference.
serhiy-storchaka May 7, 2025
176bf94
Regen global objects.
serhiy-storchaka May 8, 2025
162abc1
Merge branch 'main' into sqlite3-api-end-deprecation
serhiy-storchaka May 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 21 additions & 31 deletions Doc/library/sqlite3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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.

Expand All @@ -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::
Expand All @@ -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.

Expand All @@ -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::
Expand Down Expand Up @@ -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, /)

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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, /)
Expand Down
11 changes: 10 additions & 1 deletion Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-----------------
Expand Down
6 changes: 0 additions & 6 deletions Include/internal/pycore_global_objects_fini_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 0 additions & 6 deletions Include/internal/pycore_global_strings.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand 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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
6 changes: 0 additions & 6 deletions Include/internal/pycore_runtime_init_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 0 additions & 24 deletions Include/internal/pycore_unicodeobject_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 3 additions & 11 deletions Lib/test/test_sqlite3/test_dbapi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
Loading
Loading