====== MongoEngine ======
It's a MongoDB ORM for Python.
===== First steps =====
==== Installation and import ====
<code>
$ pip install mongoengine
</code>
To start using MongoEngine we will import like this:
<code python>
import mongoengine
</code>
==== Connecting to a DB ====
To connect a DB we will use the ''connect'' function, its first argument is the DB:
<code python>
connect('project1')
connect('project1', host='192.168.1.35', port=12345)
connect('project1', username='webapp', password='pwd123')
connect('project1', host='mongodb://localhost/database_name')
</code>
===== Defining the schema =====
==== In a nutshell ====

Next schema implements a Blog where a User can create different type Posts. Those types are inherited classes from Post.
<code python>
class User(Document):
    email = StringField(required=True)
    first_name = StringField(max_length=50)
    last_name = StringField(max_length=50)

class Post(Document):
    title = StringField(max_length=120, required=True)
    author = ReferenceField(User)
    meta = {'allow_inheritance': True}

class TextPost(Post):
    content = StringField()

class ImagePost(Post):
    image_path = StringField()

class LinkPost(Post):
    link_url = StringField()
</code>  

=== Other field objects ===
  * ''tags = ListField(StringField(max_length=30))'', a ''ListField'' is a field object that allows to have a list of other field objects (including other lists).
  * ''date_modified = DateTimeField(default=datetime.datetime.now)''
More about this subject in: [[http://docs.mongoengine.org/guide/defining-documents.html#fields]]
==== Storing an object ====
<code python>
Comment.objects.create(text='Me gusta!')
</code>
==== Storing an object inside another ====
<code python>
class Comment(EmbeddedDocument):
    content = StringField()
    name = StringField(max_length=120)

class Post(Document):
    title = StringField(max_length=120, required=True)
    author = ReferenceField(User)
    tags = ListField(StringField(max_length=30))
    comments = ListField(EmbeddedDocumentField(Comment))
</code>
We also could use ''GenericReferenceField'' to reference any kind of document:
<code python>
class Bookmark(Document):
    bookmark_object = GenericReferenceField()
</code>
==== Cascade delete ====
When we define a ''ReferenceField'' we can indicate ''reverse_delete_rule=CASCADE'' to delete all the objects when a referenced object is deleted (it does not work with MapFields neither DictFields).
<code python>
class Post(Document):
    title = StringField(max_length=120, required=True)
    author = ReferenceField(User, reverse_delete_rule=CASCADE)
    tags = ListField(StringField(max_length=30))
    comments = ListField(EmbeddedDocumentField(Comment))
</code>
Other constans we can pass:
  * ''mongoengine.DO_NOTHING''
  * ''mongoengine.DENY''
  * ''mongoengine.NULLIFY''
  * ''mongoengine.CASCADE''
  * ''mongoengine.PULL''
==== Dynamic documents ====
DynamicDocument documents work like Document but any data or attributes set to them will also be saved (fields cannot start with _ ).
<code>
from mongoengine import *

class Page(DynamicDocument):
    title = StringField(max_length=200, required=True)

# Create a new page and add tags
page = Page(title='Using MongoEngine')
page.tags = ['mongodb', 'mongoengine']
page.save()
</code>
==== Defining constraints ====
We can specify field uniqueness with ''unique=True'' and multi-fielduniqueness with ''unique_with'' (for a field name, or a list, or a tuple):
<code python>
class User(Document):
    username = StringField(unique=True)
    first_name = StringField()
    last_name = StringField(unique_with='first_name')
</code>
===== Editing Data =====
==== Adding documents ====

<code python>
ross = User(email='ross@example.com', first_name='Ross', last_name='Lawley').save()

# this is other way to save ross 
ross1 = User(email='ross1@example.com')
ross1.first_name = 'Ross1'
ross1.last_name = 'Lawley'
ross1.save()

post1 = TextPost(title='Fun with MongoEngine', author=john)
post1.content = 'Took a look at MongoEngine today, looks pretty cool.'
post1.tags = ['mongodb', 'mongoengine']
post1.save()

post2 = LinkPost(title='MongoEngine Documentation', author=ross)
post2.link_url = 'http://docs.mongoengine.com/'
post2.tags = ['mongoengine']
post2.save()
</code>
===== Accessing data =====
A ''Document'' object is actually a ''QuerySet'' object. It lazily queries the database when you need the data. ''QuerySet'' objects perform searches on the data base using functions like...
  * ''first()'' to retrieve the first object that matches with the provided query.
  * ''count()'' to know the number of objects that matche with the provided query.
==== Examples ====
=== Retrieving all the post titles ===
<code python>
for post in Post.objects:
    print post.title
</code>
=== Retrieving a concrete type content ===
<code python>
for post in TextPost.objects:
    print post.content
</code>
=== Searching by tag ===
<code python>
for post in Post.objects(tags='mongodb'):
    print post.title
</code>

===== Others =====

==== Django support ====
=== Connecting ===
You only need to call ''connect()'' somewhere in the settings module.

If you were not using another Database backend you may need to add a dummy database:
<code python>
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.dummy'
    }
}
</code>

=== Users ===
Django authentication classes are included as Document classes so they are compatible. To enable them you should add the following to your settings.py file:
<code python>
AUTHENTICATION_BACKENDS = (
    'mongoengine.django.auth.MongoEngineBackend',
)
</code>
Remember to call ''set_password()'' method in ''User'' class when assign a password value:
<code python>
instance.set_password(attrs.get('password', instance.password))
</code>