From f04bf42ff1f5fa1ea5a5b67d08c97971eff12240 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 18 Jan 2022 10:42:40 +0100 Subject: [PATCH 1/4] bpo-46402: Promote sqlite3 URI tricks in docs --- Doc/library/sqlite3.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 415a5f9a929027..5659ee343bc41b 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -273,14 +273,28 @@ Module functions and constants for the connection, you can set the *cached_statements* parameter. The currently implemented default is to cache 128 statements. - If *uri* is true, *database* is interpreted as a URI. This allows you - to specify options. For example, to open a database in read-only mode - you can use:: - - db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) - - More information about this feature, including a list of recognized options, can - be found in the `SQLite URI documentation `_. + If *uri* is :const:`True`, *database* is interpreted as a + :abbr:`URI (Uniform Resource Identifier)` consisting of a scheme, an + authority, a path, and a query string. The scheme part *must* be ``"file:"``. + 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);") + row = 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 `_. .. audit-event:: sqlite3.connect database sqlite3.connect .. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect From 461cbf37b4e339b62bf02b58ffc4b256a4fcc010 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 18 Jan 2022 12:38:04 +0100 Subject: [PATCH 2/4] fetchall() returns (potentially) multiple rows --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 5659ee343bc41b..ec7c0305d32164 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -290,7 +290,7 @@ Module functions and constants 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);") - row = con2.execute("select * from t").fetchall() + rows = con2.execute("select * from t").fetchall() More information about this feature, including a list of recognized parameters, can be found in the From ae5877eef796cae13646f879915491d5273a04ec Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 18 Jan 2022 13:05:39 +0100 Subject: [PATCH 3/4] Address review: Simplify URI explanation Co-authored-by: Ned Batchelder --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index ec7c0305d32164..71eec9384c3702 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -274,8 +274,8 @@ Module functions and constants implemented default is to cache 128 statements. If *uri* is :const:`True`, *database* is interpreted as a - :abbr:`URI (Uniform Resource Identifier)` consisting of a scheme, an - authority, a path, and a query string. The scheme part *must* be ``"file:"``. + :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:: From de7867efe7a17ffd153fc014e9d3411623afb73e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 18 Jan 2022 13:07:52 +0100 Subject: [PATCH 4/4] Reformat to max 80 chars pr. line --- Doc/library/sqlite3.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 71eec9384c3702..d213933ba5827f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -274,10 +274,10 @@ Module functions and constants implemented default is to cache 128 statements. If *uri* is :const:`True`, *database* is interpreted as a - :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:: + :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)