gh-69093: Add incremental I/O to blobs support in sqlite3

Doc/includes/sqlite3/blob.py

@@ -0,0 +1,12 @@
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+con.execute("create table test(blob_col blob)")
+con.execute("insert into test(blob_col) values (zeroblob(10))")
+
+blob = con.blobopen("test", "blob_col", 1)
+blob.write(b"Hello")
+blob.write(b"World")
+blob.seek(0)
+print(blob.read())  # will print b"HelloWorld"
+blob.close()

Doc/includes/sqlite3/blob_with.py

@@ -0,0 +1,12 @@
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+
+con.execute("create table test(blob_col blob)")
+con.execute("insert into test(blob_col) values (zeroblob(10))")
+
+with con.blobopen("test", "blob_col", 1) as blob:
+    blob.write(b"Hello")
+    blob.write(b"World")
+    blob.seek(0)
+    print(blob.read())  # will print b"HelloWorld"

Doc/library/sqlite3.rst

@@ -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,
@@ -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

Doc/whatsnew/3.11.rst

@@ -301,6 +301,10 @@ sqlite3
   Instead we leave it to the SQLite library to handle these cases.
   (Contributed by Erlend E. Aasland in :issue:`44092`.)
 
+* Add :meth:`~sqlite3.Connection.blobopen` to :class:`sqlite3.Connection`.
+  :class:`sqlite3.Blob` allows incremental I/O operations on blobs.
+  (Contributed by Aviv Palivoda and Erlend E. Aasland in :issue:`24905`)
+
 
 sys
 ---