gh-81040: Improve sqlite3.Cursor.rowcount docs (GH-94940)

(cherry picked from commit f9b3706df65c4962646587b437a4eb39289dfd4c)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 9da7b5403cca3370b51aa5ec174dc0b4a3ec083f..28f3b32014afaaeef931fce238ec40603ac39413 100644 (file)
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -956,18 +956,11 @@ Cursor Objects
 
    .. attribute:: rowcount
 
-      Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
-      attribute, the database engine's own support for the determination of "rows
-      affected"/"rows selected" is quirky.
-
-      For :meth:`executemany` statements, the number of modifications are summed up
-      into :attr:`rowcount`.
-
-      As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
-      case no ``executeXX()`` has been performed on the cursor or the rowcount of the
-      last operation is not determinable by the interface". This includes ``SELECT``
-      statements because we cannot determine the number of rows a query produced
-      until all rows were fetched.
+      Read-only attribute that provides the number of modified rows for
+      ``INSERT``, ``UPDATE``, ``DELETE``, and ``REPLACE`` statements;
+      is ``-1`` for other statements,
+      including :abbr:`CTE (Common Table Expression)` queries.
+      It is only updated by the :meth:`execute` and :meth:`executemany` methods.
 
    .. attribute:: lastrowid