Usage

import mongoengine
from mongoengine_mate import ExtendedDocument

class User(ExtendedDocument):
    id = mongoengine.IntField()
    name = mongoengine.StringField()

First, you got better __repr__() like:

>>> User(id=1, name="Alice")
User(id=1, name="Alice")

# access its collection or database
>>> col_user = User.col()
>>> col_user.find({"_id": 1})
>>> col_db = User.db()

# access its field name in order
>>> User.fields_ordered()
["id", "name"]

# provide dictionary-like api
>>> user = User(id=1, name="Alice")
>>> user.keys()
["id", "name"]

>>> user.values()
[1, "Alice"]

>>> user.items()
[("id", "name"), (1, "Alice")]

>>> user.to_dict()
{"id": 1, "name": "Alice"}

>>> user.to_OrderedDict()
OrderedDict([("id", "name"), (1, "Alice")])

Smart Insert - Skip Primary Key Conflict

When you do batch insert, sometimes one or a few documents may cause _id field conflict error, which is breaking the batch insert operation.

Usually you have to write a for loop` and use ``try ... except ... to ignore conflict. But, it is SLOW!

ExtendedDocument.smart_insert provides a fast and convenient way to batch insert lots of document at once correctly.

# insert one document which breaks the batch insert
User(id=100, name="Obama").save()

# smart_insert, automatically handle NotUniqueError
User.smart_insert([
    User(id=1, name="Alice"),
    User(id=2, name="Bob"),
    ...
    User(id=1000, name="Zillow"),
])

Smart Update - Batch Upsert

When you do batch update, you mostly want to use the _id field to locate which document you want to update.

>>>User(id=2, name="Bob").save()

# update only
>>> User.smart_update([
    User(id=1, name="Alice"),
    User(id=2, name="Bruce"),
    User(id=3, name="Cathy"),
], upsert=False)
>>> User.objects.count()
1

# upsert
>>> User.smart_update([
    User(id=1, name="Alice"),
    User(id=2, name="Bruce"),
    User(id=3, name="Cathy"),
], upsert=True)
>>> User.objects.count()
3

Install

mongoengine_mate is released on PyPI, so all you need is:

$ pip install mongoengine_mate

To upgrade to latest version:

$ pip install --upgrade mongoengine_mate