Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Code Climate Test Coverage

PyPI Requirements Status


MongoCapsule is a very thin wrapper around MongoEngine built for your happiness. It encapsulates MongoEngine attributes under a single namespace and hence allows explicit declaration without context switches.

In addition to that, MongoCapsule adds pagination support to all the query results.

MongoEngine is a great ORM for using MongoDB in any Python project. However, since MongoEngine works in "contexts", using multiple databases requires trickery such as db_alias and switch_db. MongoCapsule solves this by attaching references to MongoEngine attributes to itself.


If you are familiar with MongoEngine, you can use MongoCapsule already! Create the database object and use it to define your document and fields.

from mongocapsule import MongoCapsule

db = MongoCapsule('test_db')

class Fruits(db.Document):
    name = db.StringField()

Refer to MongoEngine Docs for details.


To install use pip:

    pip install mongocapsule

Or clone the repo:

    git clone
    python install

Additional API

MongoCapsule adds Pagination support to the MongoEngine QuerySet object. It returns 10 objects per page, however, this can be changed.

# Obtain nth Page of any arbitrary query:

query_results = Document.objects(...).sort(...)

result_page =     # Obtain second page

total_pages = query_results.page_count

# Update number of items returned per page:



Code Patches, suggestions and bug reports welcome! Please use GitHub issues for the same.


I wrote this module because the examples in official MongoEngine documentation encourages using from mongoengine import * which not only pollutes the local namespace, but makes class definitions implicit. Of course, cherrypicked imports are possible, however that requires a lot of extra imports in each files.

The biggest problem, however, comes when you're using multiple databases or hosts -- in those cases, you need to use context switches or ugly meta attributes in the declaration.