gh-69093: sqlite3 blob doc amendments (GH-91561)

- document that you cannot open a blob handle in a WITHOUT ROWID table
- document the blobopen() positional arguments in the same order as they
  appear
- relocate sqlite3.Blob section

1 files changed, 55 insertions, 52 deletions

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 4838db0..5c9e2e8 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -397,9 +397,12 @@ Connection Objects
    .. method:: blobopen(table, column, row, /, *, readonly=False, name="main")
 
       Open a :class:`Blob` handle to the :abbr:`BLOB (Binary Large OBject)`
-      located in row *row*, column *column*, table *table* of database *name*.
+      located in table name *table*, column name *column*, and row index *row*
+      of database *name*.
       When *readonly* is :const:`True` the blob is opened without write
       permissions.
+      Trying to open a blob in a ``WITHOUT ROWID`` table will raise
+      :exc:`OperationalError`.
 
       .. note::
 
@@ -1044,6 +1047,57 @@ Now we plug :class:`Row` in::
    35.14
 
 
+Blob Objects
+------------
+
+.. versionadded:: 3.11
+
+.. class:: Blob
+
+   A :class:`Blob` instance is a :term:`file-like object` that can read and write
+   data in an SQLite :abbr:`BLOB (Binary Large OBject)`.  Call ``len(blob)`` to
+   get the size (number of bytes) of the blob.
+
+   Use the :class:`Blob` as a :term:`context manager` to ensure that the blob
+   handle is closed after use.
+
+   .. literalinclude:: ../includes/sqlite3/blob.py
+
+   .. method:: close()
+
+      Close the blob.
+
+      The blob will be unusable from this point onward.  An
+      :class:`~sqlite3.Error` (or subclass) exception will be raised if any
+      further operation is attempted with the blob.
+
+   .. method:: read(length=-1, /)
+
+      Read *length* bytes of data from the blob at the current offset position.
+      If the end of the blob is reached, the data up to
+      :abbr:`EOF (End of File)` will be returned.  When *length* is not
+      specified, or is negative, :meth:`~Blob.read` will read until the end of
+      the blob.
+
+   .. method:: write(data, /)
+
+      Write *data* to the blob at the current offset.  This function cannot
+      change the blob length.  Writing beyond the end of the blob will raise
+      :exc:`ValueError`.
+
+   .. method:: tell()
+
+      Return the current access position of the blob.
+
+   .. method:: seek(offset, origin=os.SEEK_SET, /)
+
+      Set the current access position of the blob to *offset*.  The *origin*
+      argument defaults to :data:`os.SEEK_SET` (absolute blob positioning).
+      Other values for *origin* are :data:`os.SEEK_CUR` (seek relative to the
+      current position) and :data:`os.SEEK_END` (seek relative to the blob’s
+      end).
+
+
 .. _sqlite3-exceptions:
 
 Exceptions
@@ -1104,57 +1158,6 @@ Exceptions
 
 .. _sqlite3-blob-objects:
 
-Blob Objects
-------------
-
-.. versionadded:: 3.11
-
-.. class:: Blob
-
-   A :class:`Blob` instance is a :term:`file-like object` that can read and write
-   data in an SQLite :abbr:`BLOB (Binary Large OBject)`.  Call ``len(blob)`` to
-   get the size (number of bytes) of the blob.
-
-   Use the :class:`Blob` as a :term:`context manager` to ensure that the blob
-   handle is closed after use.
-
-   .. literalinclude:: ../includes/sqlite3/blob.py
-
-   .. method:: close()
-
-      Close the blob.
-
-      The blob will be unusable from this point onward.  An
-      :class:`~sqlite3.Error` (or subclass) exception will be raised if any
-      further operation is attempted with the blob.
-
-   .. method:: read(length=-1, /)
-
-      Read *length* bytes of data from the blob at the current offset position.
-      If the end of the blob is reached, the data up to
-      :abbr:`EOF (End of File)` will be returned.  When *length* is not
-      specified, or is negative, :meth:`~Blob.read` will read until the end of
-      the blob.
-
-   .. method:: write(data, /)
-
-      Write *data* to the blob at the current offset.  This function cannot
-      change the blob length.  Writing beyond the end of the blob will raise
-      :exc:`ValueError`.
-
-   .. method:: tell()
-
-      Return the current access position of the blob.
-
-   .. method:: seek(offset, origin=os.SEEK_SET, /)
-
-      Set the current access position of the blob to *offset*.  The *origin*
-      argument defaults to :data:`os.SEEK_SET` (absolute blob positioning).
-      Other values for *origin* are :data:`os.SEEK_CUR` (seek relative to the
-      current position) and :data:`os.SEEK_END` (seek relative to the blob’s
-      end).
-
-
 .. _sqlite3-types:
 
 SQLite and Python types