[Python-checkins] gh-69093: sqlite3 blob doc amendments (GH-91561)
JelleZijlstra
webhook-mailer at python.org
Sat Apr 16 09:28:48 EDT 2022
https://github.com/python/cpython/commit/95573ade42d1635dd9b69380117cbb47b6790772
commit: 95573ade42d1635dd9b69380117cbb47b6790772
branch: main
author: Erlend Egeberg Aasland <erlend.aasland at innova.no>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-04-16T06:28:38-07:00
summary:
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
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 4838db01669e6..5c9e2e868ab63 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
More information about the Python-checkins
mailing list