monguo 0.1

Asynchronous MongoDB ORM for Tornado

======
Monguo
======

.. image:: https://github.com/shiyanhui/monguo/blob/master/doc/source/_static/monguo.jpg?raw=true
:width: 200px

:Info: Monguo is a full-featured, asynchronous MongoDB_ ORM with Motor_ dirver for Tornado_ applications.
:Author: Lime YH.Shi

.. _MongoDB: http://mongodb.org/
.. _Motor: https://github.com/mongodb/motor/
.. _Tornado: http://tornadoweb.org/


About
=====

Monguo is an asynchronous MongoDB ORM based on driver Motor_. The `source is on GitHub <https://github.com/shiyanhui/monguo>`_ and the docs are on `ReadTheDocs <http://monguo.readthedocs.org/en/latest/>`_.

Issues / Questions / Feedback
=============================

You can open an issue on `GitHub <https://github.com/shiyanhui/monguo/issues>`_ or email me directly at [e-mail] if you have any question or feedback.

Installation
============

$ pip install monguo

Dependencies
============

Monguo works in all the environments officially supported by Tornado_ and Motor_. It requires:

* Unix, including Mac OS X. Microsoft Windows is not officially supported.
* PyMongo_
* Greenlet_
* Tornado_ 3.0+ (temporarily)
* Motor_ 0.1+ (temporarily)
* CPython 2.6, 2.7, 3.2, or 3.3
* PyPy 2.0 (greenlets were very slow in earlier PyPy versions)

Additional dependencies are:

- (to generate documentation) sphinx_

Examples
========

.. code-block:: python

class BookDocument(EmbeddedDocument):
name = StringField(required=True)
pages = IntegerField(required=True)


class SkillDocument(EmbeddedDocument):
name = StringField(required=True)


class PetDocument(Document):
name = StringField(required=True)
say = StringField()

meta = {
'collection': 'pet'
}


class UserDocument(Document):
name = StringField(required=True, unique=True)
sex = StringField(required=True, default='male')
age = IntegerField(required=True)
skills = ListField(DictField(SkillDocument), required=True)
book = EmbeddedDocumentField(BookDocument, required=True)
pet = ReferenceField(PetDocument)

meta = {
'collection': 'user'
}

def insert_user():
user = {
'name': 'Lime',
'age': 100,
'skills': [{'name': 'python'}, {'name': 'Web Programming'}],
'book': {'name': 'I am a bad guy', 'pages': '888'},
}
user_id = yield UserDocument.save(user)
raise gen.Return(user_id)


@gen.coroutine
def main():
Connection.connect('test')

pet_id = yield PetDocument.insert({'name': 'dog'})
pet = yield PetDocument.find_one({'_id': ObjectId(pet_id)})
print pet

user_id = yield UserDocument.insert_user()
user = yield UserDocument.find_one({'name': 'Lime'})
print user

dbref = DBRef(PetDocument.meta['collection'], ObjectId(pet_id))
yield UserDocument.update({'name': 'Lime'}, {'$set': {'pet': dbref}})
user = yield UserDocument.find_one({'name': 'Lime'})
print user

IOLoop.instance().run_sync(main)

The result:

.. code-block:: python

{u'_id': ObjectId('526208447379180fcb0dec0a'), u'name': u'dog'}

{u'name': u'Lime', u'skills': [{u'name': u'python'}, {u'name': u'Web Programming'}], u'age': 100L, u'sex': u'male', u'book': {u'name': u'I am a bad guy', u'pages': 888L}, u'_id': ObjectId('526208447379180fcb0dec0b')}

{u'name': u'Lime', u'pet': DBRef(u'pet', ObjectId('526208447379180fcb0dec0a')), u'age': 100L, u'sex': u'male', u'skills': [{u'name': u'python'}, {u'name': u'Web Programming'}], u'book': {u'name': u'I am a bad guy', u'pages': 888L}, u'_id': ObjectId('526208447379180fcb0dec0b')}


Documentation
=============

You will need sphinx_ installed to generate the documentation. Documentation
can be generated by running ``python setup.py doc``. Generated documentation
can be found in ``doc/build/html/``. You can read the current docs
at ReadTheDocs_.


.. _PyMongo: http://pypi.python.org/pypi/pymongo/
.. _MongoDB: http://mongodb.org/
.. _Tornado: http://tornadoweb.org/
.. _Motor: https://github.com/mongodb/motor/
.. _Greenlet: http://pypi.python.org/pypi/greenlet/
.. _ReadTheDocs: http://motor.readthedocs.org/
.. _sphinx: http://sphinx.pocoo.org/
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
.. _nose bug: https://github.com/nose-devs/nose/issues/556