Metadata-Version: 2.0
Name: jaraco.modb
Version: 3.5
Summary: MongoDB Object DataBase (MODB) for Python objects
Home-page: https://github.com/jaraco/jaraco.modb
Author: Jason R. Coombs
Author-email: jaraco@jaraco.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Requires-Dist: jsonpickle (>=0.9.2,<1dev)
Requires-Dist: pymongo
Requires-Dist: six

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>`_.

Manual Usage
------------

``jaraco.modb`` facilitates using `jsonpickle` to produce MongoDB-friendly
representations of pickleable Python objects for easy storage in a MongoDB
database.

One may simply encode and decode Python objects to MongoDB
BSON-friendly representations::

    class MyObject(object):
        def __init__(self, val):
            self.val = val

    import jaraco.modb
    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

A more detailed tutorial is now `published as an iPython Notebook
<http://nbviewer.ipython.org/urls/raw.githubusercontent.com/jaraco/jaraco.modb/master/tutorial.ipynb?create=1>`_.


Automatic Usage
---------------

``jaraco.modb`` also provides an SON Manipulator suitable for automatically
encoding arbitrary objects for a pymongo.Database::

    jaraco.modb.SONManipulator.install(mongo_collection.database)
    mongo_collection.save({'val': val})

Unfortunately, due to a limitation with the API of the SONManipulator,
it's not possible to save a custom object as the document itself (the
document must always be a dict).


