[Python-checkins] gh-93925: Improve clarity of sqlite3 commit/rollback, and close docs (#93926)
erlend-aasland
webhook-mailer at python.org
Sun Jun 19 15:17:53 EDT 2022
https://github.com/python/cpython/commit/6446592c89b0c581c00e170ae6278291e940755c
commit: 6446592c89b0c581c00e170ae6278291e940755c
branch: main
author: Erlend Egeberg Aasland <erlend.aasland at innova.no>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2022-06-19T21:17:28+02:00
summary:
gh-93925: Improve clarity of sqlite3 commit/rollback, and close docs (#93926)
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>
files:
M Doc/library/sqlite3.rst
M Modules/_sqlite/clinic/connection.c.h
M Modules/_sqlite/connection.c
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 32de16594c0ed..357b7b4365d5b 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -423,21 +423,20 @@ Connection Objects
.. method:: commit()
- This method commits the current transaction. If you don't call this method,
- anything you did since the last call to ``commit()`` is not visible from
- other database connections. If you wonder why you don't see the data you've
- written to the database, please check you didn't forget to call this method.
+ Commit any pending transaction to the database.
+ If there is no open transaction, this method is a no-op.
.. method:: rollback()
- This method rolls back any changes to the database since the last call to
- :meth:`commit`.
+ Roll back to the start of any pending transaction.
+ If there is no open transaction, this method is a no-op.
.. method:: close()
- This closes the database connection. Note that this does not automatically
- call :meth:`commit`. If you just close your database connection without
- calling :meth:`commit` first, your changes will be lost!
+ Close the database connection.
+ Any pending transaction is not committed implicitly;
+ make sure to :meth:`commit` before closing
+ to avoid losing pending changes.
.. method:: execute(sql[, parameters])
diff --git a/Modules/_sqlite/clinic/connection.c.h b/Modules/_sqlite/clinic/connection.c.h
index dd86fb5b64f3f..62d31b787ad71 100644
--- a/Modules/_sqlite/clinic/connection.c.h
+++ b/Modules/_sqlite/clinic/connection.c.h
@@ -248,7 +248,9 @@ PyDoc_STRVAR(pysqlite_connection_close__doc__,
"close($self, /)\n"
"--\n"
"\n"
-"Closes the connection.");
+"Close the database connection.\n"
+"\n"
+"Any pending transaction is not committed implicitly.");
#define PYSQLITE_CONNECTION_CLOSE_METHODDEF \
{"close", (PyCFunction)pysqlite_connection_close, METH_NOARGS, pysqlite_connection_close__doc__},
@@ -266,7 +268,9 @@ PyDoc_STRVAR(pysqlite_connection_commit__doc__,
"commit($self, /)\n"
"--\n"
"\n"
-"Commit the current transaction.");
+"Commit any pending transaction to the database.\n"
+"\n"
+"If there is no open transaction, this method is a no-op.");
#define PYSQLITE_CONNECTION_COMMIT_METHODDEF \
{"commit", (PyCFunction)pysqlite_connection_commit, METH_NOARGS, pysqlite_connection_commit__doc__},
@@ -284,7 +288,9 @@ PyDoc_STRVAR(pysqlite_connection_rollback__doc__,
"rollback($self, /)\n"
"--\n"
"\n"
-"Roll back the current transaction.");
+"Roll back to the start of any pending transaction.\n"
+"\n"
+"If there is no open transaction, this method is a no-op.");
#define PYSQLITE_CONNECTION_ROLLBACK_METHODDEF \
{"rollback", (PyCFunction)pysqlite_connection_rollback, METH_NOARGS, pysqlite_connection_rollback__doc__},
@@ -1231,4 +1237,4 @@ getlimit(pysqlite_Connection *self, PyObject *arg)
#ifndef DESERIALIZE_METHODDEF
#define DESERIALIZE_METHODDEF
#endif /* !defined(DESERIALIZE_METHODDEF) */
-/*[clinic end generated code: output=fb8908674e9f25ff input=a9049054013a1b77]*/
+/*[clinic end generated code: output=8818c1c3ec9425aa input=a9049054013a1b77]*/
diff --git a/Modules/_sqlite/connection.c b/Modules/_sqlite/connection.c
index f0e6a56b43a60..b6b7417fc0a6c 100644
--- a/Modules/_sqlite/connection.c
+++ b/Modules/_sqlite/connection.c
@@ -470,12 +470,14 @@ blobopen_impl(pysqlite_Connection *self, const char *table, const char *col,
/*[clinic input]
_sqlite3.Connection.close as pysqlite_connection_close
-Closes the connection.
+Close the database connection.
+
+Any pending transaction is not committed implicitly.
[clinic start generated code]*/
static PyObject *
pysqlite_connection_close_impl(pysqlite_Connection *self)
-/*[clinic end generated code: output=a546a0da212c9b97 input=3d58064bbffaa3d3]*/
+/*[clinic end generated code: output=a546a0da212c9b97 input=b3ed5b74f6fefc06]*/
{
if (!pysqlite_check_thread(self)) {
return NULL;
@@ -522,12 +524,14 @@ int pysqlite_check_connection(pysqlite_Connection* con)
/*[clinic input]
_sqlite3.Connection.commit as pysqlite_connection_commit
-Commit the current transaction.
+Commit any pending transaction to the database.
+
+If there is no open transaction, this method is a no-op.
[clinic start generated code]*/
static PyObject *
pysqlite_connection_commit_impl(pysqlite_Connection *self)
-/*[clinic end generated code: output=3da45579e89407f2 input=39c12c04dda276a8]*/
+/*[clinic end generated code: output=3da45579e89407f2 input=c8793c97c3446065]*/
{
if (!pysqlite_check_thread(self) || !pysqlite_check_connection(self)) {
return NULL;
@@ -557,12 +561,14 @@ pysqlite_connection_commit_impl(pysqlite_Connection *self)
/*[clinic input]
_sqlite3.Connection.rollback as pysqlite_connection_rollback
-Roll back the current transaction.
+Roll back to the start of any pending transaction.
+
+If there is no open transaction, this method is a no-op.
[clinic start generated code]*/
static PyObject *
pysqlite_connection_rollback_impl(pysqlite_Connection *self)
-/*[clinic end generated code: output=b66fa0d43e7ef305 input=12d4e8d068942830]*/
+/*[clinic end generated code: output=b66fa0d43e7ef305 input=7f60a2f1076f16b3]*/
{
if (!pysqlite_check_thread(self) || !pysqlite_check_connection(self)) {
return NULL;
More information about the Python-checkins
mailing list