@@ -159,23 +159,41 @@ Module functions and constants
159
159
160
160
.. data :: threadsafety
161
161
162
- Integer constant required by the DB-API, stating the level of thread safety
163
- the :mod: `sqlite3 ` module supports. Currently hard-coded to ``1 ``, meaning
164
- *"Threads may share the module, but not connections." * However, this may not
165
- always be true. You can check the underlying SQLite library's compile-time
166
- threaded mode using the following query::
167
-
168
- import sqlite3
169
- con = sqlite3.connect(":memory:")
170
- con.execute("""
171
- select * from pragma_compile_options
172
- where compile_options like 'THREADSAFE=%'
173
- """).fetchall()
174
-
175
- Note that the `SQLITE_THREADSAFE levels
176
- <https://sqlite.org/compile.html#threadsafe> `_ do not match the DB-API 2.0
177
- ``threadsafety `` levels.
178
-
162
+ Integer constant required by the DB-API 2.0, stating the level of thread
163
+ safety the :mod: `sqlite3 ` module supports. This attribute is set based on
164
+ the default `threading mode <https://sqlite.org/threadsafe.html >`_ the
165
+ underlying SQLite library is compiled with. The SQLite threading modes are:
166
+
167
+ 1. **Single-thread **: In this mode, all mutexes are disabled and SQLite is
168
+ unsafe to use in more than a single thread at once.
169
+ 2. **Multi-thread **: In this mode, SQLite can be safely used by multiple
170
+ threads provided that no single database connection is used
171
+ simultaneously in two or more threads.
172
+ 3. **Serialized **: In serialized mode, SQLite can be safely used by
173
+ multiple threads with no restriction.
174
+
175
+ The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels
176
+ are as follows:
177
+
178
+ +------------------+-----------------+----------------------+-------------------------------+
179
+ | SQLite threading | `threadsafety `_ | `SQLITE_THREADSAFE `_ | DB-API 2.0 meaning |
180
+ | mode | | | |
181
+ +==================+=================+======================+===============================+
182
+ | single-thread | 0 | 0 | Threads may not share the |
183
+ | | | | module |
184
+ +------------------+-----------------+----------------------+-------------------------------+
185
+ | multi-thread | 1 | 2 | Threads may share the module, |
186
+ | | | | but not connections |
187
+ +------------------+-----------------+----------------------+-------------------------------+
188
+ | serialized | 3 | 1 | Threads may share the module, |
189
+ | | | | connections and cursors |
190
+ +------------------+-----------------+----------------------+-------------------------------+
191
+
192
+ .. _threadsafety : https://www.python.org/dev/peps/pep-0249/#threadsafety
193
+ .. _SQLITE_THREADSAFE : https://sqlite.org/compile.html#threadsafe
194
+
195
+ .. versionchanged :: 3.11
196
+ Set *threadsafety * dynamically instead of hard-coding it to ``1 ``.
179
197
180
198
.. data :: PARSE_DECLTYPES
181
199
0 commit comments