.. Automatically generated by code2rst.py
   code2rst.py src/blob.c doc/blob.rst
   Edit src/blob.c not this file!

.. currentmodule:: apsw

.. _blobio:

Blob Input/Output
*****************

A `blob <http://en.wikipedia.org/wiki/Binary_large_object>`_ is a
SQLite `datatype <http://www.sqlite.org/datatype3.html>`_ representing
a sequence of bytes.  It can be zero or more bytes in size.

SQLite blobs have an absolute maximum size of 2GB and a `default
maximum size <http://www.sqlite.org/c3ref/c_limit_attached.html>`_ of
1GB.

An alternate approach to using blobs is to store the data in files and
store the filename in the database.  Doing so loses the `ACID
<http://www.sqlite.org/transactional.html>`_ properties of SQLite.

zeroblob class
==============

.. class:: zeroblob(size)

  If you want to insert a blob into a row, you previously needed to
  supply the entire blob in one go.  To read just one byte also
  required retrieving the blob in its entireity. For example to insert
  a 100MB file you would have done::

     largedata=open("largefile", "rb").read()
     cur.execute("insert into foo values(?)", (buffer(largedata),))

  SQLite 3.5 allowed for incremental Blob I/O so you can read and
  write blobs in small amounts.  You cannot change the size of a blob
  so you need to reserve space which you do through zeroblob which
  creates a blob of the specified size but full of zero bytes.  For
  example you would reserve space for your 100MB one of these two
  ways::

    cur.execute("insert into foo values(zeroblob(100000000))")
    cur.execute("insert into foo values(?),
                 (apsw.zeroblob(100000000),))

  This class is used for the second way.  Once a blob exists in the
  database, you then use the :class:`blob` class to read and write its
  contents.

.. method:: zeroblob.length() -> int

  Size of zero blob in bytes.

blob class
==========

.. class:: blob

  This object is created by :meth:`Connection.blobopen` and provides
  access to a blob in the database.  It behaves like a Python file.
  At the C level it wraps a `sqlite3_blob
  <http://sqlite.org/c3ref/blob.html>`_.

  .. note::

    You cannot change the size of a blob using this object. You should
    create it with the correct size in advance either by using
    :class:`zeroblob` or the `zeroblob()
    <http://www.sqlite.org/lang_corefunc.html>`_ function.

  See the :ref:`example <example-blobio>`.

.. method:: blob.__enter__() -> context

  You can use a blob as a `context manager
  <http://docs.python.org/reference/datamodel.html#with-statement-context-managers>`_
  as defined in :pep:`0343`.  When you use *with* statement,
  the blob is always :meth:`closed <~blob.close>` on exit from the block, even if an
  exception occurred in the block.

  For example::

    with connection.blobopen() as blob:
        blob.write("...")
        res=blob.read(1024)

.. method:: blob.__exit__() -> False

  Implements context manager in conjunction with
  :meth:`~blob.__enter__`.  Any exception that happened in the
  *with* block is raised after closing the blob.

.. index:: sqlite3_blob_close

.. method:: blob.close([force=False])

  Closes the blob.  Note that even if an error occurs the blob is
  still closed (see :cvstrac:`2815`).

  .. note::

     In some cases errors that technically occurred in the
     :meth:`~blob.read` and :meth:`~blob.write` routines may not be
     reported until close is called.  Similarly errors that occurred
     in those methods (eg calling :meth:`~blob.write` on a read-only
     blob) may also be re-reported in :meth:`~blob.close`.  (This
     behaviour is what the underlying SQLite APIs do - it is not APSW
     doing it.)

  It is okay to call :meth:`~blob.close` multiple times.

  :param force: Ignores any errors during close.

  Calls: :sqliteapi:`sqlite3_blob_close <blob_close>`

.. index:: sqlite3_blob_bytes

.. method:: blob.length() -> int

  Returns the size of the blob in bytes.

  Calls: :sqliteapi:`sqlite3_blob_bytes <blob_bytes>`

.. index:: sqlite3_blob_read

.. method:: blob.read([nbytes]) -> bytes

  Reads amount of data requested, or till end of file, whichever is
  earlier. Attempting to read beyond the end of the blob returns the
  empty string/bytes, in the same manner as end of file on normal file
  objects.

  :rtype: (Python 2) string  (Python 3) bytes

  Calls: :sqliteapi:`sqlite3_blob_read <blob_read>`

.. method:: blob.seek(offset[, whence=0]) -> None

  Changes current position to *offset* biased by *whence*.

  :param offset: New position to seek to.  Can be positive or negative number.
  :param whence: Use 0 if *offset* is relative to the begining of the blob,
                 1 if *offset* is relative to the current position,
                 and 2 if *offset* is relative to the end of the blob.
  :raises ValueError: If the resulting offset is before the begining (less than zero) or beyond the end of the blob.

.. method:: blob.tell() -> int

  Returns the current offset.

.. index:: sqlite3_blob_write

.. method:: blob.write(data) -> None

  Writes the data to the blob.

  :param data: (Python 2) buffer or string. (Python 3) buffer or bytes.

  :raises TypeError: Wrong data type

  :raises ValueError: If the data would go beyond the end of the blob.
      You cannot increase the size of a blob by writing beyond the end.
      You need to use :class:`zeroblob` to set the desired size first when
      inserting the blob.

  Calls: :sqliteapi:`sqlite3_blob_write <blob_write>`

