8000 [3.11] gh-94628: Add explicit parameter list to sqlite3.connect docs … · python/cpython@3517c13 · GitHub
[go: up one dir, main page]

Skip to content

Commit 3517c13

Browse files
[3.11] gh-94628: Add explicit parameter list to sqlite3.connect docs (GH-94629) (#94645)
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 3eb2b96) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
1 parent fa44a76 commit 3517c13

File tree

1 file changed

+105
-76
lines changed

1 file changed

+105
-76
lines changed

Doc/library/sqlite3.rst

Lines changed: 105 additions & 76 deletions
F438
Original file line numberDiff line numberDiff line change
@@ -236,90 +236,89 @@ Module functions and constants
236236
(bitwise or) operator.
237237

238238

239-
.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
240-
241-
Opens a connection to the SQLite database file *database*. By default returns a
242-
:class:`Connection` object, unless a custom *factory* is given.
243-
244-
*database* is a :term:`path-like object` giving the pathname (absolute or
245-
relative to the current working directory) of the database file to be opened.
246-
You can use ``":memory:"`` to open a database connection to a database that
247-
resides in RAM instead of on disk.
248-
249-
When a database is accessed by multiple connections, and one of the processes
250-
modifies the database, the SQLite database is locked until that transaction is
251-
committed. The *timeout* parameter specifies how long the connection should wait
252-
for the lock to go away until raising an exception. The default for the timeout
253-
parameter is 5.0 (five seconds).
254-
255-
For the *isolation_level* parameter, please see the
256-
:attr:`~Connection.isolation_level` property of :class:`Connection` objects.
257-
258-
SQLite natively supports only the types TEXT, INTEGER, REAL, BLOB and NULL. If
259-
you want to use other types you must add support for them yourself. The
260-
*detect_types* parameter and using custom **converters** registered with the
261-
module-level :func:`register_converter` function allow you to easily do that.
262-
263-
*detect_types* defaults to 0 (type detection disabled).
264-
Set it to any combination (using ``|``, bitwise or) of
265-
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`
266-
to enable type detection.
267-
Column names takes precedence over declared types if both flags are set.
268-
Types cannot be detected for generated fields (for example ``max(data)``),
269-
even when the *detect_types* parameter is set.
270-
In such cases, the returned type is :class:`str`.
271-
272-
By default, *check_same_thread* is :const:`True` and only the creating thread may
273-
use the connection. If set :const:`False`, the returned connection may be shared
274-
across multiple threads. When using multiple threads with the same connection
275-
writing operations should be serialized by the user to avoid data corruption.
276-
277-
By default, the :mod:`sqlite3` module uses its :class:`Connection` class for the
278-
connect call. You can, however, subclass the :class:`Connection` class and make
279-
:func:`connect` use your class instead by providing your class for the *factory*
280-
parameter.
281-
282-
Consult the section :ref:`sqlite3-types` of this manual for details.
283-
284-
The :mod:`sqlite3` module internally uses a statement cache to avoid SQL parsing
285-
overhead. If you want to explicitly set the number of statements that are cached
286-
for the connection, you can set the *cached_statements* parameter. The currently
287-
implemented default is to cache 128 statements.
288-
289-
If *uri* is :const:`True`, *database* is interpreted as a
290-
:abbr:`URI (Uniform Resource Identifier)` with a file path and an optional
291-
query string. The scheme part *must* be ``"file:"``. The path can be a
292-
relative or absolute file path. The query string allows us to pass
293-
parameters to SQLite. Some useful URI tricks include::
294-
295-
# Open a database in read-only mode.
296-
con = sqlite3.connect("file:template.db?mode=ro", uri=True)
297-
298-
# Don't implicitly create a new database file if it does not already exist.
299-
# Will raise sqlite3.OperationalError if unable to open a database file.
300-
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
301-
302-
# Create a shared named in-memory database.
303-
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
304-
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
305-
con1.executescript("create table t(t); insert into t values(28);")
306-
rows = con2.execute("select * from t").fetchall()
307-
308-
More information about this feature, including a list of recognized
309-
parameters, can be found in the
310-
`SQLite URI documentation <https://www.sqlite.org/uri.html>`_.
239+
240+
.. function:: connect(database, timeout=5.0, detect_types=0, isolation_level="DEFERRED", check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False)
241+
242+
Open a connection to an SQLite database.
243+
244+
:param database:
245+
The path to the database file to be opened.
246+
Pass ``":memory:"`` to open a connection to a database that is
247+
in RAM instead of on disk.
248+
:type database: :term:`path-like object`
249+
250+
:param timeout:
251+
How many seconds the connection should wait before raising
252+
an exception, if the database is locked by another connection.
253+
If another connection opens a transaction to modify the database,
254+
it will be locked until that transaction is committed.
255+
Default five seconds.
256+
:type timeout: float
257+
258+
:param detect_types:
259+
Control whether and how data types not
260+
:ref:`natively supported by SQLite <sqlite3-types>`
261+
are looked up to be converted to Python types,
262+
using the converters registered with :func:`register_converter`.
263+
Set it to any combination (using ``|``, bitwise or) of
264+
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`
265+
to enable this.
266+
Column names takes precedence over declared types if both flags are set.
267+
Types cannot be detected for generated fields (for example ``max(data)``),
268+
even when the *detect_types* parameter is set; :class:`str` will be
269+
returned instead.
270+
By default (``0``), type detection is disabled.
271+
:type detect_types: int
272+
273+
:param isolation_level:
274+
The :attr:`~Connection.isolation_level` of the connection,
275+
controlling whether and how transactions are implicitly opened.
276+
Can be ``"DEFERRED"`` (default), ``"EXCLUSIVE"`` or ``"IMMEDIATE"``;
277+
or :const:`None` to disable opening transactions implicitly.
278+
See :ref:`sqlite3-controlling-transactions` for more.
279+
:type isolation_level: str | None
280+
281+
:param check_same_thread:
282+
If :const:`True` (default), only the creating thread may use the connection.
283+
If :const:`False`, the connection may be shared across multiple threads;
284+
if so, write operations should be serialized by the user to avoid data
285+
corruption.
286+
:type check_same_thread: bool
287+
288+
:param factory:
289+
A custom subclass of :class:`Connection` to create the connection with,
290+
if not the default :class:`Connection` class.
291+
:type factory: :class:`Connection`
292+
293+
:param cached_statements:
294+
The number of statements that ``sqlite3``
295+
should internally cache for this connection, to avoid parsing overhead.
296+
By default, 128 statements.
297+
:type cached_statements: int
298+
299+
:param uri:
300+
If set to :const:`True`, *database* is interpreted as a
301+
:abbr:`URI (Uniform Resource Identifier)` with a file path
302+
and an optional query string.
303+
The scheme part *must* be ``"file:"``,
304+
and the path can be relative or absolute.
305+
The query string allows passing parameters to SQLite,
306+
enabling various :ref:`sqlite3-uri-tricks`.
307+
:type uri: bool
308+
309+
:rtype: sqlite3.Connection
311310

312311
.. audit-event:: sqlite3.connect database sqlite3.connect
313312
.. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
314313

315-
.. versionchanged:: 3.4
316-
Added the *uri* parameter.
314+
.. versionadded:: 3.4
315+
The *uri* parameter.
317316

318317
.. versionchanged:: 3.7
319318
*database* can now also be a :term:`path-like object`, not only a string.
320319

321-
.. versionchanged:: 3.10
322-
Added the ``sqlite3.connect/handle`` auditing event.
320+
.. versionadded:: 3.10
321+
The ``sqlite3.connect/handle`` auditing event.
323322

324323

325324
.. function:: register_converter(typename, converter, /)
@@ -1470,6 +1469,36 @@ regardless of the value of :attr:`~Connection.isolation_level`.
14701469
https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
14711470

14721471

1472+
.. _sqlite3-uri-tricks:
1473+
1474+
SQLite URI tricks
1475+
-----------------
1476+
1477+
Some useful URI tricks include:
1478+
1479+
* Open a database in read-only mode::
1480+
1481+
con = sqlite3.connect("file:template.db?mode=ro", uri=True)
1482+
1483+
* Do not implicitly create a new database file if it does not already exist;
1484+
will raise :exc:`~sqlite3.OperationalError` if unable to create a new file::
1485+
1486+
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
1487+
1488+
* Create a shared named in-memory database::
1489+
1490+
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
1491+
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
1492+
con1.execute("create table t(t)")
1493+
con1.execute("insert into t values(28)")
1494+
con1.commit()
1495+
rows = con2.execute("select * from t").fetchall()
1496+
1497+
More information about this feature, including a list of parameters,
1498+
can be found in the `SQLite URI documentation`_.
1499+
1500+
.. _SQLite URI documentation: https://www.sqlite.org/uri.html
1501+
14731502
Using :mod:`sqlite3` efficiently
14741503
--------------------------------
14751504

0 commit comments

Comments
 (0)
0