@@ -236,90 +236,89 @@ Module functions and constants
236
236
(bitwise or) operator.
237
237
238
238
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
+
F438
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
311
310
312
311
.. audit-event :: sqlite3.connect database sqlite3.connect
313
312
.. audit-event :: sqlite3.connect/handle connection_handle sqlite3.connect
314
313
315
- .. versionchanged :: 3.4
316
- Added the *uri * parameter.
314
+ .. versionadded :: 3.4
315
+ The *uri * parameter.
317
316
318
317
.. versionchanged :: 3.7
319
318
*database * can now also be a :term: `path-like object `, not only a string.
320
319
321
- .. versionchanged :: 3.10
322
- Added the ``sqlite3.connect/handle `` auditing event.
320
+ .. versionadded :: 3.10
321
+ The ``sqlite3.connect/handle `` auditing event.
323
322
324
323
325
324
.. function :: register_converter(typename, converter, /)
@@ -1470,6 +1469,36 @@ regardless of the value of :attr:`~Connection.isolation_level`.
1470
1469
https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
1471
1470
1472
1471
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
+
1473
1502
Using :mod: `sqlite3 ` efficiently
1474
1503
--------------------------------
1475
1504
0 commit comments