gh-69093: Add incremental I/O to blobs support in `sqlite3` by erlend-aasland · Pull Request #30356 · python/cpython

Expand Up @@ -394,6 +394,20 @@ Connection Objects supplied, this must be a callable returning an instance of :class:`Cursor` or its subclasses.
.. method:: blobopen(table, column, row, /, *, readonly=False, name="main")
On success, a :class:`Blob` handle to the :abbr:`BLOB (Binary Large OBject)` located in row *row*, column *column*, table *table* in database *name* will be returned. When *readonly* is :const:`True` the blob is opened without write permissions.
.. note::
The BLOB size cannot be changed using the :class:`Blob` class. Use the SQL function ``zeroblob`` to create a blob with a fixed size.
.. versionadded:: 3.11
.. method:: commit()
This method commits the current transaction. If you don't call this method, Expand Down Expand Up @@ -1021,6 +1035,65 @@ Exceptions transactions turned off. It is a subclass of :exc:`DatabaseError`.

.. _sqlite3-blob-objects:
Blob Objects ------------
.. versionadded:: 3.11
.. class:: Blob
A :class:`Blob` instance can read and write the data in a :abbr:`BLOB (Binary Large OBject)`. The :class:`Blob` class implements the file and mapping protocols.
.. method:: Blob.close()
Close the BLOB.
The BLOB will be unusable from this point forward. An :class:`~sqlite3.Error` (or subclass) exception will be raised if any further operation is attempted with the BLOB.
.. method:: Blob.__len__()
Return the BLOB size as length in bytes.
.. method:: Blob.read(length=-1, /)
Read *length* bytes of data from the BLOB at the current offset position. If the end of the BLOB is reached we will return the data up to end of file. When *size* is not specified or is negative, :meth:`~Blob.read` will read till the end of the BLOB.
.. method:: Blob.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 result in an exception being raised.
.. method:: Blob.tell()
Return the current access position of the BLOB.
.. method:: Blob.seek(offset, origin=sqlite3.BLOB_SEEK_START, /)
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).
:class:`Blob` example:
.. literalinclude:: ../includes/sqlite3/blob.py
A :class:`Blob` can also be used as a :term:`context manager`:
.. literalinclude:: ../includes/sqlite3/blob_with.py

.. _sqlite3-types:
SQLite and Python types Expand Down