[pkg] unify client and server into a single python package

We have been discussing about this merge for a while.
Its main goal is to simplify things: code navigation, but also
packaging.

The rationale is that the code is more cohesive in this way, and there's
only one source package to install.

Dependencies that are only for the server or the client will not be
installed by default, and they are expected to be provided by the
environment. There are setuptools extras defined for the client and the
server.

Debianization is still expected to split the single source package into
3 binaries.

Another avantage is that the documentation can now install a single
package with a single step, and therefore include the docstrings into
the generated docs.

- Resolves: #8896

12 files changed, 736 insertions, 0 deletions

diff --git a/src/leap/soledad/client/examples/README b/src/leap/soledad/client/examples/README
new file mode 100644
index 00000000..3aed8377
--- /dev/null
+++ b/src/leap/soledad/client/examples/README
@@ -0,0 +1,4 @@
+Right now, you can find here both an example of use
+and the benchmarking scripts.
+TODO move benchmark scripts to root scripts/ folder,
+and leave here only a minimal example.
diff --git a/src/leap/soledad/client/examples/benchmarks/.gitignore b/src/leap/soledad/client/examples/benchmarks/.gitignore
new file mode 100644
index 00000000..2211df63
--- /dev/null
+++ b/src/leap/soledad/client/examples/benchmarks/.gitignore
@@ -0,0 +1 @@
+*.txt
diff --git a/src/leap/soledad/client/examples/benchmarks/get_sample.sh b/src/leap/soledad/client/examples/benchmarks/get_sample.sh
new file mode 100755
index 00000000..1995eee1
--- /dev/null
+++ b/src/leap/soledad/client/examples/benchmarks/get_sample.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+mkdir tmp
+wget http://www.gutenberg.org/cache/epub/101/pg101.txt -O hacker_crackdown.txt
diff --git a/src/leap/soledad/client/examples/benchmarks/measure_index_times.py b/src/leap/soledad/client/examples/benchmarks/measure_index_times.py
new file mode 100644
index 00000000..f9349758
--- /dev/null
+++ b/src/leap/soledad/client/examples/benchmarks/measure_index_times.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+# measure_index_times.py
+# Copyright (C) 2014 LEAP
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Measure u1db retrieval times for different u1db index situations.
+"""
+from __future__ import print_function
+from functools import partial
+import datetime
+import hashlib
+import os
+import sys
+
+from twisted.internet import defer, reactor
+
+from leap.soledad.common import l2db
+from leap.soledad.client import adbapi
+from leap.soledad.client._db.sqlcipher import SQLCipherOptions
+
+
+folder = os.environ.get("TMPDIR", "tmp")
+numdocs = int(os.environ.get("DOCS", "1000"))
+silent = os.environ.get("SILENT", False)
+tmpdb = os.path.join(folder, "test.soledad")
+
+
+sample_file = os.environ.get("SAMPLE", "hacker_crackdown.txt")
+sample_path = os.path.join(os.curdir, sample_file)
+
+try:
+    with open(sample_file) as f:
+        SAMPLE = f.readlines()
+except Exception:
+    print("[!] Problem opening sample file. Did you download "
+          "the sample, or correctly set 'SAMPLE' env var?")
+    sys.exit(1)
+
+if numdocs > len(SAMPLE):
+    print("[!] Sorry! The requested DOCS number is larger than "
+          "the num of lines in our sample file")
+    sys.exit(1)
+
+
+def debug(*args):
+    if not silent:
+        print(*args)
+
+
+debug("[+] db path:", tmpdb)
+debug("[+] num docs", numdocs)
+
+if os.path.isfile(tmpdb):
+    debug("[+] Removing existing db file...")
+    os.remove(tmpdb)
+
+start_time = datetime.datetime.now()
+
+opts = SQLCipherOptions(tmpdb, "secret", create=True)
+dbpool = adbapi.getConnectionPool(opts)
+
+
+def createDoc(doc):
+    return dbpool.runU1DBQuery("create_doc", doc)
+
+
+db_indexes = {
+    'by-chash': ['chash'],
+    'by-number': ['number']}
+
+
+def create_indexes(_):
+    deferreds = []
+    for index, definition in db_indexes.items():
+        d = dbpool.runU1DBQuery("create_index", index, *definition)
+        deferreds.append(d)
+    return defer.gatherResults(deferreds)
+
+
+class TimeWitness(object):
+    def __init__(self, init_time):
+        self.init_time = init_time
+
+    def get_time_count(self):
+        return datetime.datetime.now() - self.init_time
+
+
+def get_from_index(_):
+    init_time = datetime.datetime.now()
+    debug("GETTING FROM INDEX...", init_time)
+
+    def printValue(res, time):
+        print("RESULT->", res)
+        print("Index Query Took: ", time.get_time_count())
+        return res
+
+    d = dbpool.runU1DBQuery(
+        "get_from_index", "by-chash",
+        # "1150c7f10fabce0a57ce13071349fc5064f15bdb0cc1bf2852f74ef3f103aff5")
+        # XXX this is line 89 from the hacker crackdown...
+        # Should accept any other optional hash as an enviroment variable.
+        "57793320d4997a673fc7062652da0596c36a4e9fbe31310d2281e67d56d82469")
+    d.addCallback(printValue, TimeWitness(init_time))
+    return d
+
+
+def getAllDocs():
+    return dbpool.runU1DBQuery("get_all_docs")
+
+
+def errBack(e):
+    debug("[!] ERROR FOUND!!!")
+    e.printTraceback()
+    reactor.stop()
+
+
+def countDocs(_):
+    debug("counting docs...")
+    d = getAllDocs()
+    d.addCallbacks(printResult, errBack)
+    d.addCallbacks(allDone, errBack)
+    return d
+
+
+def printResult(r, **kwargs):
+    if kwargs:
+        debug(*kwargs.values())
+    elif isinstance(r, l2db.Document):
+        debug(r.doc_id, r.content['number'])
+    else:
+        len_results = len(r[1])
+        debug("GOT %s results" % len(r[1]))
+
+        if len_results == numdocs:
+            debug("ALL GOOD")
+        else:
+            debug("[!] MISSING DOCS!!!!!")
+            raise ValueError("We didn't expect this result len")
+
+
+def allDone(_):
+    debug("ALL DONE!")
+
+    end_time = datetime.datetime.now()
+    print((end_time - start_time).total_seconds())
+    reactor.stop()
+
+
+def insert_docs(_):
+    deferreds = []
+    for i in range(numdocs):
+        payload = SAMPLE[i]
+        chash = hashlib.sha256(payload).hexdigest()
+        doc = {"number": i, "payload": payload, 'chash': chash}
+        d = createDoc(doc)
+        d.addCallbacks(partial(printResult, i=i, chash=chash, payload=payload),
+                       lambda e: e.printTraceback())
+        deferreds.append(d)
+    return defer.gatherResults(deferreds, consumeErrors=True)
+
+
+d = create_indexes(None)
+d.addCallback(insert_docs)
+d.addCallback(get_from_index)
+d.addCallback(countDocs)
+
+reactor.run()
diff --git a/src/leap/soledad/client/examples/benchmarks/measure_index_times_custom_docid.py b/src/leap/soledad/client/examples/benchmarks/measure_index_times_custom_docid.py
new file mode 100644
index 00000000..4f273c64
--- /dev/null
+++ b/src/leap/soledad/client/examples/benchmarks/measure_index_times_custom_docid.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+# measure_index_times.py
+# Copyright (C) 2014 LEAP
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Measure u1db retrieval times for different u1db index situations.
+"""
+from __future__ import print_function
+from functools import partial
+import datetime
+import hashlib
+import os
+import sys
+
+from twisted.internet import defer, reactor
+
+from leap.soledad.client import adbapi
+from leap.soledad.client._db.sqlcipher import SQLCipherOptions
+from leap.soledad.common import l2db
+
+
+folder = os.environ.get("TMPDIR", "tmp")
+numdocs = int(os.environ.get("DOCS", "1000"))
+silent = os.environ.get("SILENT", False)
+tmpdb = os.path.join(folder, "test.soledad")
+
+
+sample_file = os.environ.get("SAMPLE", "hacker_crackdown.txt")
+sample_path = os.path.join(os.curdir, sample_file)
+
+try:
+    with open(sample_file) as f:
+        SAMPLE = f.readlines()
+except Exception:
+    print("[!] Problem opening sample file. Did you download "
+          "the sample, or correctly set 'SAMPLE' env var?")
+    sys.exit(1)
+
+if numdocs > len(SAMPLE):
+    print("[!] Sorry! The requested DOCS number is larger than "
+          "the num of lines in our sample file")
+    sys.exit(1)
+
+
+def debug(*args):
+    if not silent:
+        print(*args)
+
+
+debug("[+] db path:", tmpdb)
+debug("[+] num docs", numdocs)
+
+if os.path.isfile(tmpdb):
+    debug("[+] Removing existing db file...")
+    os.remove(tmpdb)
+
+start_time = datetime.datetime.now()
+
+opts = SQLCipherOptions(tmpdb, "secret", create=True)
+dbpool = adbapi.getConnectionPool(opts)
+
+
+def createDoc(doc, doc_id):
+    return dbpool.runU1DBQuery("create_doc", doc, doc_id=doc_id)
+
+
+db_indexes = {
+    'by-chash': ['chash'],
+    'by-number': ['number']}
+
+
+def create_indexes(_):
+    deferreds = []
+    for index, definition in db_indexes.items():
+        d = dbpool.runU1DBQuery("create_index", index, *definition)
+        deferreds.append(d)
+    return defer.gatherResults(deferreds)
+
+
+class TimeWitness(object):
+    def __init__(self, init_time):
+        self.init_time = init_time
+
+    def get_time_count(self):
+        return datetime.datetime.now() - self.init_time
+
+
+def get_from_index(_):
+    init_time = datetime.datetime.now()
+    debug("GETTING FROM INDEX...", init_time)
+
+    def printValue(res, time):
+        print("RESULT->", res)
+        print("Index Query Took: ", time.get_time_count())
+        return res
+
+    d = dbpool.runU1DBQuery(
+        "get_doc",
+        # "1150c7f10fabce0a57ce13071349fc5064f15bdb0cc1bf2852f74ef3f103aff5")
+        # XXX this is line 89 from the hacker crackdown...
+        # Should accept any other optional hash as an enviroment variable.
+        "57793320d4997a673fc7062652da0596c36a4e9fbe31310d2281e67d56d82469")
+    d.addCallback(printValue, TimeWitness(init_time))
+    return d
+
+
+def getAllDocs():
+    return dbpool.runU1DBQuery("get_all_docs")
+
+
+def errBack(e):
+    debug("[!] ERROR FOUND!!!")
+    e.printTraceback()
+    reactor.stop()
+
+
+def countDocs(_):
+    debug("counting docs...")
+    d = getAllDocs()
+    d.addCallbacks(printResult, errBack)
+    d.addCallbacks(allDone, errBack)
+    return d
+
+
+def printResult(r, **kwargs):
+    if kwargs:
+        debug(*kwargs.values())
+    elif isinstance(r, l2db.Document):
+        debug(r.doc_id, r.content['number'])
+    else:
+        len_results = len(r[1])
+        debug("GOT %s results" % len(r[1]))
+
+        if len_results == numdocs:
+            debug("ALL GOOD")
+        else:
+            debug("[!] MISSING DOCS!!!!!")
+            raise ValueError("We didn't expect this result len")
+
+
+def allDone(_):
+    debug("ALL DONE!")
+
+    end_time = datetime.datetime.now()
+    print((end_time - start_time).total_seconds())
+    reactor.stop()
+
+
+def insert_docs(_):
+    deferreds = []
+    for i in range(numdocs):
+        payload = SAMPLE[i]
+        chash = hashlib.sha256(payload).hexdigest()
+        doc = {"number": i, "payload": payload, 'chash': chash}
+        d = createDoc(doc, doc_id=chash)
+        d.addCallbacks(partial(printResult, i=i, chash=chash, payload=payload),
+                       lambda e: e.printTraceback())
+        deferreds.append(d)
+    return defer.gatherResults(deferreds, consumeErrors=True)
+
+
+d = create_indexes(None)
+d.addCallback(insert_docs)
+d.addCallback(get_from_index)
+d.addCallback(countDocs)
+
+reactor.run()
diff --git a/src/leap/soledad/client/examples/compare.txt b/src/leap/soledad/client/examples/compare.txt
new file mode 100644
index 00000000..19a1325a
--- /dev/null
+++ b/src/leap/soledad/client/examples/compare.txt
@@ -0,0 +1,8 @@
+TIMES=100 TMPDIR=/media/sdb5/leap python use_adbapi.py  1.34s user 0.16s system 53% cpu 2.832 total
+TIMES=100 TMPDIR=/media/sdb5/leap python use_api.py  1.22s user 0.14s system 62% cpu 2.181 total
+
+TIMES=1000 TMPDIR=/media/sdb5/leap python use_api.py  2.18s user 0.34s system 27% cpu 9.213 total
+TIMES=1000 TMPDIR=/media/sdb5/leap python use_adbapi.py  2.40s user 0.34s system 39% cpu 7.004 total
+
+TIMES=5000 TMPDIR=/media/sdb5/leap python use_api.py  6.63s user 1.27s system 13% cpu 57.882 total
+TIMES=5000 TMPDIR=/media/sdb5/leap python use_adbapi.py  6.84s user 1.26s system 36% cpu 22.367 total
diff --git a/src/leap/soledad/client/examples/manifest.phk b/src/leap/soledad/client/examples/manifest.phk
new file mode 100644
index 00000000..2c86c07d
--- /dev/null
+++ b/src/leap/soledad/client/examples/manifest.phk
@@ -0,0 +1,50 @@
+The Hacker's Manifesto
+
+The Hacker's Manifesto
+by: The Mentor
+
+Another one got caught today, it's all over the papers. "Teenager 
+Arrested in Computer Crime Scandal", "Hacker Arrested after Bank 
+Tampering." "Damn kids. They're all alike." But did you, in your 
+three-piece psychology and 1950's technobrain, ever take a look behind 
+the eyes of the hacker? Did you ever wonder what made him tick, what 
+forces shaped him, what may have molded him? I am a hacker, enter my 
+world. Mine is a world that begins with school. I'm smarter than most of 
+the other kids, this crap they teach us bores me. "Damn underachiever. 
+They're all alike." I'm in junior high or high school.  I've listened to 
+teachers explain for the fifteenth time how to reduce a fraction. I 
+understand it. "No, Ms. Smith, I didn't show my work. I did it in
+my head." "Damn kid. Probably copied it. They're all alike." I made a 
+discovery today. I found a computer. Wait a second, this is cool. It does 
+what I want it to. If it makes a mistake, it's because I screwed it up. 
+Not because it doesn't like me, or feels threatened by me, or thinks I'm 
+a smart ass, or doesn't like teaching and shouldn't be here. Damn kid. 
+All he does is play games. They're all alike. And then it happened... a 
+door opened to a world... rushing through the phone line like heroin 
+through an addict's veins, an electronic pulse is sent out, a refuge from 
+the day-to-day incompetencies is sought... a board is found. "This is 
+it... this is where I belong..." I know everyone here... even if I've 
+never met them, never talked to them, may never hear from them again... I 
+know you all... Damn kid. Tying up the phone line again. They're all 
+alike... You bet your ass we're all alike... we've been spoon-fed baby 
+food at school when we hungered for steak... the bits of meat that you 
+did let slip through were pre-chewed and tasteless. We've been dominated 
+by sadists, or ignored by the apathetic. The few that had something to 
+teach found us willing pupils, but those few are like drops of water in 
+the desert. This is our world now... the world of the electron and the 
+switch, the beauty of the baud. We make use of a service already existing 
+without paying for what could be dirt-cheap if it wasn't run by 
+profiteering gluttons, and you call us criminals. We explore... and you 
+call us criminals. We seek after knowledge... and you call us criminals. 
+We exist without skin color, without nationality, without religious 
+bias... and you call us criminals. You build atomic bombs, you wage wars, 
+you murder, cheat, and lie to us and try to make us believe it's for our 
+own good, yet we're the criminals. Yes, I am a criminal. My crime is that 
+of curiosity. My crime is that of judging people by what they say and 
+think, not what they look like. My crime is that of outsmarting you, 
+something that you will never forgive me for. I am a hacker, and this is 
+my manifesto.  You may stop this individual, but you can't stop us all... 
+after all, we're all alike.
+
+This was the last published file written by The Mentor. Shortly after 
+releasing it, he was busted by the FBI. The Mentor, sadly missed.
diff --git a/src/leap/soledad/client/examples/plot-async-db.py b/src/leap/soledad/client/examples/plot-async-db.py
new file mode 100644
index 00000000..018a1a1d
--- /dev/null
+++ b/src/leap/soledad/client/examples/plot-async-db.py
@@ -0,0 +1,45 @@
+import csv
+from matplotlib import pyplot as plt
+
+FILE = "bench.csv"
+
+# config the plot
+plt.xlabel('number of inserts')
+plt.ylabel('time (seconds)')
+plt.title('SQLCipher parallelization')
+
+kwargs = {
+    'linewidth': 1.0,
+    'linestyle': '-',
+}
+
+series = (('sync', 'r'),
+          ('async', 'g'))
+
+data = {'mark': [],
+        'sync': [],
+        'async': []}
+
+with open(FILE, 'rb') as csvfile:
+    series_reader = csv.reader(csvfile, delimiter=',')
+    for m, s, a in series_reader:
+        data['mark'].append(int(m))
+        data['sync'].append(float(s))
+        data['async'].append(float(a))
+
+xmax = max(data['mark'])
+xmin = min(data['mark'])
+ymax = max(data['sync'] + data['async'])
+ymin = min(data['sync'] + data['async'])
+
+for run in series:
+    name = run[0]
+    color = run[1]
+    plt.plot(data['mark'], data[name], label=name, color=color, **kwargs)
+
+plt.axes().annotate("", xy=(xmax, ymax))
+plt.axes().annotate("", xy=(xmin, ymin))
+
+plt.grid()
+plt.legend()
+plt.show()
diff --git a/src/leap/soledad/client/examples/run_benchmark.py b/src/leap/soledad/client/examples/run_benchmark.py
new file mode 100644
index 00000000..ddedf433
--- /dev/null
+++ b/src/leap/soledad/client/examples/run_benchmark.py
@@ -0,0 +1,30 @@
+"""
+Run a mini-benchmark between regular api and dbapi
+"""
+import commands
+import os
+import time
+
+TMPDIR = os.environ.get("TMPDIR", "/tmp")
+CSVFILE = 'bench.csv'
+
+cmd = "SILENT=1 TIMES={times} TMPDIR={tmpdir} python ./use_{version}api.py"
+
+
+def parse_time(r):
+    return r.split('\n')[-1]
+
+
+with open(CSVFILE, 'w') as log:
+
+    for times in range(0, 10000, 500):
+        cmd1 = cmd.format(times=times, tmpdir=TMPDIR, version="")
+        sync_time = parse_time(commands.getoutput(cmd1))
+
+        cmd2 = cmd.format(times=times, tmpdir=TMPDIR, version="adb")
+        async_time = parse_time(commands.getoutput(cmd2))
+
+        print times, sync_time, async_time
+        log.write("%s, %s, %s\n" % (times, sync_time, async_time))
+        log.flush()
+        time.sleep(2)
diff --git a/src/leap/soledad/client/examples/soledad_sync.py b/src/leap/soledad/client/examples/soledad_sync.py
new file mode 100644
index 00000000..3aed10eb
--- /dev/null
+++ b/src/leap/soledad/client/examples/soledad_sync.py
@@ -0,0 +1,63 @@
+from leap.bitmask.config.providerconfig import ProviderConfig
+from leap.bitmask.crypto.srpauth import SRPAuth
+from leap.soledad.client import Soledad
+from twisted.internet import reactor
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+
+# EDIT THIS --------------------------------------------
+user = u"USERNAME"
+uuid = u"USERUUID"
+_pass = u"USERPASS"
+server_url = "https://soledad.server.example.org:2323"
+# EDIT THIS --------------------------------------------
+
+secrets_path = "/tmp/%s.secrets" % uuid
+local_db_path = "/tmp/%s.soledad" % uuid
+cert_file = "/tmp/cacert.pem"
+provider_config = '/tmp/cdev.json'
+
+
+provider = ProviderConfig()
+provider.load(provider_config)
+
+soledad = None
+
+
+def printStuff(r):
+    print r
+
+
+def printErr(err):
+    logging.exception(err.value)
+
+
+def init_soledad(_):
+    token = srpauth.get_token()
+    print "token", token
+
+    global soledad
+    soledad = Soledad(uuid, _pass, secrets_path, local_db_path,
+                      server_url, cert_file,
+                      auth_token=token)
+
+    def getall(_):
+        d = soledad.get_all_docs()
+        return d
+
+    d1 = soledad.create_doc({"test": 42})
+    d1.addCallback(getall)
+    d1.addCallbacks(printStuff, printErr)
+
+    d2 = soledad.sync()
+    d2.addCallbacks(printStuff, printErr)
+    d2.addBoth(lambda r: reactor.stop())
+
+
+srpauth = SRPAuth(provider)
+
+d = srpauth.authenticate(user, _pass)
+d.addCallbacks(init_soledad, printErr)
+
+reactor.run()
diff --git a/src/leap/soledad/client/examples/use_adbapi.py b/src/leap/soledad/client/examples/use_adbapi.py
new file mode 100644
index 00000000..ddb1eaae
--- /dev/null
+++ b/src/leap/soledad/client/examples/use_adbapi.py
@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+# use_adbapi.py
+# Copyright (C) 2014 LEAP
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Example of use of the asynchronous soledad api.
+"""
+from __future__ import print_function
+import datetime
+import os
+
+from twisted.internet import defer, reactor
+
+from leap.soledad.client import adbapi
+from leap.soledad.client._db.sqlcipher import SQLCipherOptions
+from leap.soledad.common import l2db
+
+
+folder = os.environ.get("TMPDIR", "tmp")
+times = int(os.environ.get("TIMES", "1000"))
+silent = os.environ.get("SILENT", False)
+
+tmpdb = os.path.join(folder, "test.soledad")
+
+
+def debug(*args):
+    if not silent:
+        print(*args)
+
+
+debug("[+] db path:", tmpdb)
+debug("[+] times", times)
+
+if os.path.isfile(tmpdb):
+    debug("[+] Removing existing db file...")
+    os.remove(tmpdb)
+
+start_time = datetime.datetime.now()
+
+opts = SQLCipherOptions(tmpdb, "secret", create=True)
+dbpool = adbapi.getConnectionPool(opts)
+
+
+def createDoc(doc):
+    return dbpool.runU1DBQuery("create_doc", doc)
+
+
+def getAllDocs():
+    return dbpool.runU1DBQuery("get_all_docs")
+
+
+def countDocs(_):
+    debug("counting docs...")
+    d = getAllDocs()
+    d.addCallbacks(printResult, lambda e: e.printTraceback())
+    d.addBoth(allDone)
+
+
+def printResult(r):
+    if isinstance(r, l2db.Document):
+        debug(r.doc_id, r.content['number'])
+    else:
+        len_results = len(r[1])
+        debug("GOT %s results" % len(r[1]))
+
+        if len_results == times:
+            debug("ALL GOOD")
+        else:
+            raise ValueError("We didn't expect this result len")
+
+
+def allDone(_):
+    debug("ALL DONE!")
+    if silent:
+        end_time = datetime.datetime.now()
+        print((end_time - start_time).total_seconds())
+    reactor.stop()
+
+
+deferreds = []
+payload = open('manifest.phk').read()
+
+for i in range(times):
+    doc = {"number": i, "payload": payload}
+    d = createDoc(doc)
+    d.addCallbacks(printResult, lambda e: e.printTraceback())
+    deferreds.append(d)
+
+
+all_done = defer.gatherResults(deferreds, consumeErrors=True)
+all_done.addCallback(countDocs)
+
+reactor.run()
diff --git a/src/leap/soledad/client/examples/use_api.py b/src/leap/soledad/client/examples/use_api.py
new file mode 100644
index 00000000..db77c4b3
--- /dev/null
+++ b/src/leap/soledad/client/examples/use_api.py
@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+# use_api.py
+# Copyright (C) 2014 LEAP
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Example of use of the soledad api.
+"""
+from __future__ import print_function
+import datetime
+import os
+
+from leap.soledad.client import sqlcipher
+from leap.soledad.client.sqlcipher import SQLCipherOptions
+
+
+folder = os.environ.get("TMPDIR", "tmp")
+times = int(os.environ.get("TIMES", "1000"))
+silent = os.environ.get("SILENT", False)
+
+tmpdb = os.path.join(folder, "test.soledad")
+
+
+def debug(*args):
+    if not silent:
+        print(*args)
+
+
+debug("[+] db path:", tmpdb)
+debug("[+] times", times)
+
+if os.path.isfile(tmpdb):
+    debug("[+] Removing existing db file...")
+    os.remove(tmpdb)
+
+start_time = datetime.datetime.now()
+
+opts = SQLCipherOptions(tmpdb, "secret", create=True)
+db = sqlcipher.SQLCipherDatabase(opts)
+
+
+def allDone():
+    debug("ALL DONE!")
+
+
+payload = open('manifest.phk').read()
+
+for i in range(times):
+    doc = {"number": i, "payload": payload}
+    d = db.create_doc(doc)
+    debug(d.doc_id, d.content['number'])
+
+debug("Count", len(db.get_all_docs()[1]))
+if silent:
+    end_time = datetime.datetime.now()
+    print((end_time - start_time).total_seconds())
+
+allDone()