diff options
Diffstat (limited to 'Doc/library/sqlite3.rst')
| -rw-r--r-- | Doc/library/sqlite3.rst | 83 |
1 files changed, 41 insertions, 42 deletions
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index c615650b622..641e1f1de03 100644 --- a/Doc/library/sqlite3.rst +++ b/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) @@ -510,6 +507,15 @@ Module constants Version number of the runtime SQLite library as a :class:`tuple` of :class:`integers <int>`. +.. data:: SQLITE_KEYWORDS + + A :class:`tuple` containing all sqlite3 keywords. + + This constant is only available if Python was compiled with SQLite + 3.24.0 or greater. + + .. versionadded:: next + .. data:: threadsafety Integer constant required by the DB-API 2.0, stating the level of thread @@ -693,7 +699,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 +725,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 +742,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 +767,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 +799,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 +939,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 +964,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 +982,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 +1009,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, /) @@ -1492,7 +1491,9 @@ Cursor objects :type parameters: :class:`dict` | :term:`sequence` :raises ProgrammingError: - If *sql* contains more than one SQL statement. + When *sql* contains more than one SQL statement. + When :ref:`named placeholders <sqlite3-placeholders>` are used + and *parameters* is a sequence instead of a :class:`dict`. If :attr:`~Connection.autocommit` is :data:`LEGACY_TRANSACTION_CONTROL`, @@ -1501,13 +1502,11 @@ Cursor objects and there is no open transaction, a transaction is implicitly opened before executing *sql*. - .. deprecated-removed:: 3.12 3.14 + .. versionchanged:: 3.14 - :exc:`DeprecationWarning` is emitted if + :exc:`ProgrammingError` is emitted if :ref:`named placeholders <sqlite3-placeholders>` are used and *parameters* is a sequence instead of a :class:`dict`. - Starting with Python 3.14, :exc:`ProgrammingError` will - be raised instead. Use :meth:`executescript` to execute multiple SQL statements. @@ -1529,8 +1528,10 @@ Cursor objects :type parameters: :term:`iterable` :raises ProgrammingError: - If *sql* contains more than one SQL statement, - or is not a DML statement. + When *sql* contains more than one SQL statement + or is not a DML statement, + When :ref:`named placeholders <sqlite3-placeholders>` are used + and the items in *parameters* are sequences instead of :class:`dict`\s. Example: @@ -1554,14 +1555,12 @@ Cursor objects .. _RETURNING clauses: https://www.sqlite.org/lang_returning.html - .. deprecated-removed:: 3.12 3.14 + .. versionchanged:: 3.14 - :exc:`DeprecationWarning` is emitted if + :exc:`ProgrammingError` is emitted if :ref:`named placeholders <sqlite3-placeholders>` are used and the items in *parameters* are sequences instead of :class:`dict`\s. - Starting with Python 3.14, :exc:`ProgrammingError` will - be raised instead. .. method:: executescript(sql_script, /) |