mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-23 10:16:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

[3.10] gh-94628: Add explicit parameter list to sqlite3.connect docs (GH-94629) (#94646)

Browse source 
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 3eb2b9634f)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
This commit is contained in:
Erlend Egeberg Aasland 2022-07-07 10:46:29 +02:00 • committed by GitHub
parent 7f45ae859a
commit 663aa6e7d9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 94 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

159
Doc/library/sqlite3.rst
View file

@ -218,90 +218,89 @@ Module functions and constants
(bitwise or) operator. (bitwise or) operator.
.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
Opens a connection to the SQLite database file *database*. By default returns a .. function:: connect(database, timeout=5.0, detect_types=0, isolation_level="DEFERRED", check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False)
:class:`Connection` object, unless a custom *factory* is given.
*database* is a :term:`path-like object` giving the pathname (absolute or Open a connection to an SQLite database.
relative to the current working directory) of the database file to be opened.
You can use ``":memory:"`` to open a database connection to a database that
resides in RAM instead of on disk.
When a database is accessed by multiple connections, and one of the processes :param database:
modifies the database, the SQLite database is locked until that transaction is The path to the database file to be opened.
committed. The *timeout* parameter specifies how long the connection should wait Pass ``":memory:"`` to open a connection to a database that is
for the lock to go away until raising an exception. The default for the timeout in RAM instead of on disk.
parameter is 5.0 (five seconds). :type database: :term:`path-like object`
For the *isolation_level* parameter, please see the :param timeout:
:attr:`~Connection.isolation_level` property of :class:`Connection` objects. How many seconds the connection should wait before raising
an exception, if the database is locked by another connection.
If another connection opens a transaction to modify the database,
it will be locked until that transaction is committed.
Default five seconds.
:type timeout: float
SQLite natively supports only the types TEXT, INTEGER, REAL, BLOB and NULL. If :param detect_types:
you want to use other types you must add support for them yourself. The Control whether and how data types not
*detect_types* parameter and using custom **converters** registered with the :ref:`natively supported by SQLite <sqlite3-types>`
module-level :func:`register_converter` function allow you to easily do that. are looked up to be converted to Python types,
using the converters registered with :func:`register_converter`.
Set it to any combination (using ``|``, bitwise or) of
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`
to enable this.
Column names takes precedence over declared types if both flags are set.
Types cannot be detected for generated fields (for example ``max(data)``),
even when the *detect_types* parameter is set; :class:`str` will be
returned instead.
By default (``0``), type detection is disabled.
:type detect_types: int
*detect_types* defaults to 0 (type detection disabled). :param isolation_level:
Set it to any combination (using ``|``, bitwise or) of The :attr:`~Connection.isolation_level` of the connection,
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` controlling whether and how transactions are implicitly opened.
to enable type detection. Can be ``"DEFERRED"`` (default), ``"EXCLUSIVE"`` or ``"IMMEDIATE"``;
Column names takes precedence over declared types if both flags are set. or :const:`None` to disable opening transactions implicitly.
Types cannot be detected for generated fields (for example ``max(data)``), See :ref:`sqlite3-controlling-transactions` for more.
even when the *detect_types* parameter is set. :type isolation_level: str | None
In such cases, the returned type is :class:`str`.
By default, *check_same_thread* is :const:`True` and only the creating thread may :param check_same_thread:
use the connection. If set :const:`False`, the returned connection may be shared If :const:`True` (default), only the creating thread may use the connection.
across multiple threads. When using multiple threads with the same connection If :const:`False`, the connection may be shared across multiple threads;
writing operations should be serialized by the user to avoid data corruption. if so, write operations should be serialized by the user to avoid data
corruption.
:type check_same_thread: bool
By default, the :mod:`sqlite3` module uses its :class:`Connection` class for the :param factory:
connect call. You can, however, subclass the :class:`Connection` class and make A custom subclass of :class:`Connection` to create the connection with,
:func:`connect` use your class instead by providing your class for the *factory* if not the default :class:`Connection` class.
parameter. :type factory: :class:`Connection`
Consult the section :ref:`sqlite3-types` of this manual for details. :param cached_statements:
The number of statements that ``sqlite3``
should internally cache for this connection, to avoid parsing overhead.
By default, 100 statements.
:type cached_statements: int
The :mod:`sqlite3` module internally uses a statement cache to avoid SQL parsing :param uri:
overhead. If you want to explicitly set the number of statements that are cached If set to :const:`True`, *database* is interpreted as a
for the connection, you can set the *cached_statements* parameter. The currently :abbr:`URI (Uniform Resource Identifier)` with a file path
implemented default is to cache 100 statements. and an optional query string.
The scheme part *must* be ``"file:"``,
and the path can be relative or absolute.
The query string allows passing parameters to SQLite,
enabling various :ref:`sqlite3-uri-tricks`.
:type uri: bool
If *uri* is :const:`True`, *database* is interpreted as a :rtype: sqlite3.Connection
:abbr:`URI (Uniform Resource Identifier)` with a file path and an optional
query string. The scheme part *must* be ``"file:"``. The path can be a
relative or absolute file path. The query string allows us to pass
parameters to SQLite. Some useful URI tricks include::
# Open a database in read-only mode.
con = sqlite3.connect("file:template.db?mode=ro", uri=True)
# Don't implicitly create a new database file if it does not already exist.
# Will raise sqlite3.OperationalError if unable to open a database file.
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
# Create a shared named in-memory database.
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con1.executescript("create table t(t); insert into t values(28);")
rows = con2.execute("select * from t").fetchall()
More information about this feature, including a list of recognized
parameters, can be found in the
`SQLite URI documentation <https://www.sqlite.org/uri.html>`_.
.. audit-event:: sqlite3.connect database sqlite3.connect .. audit-event:: sqlite3.connect database sqlite3.connect
.. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect .. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
.. versionchanged:: 3.4 .. versionadded:: 3.4
Added the *uri* parameter. The *uri* parameter.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
*database* can now also be a :term:`path-like object`, not only a string. *database* can now also be a :term:`path-like object`, not only a string.
.. versionchanged:: 3.10 .. versionadded:: 3.10
Added the ``sqlite3.connect/handle`` auditing event. The ``sqlite3.connect/handle`` auditing event.
.. function:: register_converter(typename, converter, /) .. function:: register_converter(typename, converter, /)
@ -1238,6 +1237,36 @@ regardless of the value of :attr:`~Connection.isolation_level`.
https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
.. _sqlite3-uri-tricks:
SQLite URI tricks
-----------------
Some useful URI tricks include:
* Open a database in read-only mode::
con = sqlite3.connect("file:template.db?mode=ro", uri=True)
* Do not implicitly create a new database file if it does not already exist;
will raise :exc:`~sqlite3.OperationalError` if unable to create a new file::
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
* Create a shared named in-memory database::
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con1.execute("create table t(t)")
con1.execute("insert into t values(28)")
con1.commit()
rows = con2.execute("select * from t").fetchall()
More information about this feature, including a list of parameters,
can be found in the `SQLite URI documentation`_.
.. _SQLite URI documentation: https://www.sqlite.org/uri.html
Using :mod:`sqlite3` efficiently Using :mod:`sqlite3` efficiently
-------------------------------- --------------------------------