Skip to content

Commit d7a6a97

Browse files
erlend-aaslanderlend-aasland
authored
[3.11] gh-95273: Reorganize sqlite3 doc module level funcs and vars (GH-95626) (#95801)
Co-authored-by: Ezio Melotti <[email protected]> Co-authored-by: CAM Gerlach <[email protected]>. (cherry picked from commit 41c939c) Co-authored-by: Erlend E. Aasland <[email protected]>
1 parent 514ec82 commit d7a6a97

File tree

1 file changed

+146
-148
lines changed

1 file changed

+146
-148
lines changed

‎Doc/library/sqlite3.rst‎

Lines changed: 146 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -132,132 +132,18 @@ You've now created an SQLite database using the :mod:`!sqlite3` module.
132132
Reference
133133
---------
134134

135+
.. We keep the old sqlite3-module-contents ref to prevent breaking links.
135136
.. _sqlite3-module-contents:
136137

137-
Module functions and constants
138-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
138+
.. _sqlite3-module-functions:
139139

140+
Module functions
141+
^^^^^^^^^^^^^^^^
140142

141-
.. data:: apilevel
142-
143-
String constant stating the supported DB-API level. Required by the DB-API.
144-
Hard-coded to ``"2.0"``.
145-
146-
.. data:: paramstyle
147-
148-
String constant stating the type of parameter marker formatting expected by
149-
the :mod:`!sqlite3` module. Required by the DB-API. Hard-coded to
150-
``"qmark"``.
151-
152-
.. note::
153-
154-
The :mod:`!sqlite3` module supports both ``qmark`` and ``numeric`` DB-API
155-
parameter styles, because that is what the underlying SQLite library
156-
supports. However, the DB-API does not allow multiple values for
157-
the ``paramstyle`` attribute.
158-
159-
.. data:: version
160-
161-
Version number of this module as a :class:`string <str>`.
162-
This is not the version of the SQLite library.
163-
164-
165-
.. data:: version_info
166-
167-
Version number of this module as a :class:`tuple` of :class:`integers <int>`.
168-
This is not the version of the SQLite library.
169-
170-
171-
.. data:: sqlite_version
172-
173-
Version number of the runtime SQLite library as a :class:`string <str>`.
174-
175-
176-
.. data:: sqlite_version_info
177-
178-
Version number of the runtime SQLite library as a :class:`tuple` of
179-
:class:`integers <int>`.
180-
181-
182-
.. data:: threadsafety
183-
184-
Integer constant required by the DB-API 2.0, stating the level of thread
185-
safety the :mod:`!sqlite3` module supports. This attribute is set based on
186-
the default `threading mode <https://sqlite.org/threadsafe.html>`_ the
187-
underlying SQLite library is compiled with. The SQLite threading modes are:
188-
189-
1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is
190-
unsafe to use in more than a single thread at once.
191-
2. **Multi-thread**: In this mode, SQLite can be safely used by multiple
192-
threads provided that no single database connection is used
193-
simultaneously in two or more threads.
194-
3. **Serialized**: In serialized mode, SQLite can be safely used by
195-
multiple threads with no restriction.
196-
197-
The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels
198-
are as follows:
199-
200-
+------------------+-----------------+----------------------+-------------------------------+
201-
| SQLite threading | `threadsafety`_ | `SQLITE_THREADSAFE`_ | DB-API 2.0 meaning |
202-
| mode | | | |
203-
+==================+=================+======================+===============================+
204-
| single-thread | 0 | 0 | Threads may not share the |
205-
| | | | module |
206-
+------------------+-----------------+----------------------+-------------------------------+
207-
| multi-thread | 1 | 2 | Threads may share the module, |
208-
| | | | but not connections |
209-
+------------------+-----------------+----------------------+-------------------------------+
210-
| serialized | 3 | 1 | Threads may share the module, |
211-
| | | | connections and cursors |
212-
+------------------+-----------------+----------------------+-------------------------------+
213-
214-
.. _threadsafety: https://peps.python.org/pep-0249/#threadsafety
215-
.. _SQLITE_THREADSAFE: https://sqlite.org/compile.html#threadsafe
216-
217-
.. versionchanged:: 3.11
218-
Set *threadsafety* dynamically instead of hard-coding it to ``1``.
219-
220-
.. data:: PARSE_DECLTYPES
221-
222-
Pass this flag value to the *detect_types* parameter of
223-
:func:`connect` to look up a converter function using
224-
the declared types for each column.
225-
The types are declared when the database table is created.
226-
:mod:`!sqlite3` will look up a converter function using the first word of the
227-
declared type as the converter dictionary key.
228-
For example:
229-
230-
231-
.. code-block:: sql
232-
233-
CREATE TABLE test(
234-
i integer primary key, ! will look up a converter named "integer"
235-
p point, ! will look up a converter named "point"
236-
n number(10) ! will look up a converter named "number"
237-
)
238-
239-
This flag may be combined with :const:`PARSE_COLNAMES` using the ``|``
240-
(bitwise or) operator.
241-
242-
243-
.. data:: PARSE_COLNAMES
244-
245-
Pass this flag value to the *detect_types* parameter of
246-
:func:`connect` to look up a converter function by
247-
using the type name, parsed from the query column name,
248-
as the converter dictionary key.
249-
The type name must be wrapped in square brackets (``[]``).
250-
251-
.. code-block:: sql
252-
253-
SELECT p as "p [point]" FROM test; ! will look up converter "point"
254-
255-
This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|``
256-
(bitwise or) operator.
257-
258-
259-
260-
.. function:: connect(database, timeout=5.0, detect_types=0, isolation_level="DEFERRED", check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False)
143+
.. function:: connect(database, timeout=5.0, detect_types=0, \
144+
isolation_level="DEFERRED", check_same_thread=True, \
145+
factory=sqlite3.Connection, cached_statements=128, \
146+
uri=False)
261147

262148
Open a connection to an SQLite database.
263149

@@ -334,30 +220,6 @@ Module functions and constants
334220
.. versionadded:: 3.10
335221
The ``sqlite3.connect/handle`` auditing event.
336222

337-
338-
.. function:: register_converter(typename, converter, /)
339-
340-
Register the *converter* callable to convert SQLite objects of type
341-
*typename* into a Python object of a specific type.
342-
The converter is invoked for all SQLite values of type *typename*;
343-
it is passed a :class:`bytes` object and should return an object of the
344-
desired Python type.
345-
Consult the parameter *detect_types* of
346-
:func:`connect` for information regarding how type detection works.
347-
348-
Note: *typename* and the name of the type in your query are matched
349-
case-insensitively.
350-
351-
352-
.. function:: register_adapter(type, adapter, /)
353-
354-
Register an *adapter* callable to adapt the Python type *type* into an
355-
SQLite type.
356-
The adapter is called with a Python object of type *type* as its sole
357-
argument, and must return a value of a
358-
:ref:`type that SQLite natively understands <sqlite3-types>`.
359-
360-
361223
.. function:: complete_statement(statement)
362224

363225
Returns ``True`` if the string *statement* contains one or more complete SQL
@@ -367,10 +229,8 @@ Module functions and constants
367229

368230
This can be used to build a shell for SQLite, as in the following example:
369231

370-
371232
.. literalinclude:: ../includes/sqlite3/complete_statement.py
372233

373-
374234
.. function:: enable_callback_tracebacks(flag, /)
375235

376236
Enable or disable callback tracebacks.
@@ -398,6 +258,144 @@ Module functions and constants
398258
UnraisableHookArgs(exc_type=<class 'ZeroDivisionError'>, exc_value=ZeroDivisionError('division by zero'), exc_traceback=<traceback object at 0x10b559900>, err_msg=None, object=<function <lambda> at 0x10b4e3ee0>)
399259
<sqlite3.Cursor object at 0x10b1fe840>
400260

261+
.. function:: register_adapter(type, adapter, /)
262+
263+
Register an *adapter* callable to adapt the Python type *type* into an
264+
SQLite type.
265+
The adapter is called with a Python object of type *type* as its sole
266+
argument, and must return a value of a
267+
:ref:`type that SQLite natively understands <sqlite3-types>`.
268+
269+
.. function:: register_converter(typename, converter, /)
270+
271+
Register the *converter* callable to convert SQLite objects of type
272+
*typename* into a Python object of a specific type.
273+
The converter is invoked for all SQLite values of type *typename*;
274+
it is passed a :class:`bytes` object and should return an object of the
275+
desired Python type.
276+
Consult the parameter *detect_types* of
277+
:func:`connect` for information regarding how type detection works.
278+
279+
Note: *typename* and the name of the type in your query are matched
280+
case-insensitively.
281+
282+
283+
.. _sqlite3-module-constants:
284+
285+
Module constants
286+
^^^^^^^^^^^^^^^^
287+
288+
.. data:: PARSE_COLNAMES
289+
290+
Pass this flag value to the *detect_types* parameter of
291+
:func:`connect` to look up a converter function by
292+
using the type name, parsed from the query column name,
293+
as the converter dictionary key.
294+
The type name must be wrapped in square brackets (``[]``).
295+
296+
.. code-block:: sql
297+
298+
SELECT p as "p [point]" FROM test; ! will look up converter "point"
299+
300+
This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|``
301+
(bitwise or) operator.
302+
303+
.. data:: PARSE_DECLTYPES
304+
305+
Pass this flag value to the *detect_types* parameter of
306+
:func:`connect` to look up a converter function using
307+
the declared types for each column.
308+
The types are declared when the database table is created.
309+
:mod:`!sqlite3` will look up a converter function using the first word of the
310+
declared type as the converter dictionary key.
311+
For example:
312+
313+
.. code-block:: sql
314+
315+
CREATE TABLE test(
316+
i integer primary key, ! will look up a converter named "integer"
317+
p point, ! will look up a converter named "point"
318+
n number(10) ! will look up a converter named "number"
319+
)
320+
321+
This flag may be combined with :const:`PARSE_COLNAMES` using the ``|``
322+
(bitwise or) operator.
323+
324+
.. data:: apilevel
325+
326+
String constant stating the supported DB-API level. Required by the DB-API.
327+
Hard-coded to ``"2.0"``.
328+
329+
.. data:: paramstyle
330+
331+
String constant stating the type of parameter marker formatting expected by
332+
the :mod:`!sqlite3` module. Required by the DB-API. Hard-coded to
333+
``"qmark"``.
334+
335+
.. note::
336+
337+
The :mod:`!sqlite3` module supports both ``qmark`` and ``numeric`` DB-API
338+
parameter styles, because that is what the underlying SQLite library
339+
supports. However, the DB-API does not allow multiple values for
340+
the ``paramstyle`` attribute.
341+
342+
.. data:: sqlite_version
343+
344+
Version number of the runtime SQLite library as a :class:`string <str>`.
345+
346+
.. data:: sqlite_version_info
347+
348+
Version number of the runtime SQLite library as a :class:`tuple` of
349+
:class:`integers <int>`.
350+
351+
.. data:: threadsafety
352+
353+
Integer constant required by the DB-API 2.0, stating the level of thread
354+
safety the :mod:`!sqlite3` module supports. This attribute is set based on
355+
the default `threading mode <https://sqlite.org/threadsafe.html>`_ the
356+
underlying SQLite library is compiled with. The SQLite threading modes are:
357+
358+
1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is
359+
unsafe to use in more than a single thread at once.
360+
2. **Multi-thread**: In this mode, SQLite can be safely used by multiple
361+
threads provided that no single database connection is used
362+
simultaneously in two or more threads.
363+
3. **Serialized**: In serialized mode, SQLite can be safely used by
364+
multiple threads with no restriction.
365+
366+
The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels
367+
are as follows:
368+
369+
+------------------+-----------------+----------------------+-------------------------------+
370+
| SQLite threading | `threadsafety`_ | `SQLITE_THREADSAFE`_ | DB-API 2.0 meaning |
371+
| mode | | | |
372+
+==================+=================+======================+===============================+
373+
| single-thread | 0 | 0 | Threads may not share the |
374+
| | | | module |
375+
+------------------+-----------------+----------------------+-------------------------------+
376+
| multi-thread | 1 | 2 | Threads may share the module, |
377+
| | | | but not connections |
378+
+------------------+-----------------+----------------------+-------------------------------+
379+
| serialized | 3 | 1 | Threads may share the module, |
380+
| | | | connections and cursors |
381+
+------------------+-----------------+----------------------+-------------------------------+
382+
383+
.. _threadsafety: https://peps.python.org/pep-0249/#threadsafety
384+
.. _SQLITE_THREADSAFE: https://sqlite.org/compile.html#threadsafe
385+
386+
.. versionchanged:: 3.11
387+
Set *threadsafety* dynamically instead of hard-coding it to ``1``.
388+
389+
.. data:: version
390+
391+
Version number of this module as a :class:`string <str>`.
392+
This is not the version of the SQLite library.
393+
394+
.. data:: version_info
395+
396+
Version number of this module as a :class:`tuple` of :class:`integers <int>`.
397+
This is not the version of the SQLite library.
398+
401399

402400
.. _sqlite3-connection-objects:
403401

0 commit comments

Comments
 (0)