Merge lp:~tribaal/u1db/u1db-docs-and-cleanup into lp:u1db

[Chris Glass]

This branch adds a little substance to the README file, as well as correcting some small inefficiencies/omissions (unused variable, undefined references).

Please don't hesitate to be ruthless when reviewing this, since this is my first contribution to the project.

[John A Meinel (jameinel)]

Dependencies are also mentioned in setup.py under 'install_requires' and 'tests_require'.

The other tweaks seem fine.

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2012-04-18 20:41:57 +0000
+++ .bzrignore	2012-05-10 19:17:27 +0000
@@ -10,3 +10,4 @@
 html-docs/_build/html
 u1db/tests/c_backend_wrapper.c
 ./src/u1db_schema.c
+.ropeproject

=== modified file 'README'
--- README	2011-12-20 12:15:00 +0000
+++ README	2012-05-10 19:17:27 +0000
@@ -1,8 +1,55 @@
+Getting started
+===============
+
+The easiest way to get started is to use "setup.py install", preferably
+in a virtualenv (although that's up to you).
+
+
+Using the database interface
+============================
+
+Inserting and retrieving documents::
+
+    import u1db
+    db = u1db.open(":memory:", create=True)
+    doc = db.create_doc('{"firstname": "Bob", "familyname": "Foo"}')
+    print "document id: %s" % doc.doc_id
+    print "document revision: %s" % doc.revision
+
+    doc2 = db.get_doc(doc.doc_id)
+    print (doc == doc2)
+
+Creating an index::
+
+    import u1db
+    db = u1db.open(":memory:", create=True)
+    # Indexes can be on a single field...
+    idx = db.create_index("firstname_idx", ["firstname"])
+    # ... or on several
+    idx2 = db_create_index("composed_idx", ["firstname", "familyname"])
+
+Querying using an index::
+
+    import u1db
+    db = u1db.open(":memory:", create=True)
+    doc = db.get_from_index("firstname_idx", [("Bob",)])
+    print doc
+    # You can of course get a range of documents using wildcards
+    docs = db.get_from_index("firstname_idx", [("Bo*",)])
+
+More information and comments can be found in the u1db/__init__.py file.
+
+
+Running the tests
+=================
+
+A simple `make check` should get you on the right tracks. The dependencies can
+be infered from the output.
+
+
 Building the docs
 =================
 
 cd html-docs
 make doctest # check that the code examples all still work
 make html # build HTML documentation at _build/html/index.html
-
-

=== modified file 'u1db/backends/sqlite_backend.py'
--- u1db/backends/sqlite_backend.py	2012-04-27 14:22:47 +0000
+++ u1db/backends/sqlite_backend.py	2012-05-10 19:17:27 +0000
@@ -130,7 +130,7 @@
         try:
             c.execute("SELECT value FROM u1db_config"
                       " WHERE name = 'sql_schema'")
-        except dbapi2.OperationalError, e:
+        except dbapi2.OperationalError:
             # The table does not exist yet
             val = None
         else:
@@ -583,7 +583,7 @@
             c.execute(SQL_INDEX_KEYS, (index,))
         except dbapi2.OperationalError, e:
             raise dbapi2.OperationalError(str(e) +
-                '\nstatement: %s\nargs: %s\n' % (statement, args))
+                '\nstatement: %s\nargs: %s\n' % (SQL_INDEX_KEYS, (index,)))
         res = c.fetchall()
         return [r[0] for r in res]
 
@@ -622,7 +622,6 @@
         return set([x[0] for x in c.fetchall()])
 
     def _evaluate_index(self, raw_doc, field):
-        val = raw_doc
         parser = query_parser.Parser()
         getter = parser.parse(field)
         return getter.get(raw_doc)