API Documentation¶

Externals¶

The parts of the API described in this section are used to interact with a MongoDB database and define Documents.

Connecting to a MongoDB Server¶

class mango.Client(host=None, port=None, document_class=<class 'dict'>, tz_aware=False, connect=True, **kwargs)[source]¶

Drop-in replacement for pymongo.mongo_client.MongoClient.

When databases and collections are created from a Client, they are really instances of Mango’s Database and Collection classes.

Defining Documents¶

mango.assign(database, collection=None)[source]¶

A class decorator that assigns a type of document to a database/collection.

If collection is None, Mango generates a Collection automatically based on the name of the Document class. If collection is passed, it must have been generated from the database.

Parameters:	database (a `Database`) – collection (a `Collection`, optional) –

class mango.Document(**kwargs)[source]¶

The base class for any user-defined documents.

Document is a subclass of dict, with dot access to its keys.

There are two forbidden keys: '_id' and '_docname'. These are used internally to uniquely identify objects and to reconstruct raw data from the database, respectively.

Mango automatically generates a UUID for the Document to use as its _id, as well as a creation and modification timestamp.

id¶: str – A UUID, unique to the document, generated by Mango.

id_filter¶: dict – A dictionary: {'_id': self.id}.

docname¶: str – The name of the Document (i.e., the name of the class)

save()[source]¶

Save the Document to its assigned collection.

Returns:	result – A pymongo database write result object (see https://api.mongodb.com/python/current/api/pymongo/results.html)
Return type:	class:pymongo.results._WriteResult

find_matching(*keys, match_document_type=True)[source]¶

Find all documents in the collection that match this document on the values of the given keys.

Parameters:	keys (any number of `str`) – Found documents will match this document on these keys. match_document_type (optional, default True) – If True, found documents must match this document’s type as well. Equivalent to adding `'_docname'` to keys.
Returns:	cursor – A `Cursor` representing the results of the query.
Return type:	`Cursor`

find_self()[source]¶: Find this Document from the database. Shortcut for doc.find_matching('_id')[0].

classmethod find(**filters)[source]¶: Find all documents in the collection of this type, with additional filters given by the kwargs as if they were arguments to a dictionary used as Collection.find(filters).

mango.utils.filter_dict(dct, *keys)[source]¶

Filter a dictionary, including only the named keys.

Parameters:	dct (`dict`) – A dictionary. keys (any number of `str`) – These keys are extracted from d.
Returns:	filtered_d – A copy of d, but containing only the keys from keys.
Return type:	`dict`

mango.register(cls)[source]¶

A class decorator that “manually” registers a class for conversion when coming back from the database.

Parameters:	cls – The class to register.

Working with Documents¶

mango.save_many(*documents)[source]¶

Save many Documents to their associated collections.

This function performs a single bulk write operation for each unique collection among the documents.

Parameters:	documents (any number of `Documents`) – Documents to be saved.
Returns:	results_by_collection – A dictionary: `{collection: write_result}` (`pymongo.results.BulkWriteResult`).
Return type:	`dict`

Utilities¶

The parts of the API described in this section are peripheral helper functions.

mango.utils.run_mongodb(mongo_bin_path=None, dbpath=None, **kwargs)[source]¶

Start a MongoDB server using the data at dbpath, looking for the mongod executable in the dir mongo_bin_path.

If mongod is visible on your system path, pass an empty string (‘’) to mongo_bin_path. If dbpath is None, mango will attempt to find your MongoDB install based on the default location for your OS.

Parameters:	mongo_bin_path (`str`) – dbpath (`str`) – kwargs – Keyword arguments are passed to the `subprocess.Popen` constructor.
Returns:	process – The subprocess that the MongoDB server is running in.
Return type:	`subprocess.Popen`

Internals¶

The parts of the API described in this section are used internally by Mango but should not need to be referenced externally.

class mango.Database(client, name, codec_options=None, read_preference=None, write_concern=None, read_concern=None)[source]¶: Drop-in replacement for pymongo.database.Database.

class mango.Collection(database, name, create=False, codec_options=None, read_preference=None, write_concern=None, read_concern=None, **kwargs)[source]¶: Drop-in replacement for pymongo.collection.Collection.

class mango.Cursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=0, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, manipulate=True)[source]¶: Drop-in replacement for pymongo.cursor.Cursor.