make a README to satisfy github

1 files changed, 107 insertions, 0 deletions

diff --git a/README.mdwn b/README.mdwn
new file mode 100644
index 0000000..2e23413
--- /dev/null
+++ b/README.mdwn
@@ -0,0 +1,107 @@
+withsqlite - uses an sqlite db as a back end for a dict-like object,
+kind of like shelve but with json and sqlite3.
+
+Copyright 2011-2013 James Vasile
+Released under the GNU General Public License, version 3 or later.
+See https://www.gnu.org/licenses/gpl-3.0.html for terms.
+
+Repo is at <http://github.com/jvasile/withsqlite>.  Patches welcome!
+
+This file was developed as part of planeteria <http://github.com/jvasile/planeteria>
+
+
+Backends a dict on an sqlite db.  This class aims to present like a
+dict wherever it can.
+
+USE:
+import sqlite_db from withsqlite
+with sqlite_db("filename") as db:
+   db['aaa'] = {'test':'ok'}
+   print db.items()
+
+Specify a table to have one sqlite db hold multiple dicts:
+
+with sqlite_db("filename", table="fruit") as db:
+   db['citrus'] = ['orange', 'grapefruit']
+   print db.items()
+
+If you change the dict in any way, its state will differ from the
+state of the sqlite database.  Changes are committed to disk when you
+close the database connection, manually call commit, or (if you've set
+autocommit to True) after each assignment.
+
+BUGS:
+
+vals are json serialized before being written, so if you can't
+serialize it, you can't put it in the dict.
+
+Unimplemented mapping API: 
+a.copy() 	a (shallow) copy of a 	
+a.update([b]) 	updates a with key/value pairs from b, overwriting existing keys, returns None 
+a.fromkeys(seq[, value]) 	Creates a new dictionary with keys from seq and values set to value 
+a.setdefault(k[, x]) 	a[k] if k in a, else x (also setting it)
+a.pop(k[, x]) 	a[k] if k in a, else x (and remove k)
+a.popitem() 	remove and return an arbitrary (key, value) pair 
+a.iteritems() 	return an iterator over (key, value) pairs
+a.iterkeys() 	return an iterator over the mapping's keys
+a.itervalues() 	return an iterator over the mapping's values
+
+TODO: implement that mapping API
+
+>>> with sqlite_db("test") as db:
+...    db.clear()
+...    db.items()
+... 
+[]
+>>> with sqlite_db("test") as db:
+...    db['a']="test"
+...    db.items()
+... 
+[(u'a', u'test')]
+>>> with sqlite_db("test") as db:
+...    db['as']="test"
+...    db.items()
+... 
+[(u'a', u'test'), (u'as', u'test')]
+>>> with sqlite_db("test") as db:
+...    db['b']=[1,2,3,4,5]
+...    del db['b']
+... 
+>>> with sqlite_db("test") as db:
+...    db.items()
+...    len(db)
+... 
+[(u'a', u'test'), (u'as', u'test')]
+2
+>>> with sqlite_db("test") as db:
+...    db.keys()
+... 
+[u'a', u'as']
+>>> with sqlite_db("test") as db:
+...    db.values()
+... 
+[u'test', u'test']
+>>> with sqlite_db("test") as db:
+...    db.get('b',5)
+... 
+5
+>>> with sqlite_db("test") as db:
+...    db.get('b')
+... 
+>>> with sqlite_db("test") as db:
+...    db.get('c',5)
+... 
+5
+>>> with sqlite_db("test") as db:
+...    'as' in db
+... 
+True
+>>> with sqlite_db("test") as db:
+...    'asdf' not in db
+... 
+True
+>>> with sqlite_db("test") as db:
+...    db.has_key('as')
+...
+True
+>>>