Commits

Jason R. Coombs committed 2a3f926

Added readme

  • Participants
  • Parent commits 1e9889c
  • Tags 1.0.3

Comments (0)

Files changed (2)

+===========
+jaraco.modb
+===========
+
+.. contents::
+
+Overview
+--------
+
+``jaraco.modb`` is a small, pure-Python library for persisting Python
+objects to `MongoDB <http://www.mongodb.org/>`_.
+
+``jaraco.modb`` is written by Jason R. Coombs.  It is licensed under an
+`MIT-style permissive license
+<http://www.opensource.org/licenses/mit-license.php>`_.
+
+You can install it with ``easy_install jaraco.modb`` or grab the source
+code from the `mercurial repository
+<http://bitbucket.org/jaraco/jaraco.modb>`_.
+
+Usage
+-----
+
+``jaraco.modb`` facilitates using `jsonpickle` to produce MongoDB-friendly
+representations of pickleable Python objects for easy storage in a MongoDB
+database.
+
+The jsonpickle module requires initialization to use the backends supplied
+by jaraco.modb, so the application must first call `init()`::
+
+    import jaraco.modb
+    jaraco.modb.init()
+
+Thereafter, one can simply encode and decode Python objects to MongoDB
+BSON-friendly representations::
+
+    class MyObject(object):
+        def __init__(self, val):
+            self.val = val
+
+    import pymongo
+    mongo_collection = pymongo.Connection().mydb.mycollection
+    val = MyObject(3)
+    # save the object to the DB
+    id = mongo_collection.save(jaraco.modb.encode(val))
+    # retrieve the object from the DB
+    new_val = jaraco.modb.decode(mongo_collection.find_one(id))
+    assert isinstance(new_val, MyObject)
+    assert new_val.val == 3
+
+Changes
+-------
+
+1.0
+~~~
+
+* Initial release
 #!/usr/bin/env python
 # Generated by jaraco.develop (https://bitbucket.org/jaraco/jaraco.develop)
+import os
+
 from setuptools import find_packages
+
+with open(os.path.join(os.path.dirname(__file__), 'README')) as readme:
+	long_description = readme.read()
+
 setup_params = dict(
 	name='jaraco.modb',
 	description="MongoDB Object DataBase (MODB) for Python objects",
+	long_description=long_description,
 	use_hg_version=dict(increment='0.1'),
 	packages=find_packages(),
 	namespace_packages=['jaraco'],