From bb9cc1216873604459724860d606283c398ea06b Mon Sep 17 00:00:00 2001
From: Ruben Pollan <meskio@sindominio.net>
Date: Thu, 2 Feb 2017 20:25:20 +0100
Subject: [feat] add support for the blob interface

Pysqlcipher support for the sqlite blob interface:
https://sqlite.org/c3ref/blob_open.html

Copying the code from the PR in pysqlite:
https://github.com/ghaering/pysqlite/pull/93
---
 doc/examples/blob.py      | 13 ++++++++++
 doc/examples/blob_with.py | 12 ++++++++++
 doc/sphinx/sqlcipher.rst  | 61 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 doc/examples/blob.py
 create mode 100644 doc/examples/blob_with.py

(limited to 'doc')

diff --git a/doc/examples/blob.py b/doc/examples/blob.py
new file mode 100644
index 0000000..2d63b9c
--- /dev/null
+++ b/doc/examples/blob.py
@@ -0,0 +1,13 @@
+from pysqlcipher import dbapi2 as sqlite3
+con = sqlite3.connect(":memory:")
+# creating the table
+con.execute("create table test(id integer primary key, blob_col blob)")
+con.execute("insert into test(blob_col) values (zeroblob(10))")
+# opening blob handle
+blob = con.blob("test", "blob_col", 1, 1)
+blob.write("a" * 5)
+blob.write("b" * 5)
+blob.seek(0)
+print blob.read() # will print "aaaaabbbbb"
+blob.close()
+
diff --git a/doc/examples/blob_with.py b/doc/examples/blob_with.py
new file mode 100644
index 0000000..fff9037
--- /dev/null
+++ b/doc/examples/blob_with.py
@@ -0,0 +1,12 @@
+from pysqlcipher import dbapi2 as sqlite3
+con = sqlite3.connect(":memory:")
+# creating the table
+con.execute("create table test(id integer primary key, blob_col blob)")
+con.execute("insert into test(blob_col) values (zeroblob(10))")
+# opening blob handle
+with con.blob("test", "blob_col", 1, 1) as blob:
+    blob.write("a" * 5)
+    blob.write("b" * 5)
+    blob.seek(0)
+    print blob.read() # will print "aaaaabbbbb" 
+
diff --git a/doc/sphinx/sqlcipher.rst b/doc/sphinx/sqlcipher.rst
index 7785aeb..2332528 100644
--- a/doc/sphinx/sqlcipher.rst
+++ b/doc/sphinx/sqlcipher.rst
@@ -236,6 +236,13 @@ Connection Objects
    :class:`sqlite3.Cursor`.
 
 
+.. method:: Connection.blob(table, column, row, flags=0, dbname="main")
+
+   On success a :class:`Blob` handle to the blob located in row 'row', 
+   column 'column', table 'table' in database 'dbname' will be returned.
+   The flags represent the blob mode. 0 for read-only otherwise read-write.
+
+
 .. method:: Connection.commit()
 
    This method commits the current transaction. If you don't call this method,
@@ -631,6 +638,60 @@ Now we plug :class:`Row` in::
     35.14
 
 
+.. _sqlite3-blob-objects:
+
+Blob Objects
+--------------
+
+.. class:: Blob
+
+A :class:`Blob` instance has the following attributes and methods:
+
+   A SQLite database blob has the following attributes and methods:
+
+.. method:: Blob.close()
+
+   Close the blob now (rather than whenever __del__ is called).
+
+   The blob will be unusable from this point forward; an Error (or subclass)
+   exception will be raised if any operation is attempted with the blob.
+
+.. method:: Blob.length()
+
+   Return the blob size.
+
+.. method:: Blob.read([length])
+
+   Read lnegth 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 
+   length is not specified or negative we will read up to end of blob.
+
+.. method:: Blob.write(data)
+
+   Write data to the blob at the current offset. This function cannot changed blob
+   length. If data write will result in writing to more then blob current size an 
+   error will be raised.
+
+.. method:: Blob.tell()
+
+   Return the current offset of the blob.
+
+.. method:: Blob.seek(offset, [whence])
+
+   Set the blob offset. The whence argument is optional and defaults to os.SEEK_SET 
+   or 0 (absolute blob positioning); other values are os.SEEK_CUR or 1 (seek 
+   relative to the current position) and os.SEEK_END or 2 (seek relative to the blob’s end).
+
+
+:class:`Blob` example:
+
+   .. literalinclude:: ../includes/sqlite3/blob.py
+
+A :class:`Blob` can also be used with context manager:
+
+   .. literalinclude:: ../includes/sqlite3/blob_with.py
+
+
 .. _sqlite3-types:
 
 SQLite and Python types
-- 
cgit v1.2.3