API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

Auth

class mongokit.auth.User(*args, **kwargs)

authorized_types = [<class 'dict'>, <class 'bson.objectid.ObjectId'>, <class 'bytes'>, <class 'datetime.datetime'>, <class 'float'>, <class 'bool'>, <class 'list'>, <class '_sre.SRE_Pattern'>, <class 'uuid.UUID'>, <class 'mongokit.schema_document.CustomType'>, <class 'bson.dbref.DBRef'>, <class 'NoneType'>, <class 'bson.code.Code'>, <class 'bson.binary.Binary'>, <class 'int'>, <class 'str'>]

del_email()

del_login()

del_password()

email

get_email()

get_login()

get_password()

Return the password hashed

login

password

Return the password hashed

required_fields = ['user.password', 'user.email']

save(*args, **kwargs)

set_email(email)

set_login(login)

set_password(password)

Hash password on the fly

structure = {'user': {'email': <class 'str'>, 'login': <class 'str'>, 'password': <class 'str'>}, '_id': <class 'str'>}

use_dot_notation = True

verify_password(password)

Check the password against existing credentials

Collection

class mongokit.collection.Collection(*args, **kwargs)

find(*args, **kwargs)

Query the database.

The spec argument is a prototype document that all results must match. For example:

>>> db.test.find({"hello": "world"})

only matches documents that have a key “hello” with value “world”. Matches can have other keys in addition to “hello”. The fields argument is used to specify a subset of fields that should be included in the result documents. By limiting results to a certain subset of fields you can cut down on network traffic and decoding time.

Raises TypeError if any of the arguments are of improper type. Returns an instance of Cursor corresponding to this query.

Parameters:

• spec (optional): a SON object specifying elements which must be present for a document to be included in the result set
• fields (optional): a list of field names that should be returned in the result set or a dict specifying the fields to include or exclude. If fields is a list “_id” will always be returned. Use a dict to exclude fields from the result (e.g. fields={‘_id’: False}).
• skip (optional): the number of documents to omit (from the start of the result set) when returning the results
• limit (optional): the maximum number of results to return
• timeout (optional): if True (the default), any returned cursor is closed by the server after 10 minutes of inactivity. If set to False, the returned cursor will never time out on the server. Care should be taken to ensure that cursors with timeout turned off are properly closed.
• snapshot (optional): if True, snapshot mode will be used for this query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query’s execution. For details, see the snapshot documentation.
• tailable (optional): the result of this find call will be a tailable cursor - tailable cursors aren’t closed when the last data is retrieved but are kept open and the cursors location marks the final document’s position. if more data is received iteration of the cursor will continue from the last document received. For details, see the tailable cursor documentation.
• sort (optional): a list of (key, direction) pairs specifying the sort order for this query. See sort() for details.
• max_scan (optional): limit the number of documents examined when performing the query
• as_class (optional): class to use for documents in the query result (default is document_class)
• slave_okay (optional): if True, allows this query to be run against a replica secondary.
• await_data (optional): if True, the server will block for some extra time before returning, waiting for more data to return. Ignored if tailable is False.
• partial (optional): if True, mongos will return partial results if some shards are down instead of returning an error.
• manipulate: (optional): If True (the default), apply any outgoing SON manipulators before returning.
• network_timeout (optional): specify a timeout to use for this query, which will override the MongoClient-level default
• read_preference (optional): The read preference for this query.
• tag_sets (optional): The tag sets for this query.
• secondary_acceptable_latency_ms (optional): Any replica-set member whose ping time is within secondary_acceptable_latency_ms of the nearest member may accept reads. Default 15 milliseconds. Ignored by mongos and must be configured on the command line. See the localThreshold option for more information.

Note

The manipulate parameter may default to False in a future release.

Note

The max_scan parameter requires server version >= 1.5.1

New in version 2.3: The tag_sets and secondary_acceptable_latency_ms parameters.

New in version 1.11+: The await_data, partial, and manipulate parameters.

New in version 1.8: The network_timeout parameter.

New in version 1.7: The sort, max_scan and as_class parameters.

Changed in version 1.7: The fields parameter can now be a dict or any iterable in addition to a list.

New in version 1.1: The tailable parameter.

added by mongokit::

• wrap (optional): a class object used to wrap

documents in the query result

find_and_modify(*args, **kwargs)

Update and return an object.

This is a thin wrapper around the findAndModify command. The positional arguments are designed to match the first three arguments to update() however most options should be passed as named parameters. Either update or remove arguments are required, all others are optional.

Returns either the object before or after modification based on new parameter. If no objects match the query and upsert is false, returns None. If upserting and new is false, returns {}.

If the full_response parameter is True, the return value will be the entire response object from the server, including the ‘ok’ and ‘lastErrorObject’ fields, rather than just the modified object. This is useful mainly because the ‘lastErrorObject’ document holds information about the command’s execution.

Parameters:

• query: filter for the update (default {})
• update: see second argument to update() (no default)
• upsert: insert if object doesn’t exist (default False)
• sort: a list of (key, direction) pairs specifying the sort order for this query. See sort() for details.
• full_response: return the entire response object from the server (default False)
• remove: remove rather than updating (default False)
• new: return updated rather than original object (default False)
• fields: see second argument to find() (default all)
• **kwargs: any other options the findAndModify command supports can be passed here.

Note

Requires server version >= 1.3.0

Changed in version 2.5: Added the optional full_response parameter

Changed in version 2.4: Deprecated the use of mapping types for the sort parameter

New in version 1.10.

added by mongokit::

• wrap (optional): a class object used to wrap

documents in the query result

find_fulltext(search, **kwargs)

Executes a full-text search. Additional parameters may be passed as keyword arguments.

find_random()

return one random document from the collection

get_from_id(id)

return the document which has the id

one(*args, **kwargs)

Connection

class mongokit.connection.CallableMixin

brings the callable method to a Document. usefull for the connection’s register method

class mongokit.connection.Connection(*args, **kwargs)

mongokit.connection.MongoClient

alias of Connection

class mongokit.connection.MongoKitConnection(*args, **kwargs)

register(obj_list)

mongokit.connection.MongoReplicaSetClient

alias of ReplicaSetConnection

class mongokit.connection.ReplicaSetConnection(*args, **kwargs)

Cursor

class mongokit.connection.CallableMixin

brings the callable method to a Document. usefull for the connection’s register method

class mongokit.connection.Connection(*args, **kwargs)

mongokit.connection.MongoClient

alias of Connection

class mongokit.connection.MongoKitConnection(*args, **kwargs)

register(obj_list)

mongokit.connection.MongoReplicaSetClient

alias of ReplicaSetConnection

class mongokit.connection.ReplicaSetConnection(*args, **kwargs)

Database

class mongokit.database.Database(*args, **kwargs)

dereference(dbref, model=None)

Document

class mongokit.document.Document(doc=None, gen_skel=True, collection=None, lang='en', fallback_lang='en')

atomic_save = False

authorized_types = [<class 'dict'>, <class 'bson.objectid.ObjectId'>, <class 'bytes'>, <class 'datetime.datetime'>, <class 'float'>, <class 'bool'>, <class 'list'>, <class '_sre.SRE_Pattern'>, <class 'uuid.UUID'>, <class 'mongokit.schema_document.CustomType'>, <class 'bson.dbref.DBRef'>, <class 'NoneType'>, <class 'bson.code.Code'>, <class 'bson.binary.Binary'>, <class 'int'>, <class 'str'>]

delete()

delete the document from the collection from his _id.

fetch(spec=None, *args, **kwargs)

return all document which match the structure of the object fetch() takes the same arguments than the the pymongo.collection.find method.

The query is launch against the db and collection of the object.

fetch_one(*args, **kwargs)

return one document which match the structure of the object fetch_one() takes the same arguments than the the pymongo.collection.find method.

If multiple documents are found, raise a MultipleResultsFound exception. If no document is found, return None

The query is launch against the db and collection of the object.

find(*args, **kwargs)

Query the database.

The spec argument is a prototype document that all results must match. For example if self si called MyDoc:

>>> mydocs = db.test.MyDoc.find({"hello": "world"})

only matches documents that have a key “hello” with value “world”. Matches can have other keys in addition to “hello”. The fields argument is used to specify a subset of fields that should be included in the result documents. By limiting results to a certain subset of fields you can cut down on network traffic and decoding time.

mydocs is a cursor which yield MyDoc object instances.

See pymongo’s documentation for more details on arguments.

find_and_modify(*args, **kwargs)

Update and return an object.

find_fulltext(search, **kwargs)

Executes a full-text search. Additional parameters may be passed as keyword arguments.

find_one(*args, **kwargs)

Get the first object found from the database.

See pymongo’s documentation for more details on arguments.

find_random()

return one random document from the collection

force_autorefs_current_db = False

from_json(json)

convert a json string and return a SchemaDocument

classmethod generate_index(collection)

generate indexes from indexes class-attribute

supports additional index-creation-keywords supported by pymongos ensure_index.

get_dbref()

return a pymongo DBRef instance related to the document

get_from_id(id)

return the document which has the id

get_size()

return the size of the underlying bson object

gridfs = []

indexes = []

migrate(safe=True, _process_to_bson=True)

migrate the document following the migration_handler rules

safe : if True perform a safe update (see pymongo documentation for more details

migration_handler = None

one(*args, **kwargs)

one() act like find() but will raise a mongokit.MultipleResultsFound exception if there is more than one result.

If no document is found, one() returns None

reload()

allow to refresh the document, so after using update(), it could reload its value from the database.

Be careful : reload() will erase all unsaved values.

If no _id is set in the document, a KeyError is raised.

save(uuid=False, validate=None, safe=True, *args, **kwargs)

save the document into the db.

if uuid is True, a uuid4 will be automatically generated else, the bson.ObjectId will be used.

If validate is True, the validate method will be called before saving. Not that the validate method will be called before the uuid is generated.

save() follow the pymongo.collection.save arguments

skip_validation = False

to_json()

convert the document into a json string and return it

to_json_type()

convert all document field into json type and return the new converted object

type_field = '_type'

use_autorefs = False

validate(auto_migrate=False)

class mongokit.document.DocumentProperties

class mongokit.document.R(doc, connection, fallback_database=None)

CustomType to deal with autorefs documents

mongo_type

alias of DBRef

python_type

alias of Document

to_bson(value)

to_python(value)

Grid

class mongokit.grid.FS(obj)

get_version(filename, version=-1, **kwargs)

Get a file from GridFS by "filename" or metadata fields.

Returns a version of the file in GridFS whose filename matches filename and whose metadata fields match the supplied keyword arguments, as an instance of GridOut.

Version numbering is a convenience atop the GridFS API provided by MongoDB. If more than one file matches the query (either by filename alone, by metadata fields, or by a combination of both), then version -1 will be the most recently uploaded matching file, -2 the second most recently uploaded, etc. Version 0 will be the first version uploaded, 1 the second version, etc. So if three versions have been uploaded, then version 0 is the same as version -3, version 1 is the same as version -2, and version 2 is the same as version -1.

Raises NoFile if no such version of that file exists.

An index on {filename: 1, uploadDate: -1} will automatically be created when this method is called the first time.

Parameters:

• filename: "filename" of the file to get, or None
• version (optional): version of the file to get (defaults to -1, the most recent version uploaded)
• **kwargs (optional): find files by custom metadata.

Changed in version 1.11: filename defaults to None;

New in version 1.11: Accept keyword arguments to find files by custom metadata.

New in version 1.9.

new_file(filename)

put(data, **kwargs)

class mongokit.grid.FSContainer(container_name, obj)

Helpers

class mongokit.helpers.DotCollapsedDict(passed_dict, remove_under_type=False, reference=None)

A special dictionary constructor that take a dict and provides a dot collapsed dict:

>>> DotCollapsedDict({'a':{'b':{'c':{'d':3}, 'e':5}, "g":2}, 'f':6})
{'a.b.c.d': 3, 'a.b.e': 5, 'a.g': 2, 'f': 6}

>>> DotCollapsedDict({'bla':{'foo':{unicode:{"bla":3}}, 'bar':'egg'}})
{'bla.foo.$unicode.bla': 3, 'bla.bar': "egg"}

>>> DotCollapsedDict({'bla':{'foo':{unicode:{"bla":3}}, 'bar':'egg'}}, remove_under_type=True)
{'bla.foo':{}, 'bla.bar':unicode}

>>> dic = {'bar':{'foo':3}, 'bla':{'g':2, 'h':3}}
>>> DotCollapsedDict(dic, reference={'bar.foo':None, 'bla':{'g':None, 'h':None}})
{'bar.foo':3, 'bla':{'g':2, 'h':3}}

class mongokit.helpers.DotExpandedDict(key_to_list_mapping)

A special dictionary constructor that takes a dictionary in which the keys may contain dots to specify inner dictionaries. It’s confusing, but this example should make sense.

>>> d = DotExpandedDict({'person.1.firstname': ['Simon'],           'person.1.lastname': ['Willison'],           'person.2.firstname': ['Adrian'],           'person.2.lastname': ['Holovaty']})
>>> d
{'person': {'1': {'lastname': ['Willison'], 'firstname': ['Simon']},
'2': {'lastname': ['Holovaty'], 'firstname': ['Adrian']}}}
>>> d['person']
{'1': {'lastname': ['Willison'], 'firstname': ['Simon']}, '2': {'lastname': ['Holovaty'], 'firstname': ['Adrian']}}
>>> d['person']['1']
{'lastname': ['Willison'], 'firstname': ['Simon']}

# Gotcha: Results are unpredictable if the dots are “uneven”: >>> DotExpandedDict({‘c.1’: 2, ‘c.2’: 3, ‘c’: 1}) {‘c’: 1}

class mongokit.helpers.DotedDict(doc=None, warning=False)

Dot notation dictionary access

mongokit.helpers.fromtimestamp(epoch_date)

convert a float since epoch to a datetime object

class mongokit.helpers.i18nDotedDict(dic, doc)

Dot notation dictionary access with i18n support

mongokit.helpers.totimestamp(value)

convert a datetime into a float since epoch

Master Slave Connection

Master-Slave integration with for MongoKit Andreas Jung, info@zopyx.com (same license as Mongokit)

class mongokit.master_slave_connection.MasterSlaveConnection(master, slaves=[])

Master-Slave support for MongoKit

Migration

class mongokit.migration.DocumentMigration(doc_class)

clean()

get_deprecated(collection)

migrate(doc, safe=True)

migrate the doc through all migration process

migrate_all(collection, safe=True)

validate_update(update_query)

Migration

exception mongokit.mongo_exceptions.AutoReferenceError

exception mongokit.mongo_exceptions.BadIndexError

exception mongokit.mongo_exceptions.ConnectionError

exception mongokit.mongo_exceptions.EvalException

exception mongokit.mongo_exceptions.MaxDocumentSizeError

exception mongokit.mongo_exceptions.MongoAuthException

exception mongokit.mongo_exceptions.MultipleResultsFound

exception mongokit.mongo_exceptions.OptionConflictError

exception mongokit.mongo_exceptions.UpdateQueryError

Operators

class mongokit.operators.IS(*args)

repr = 'is'

validate(value)

class mongokit.operators.NOT(*args)

repr = 'not'

validate(value)

class mongokit.operators.OR(*args)

repr = 'or'

validate(value)

class mongokit.operators.SchemaOperator(*args)

repr = None

validate(value)

Paginator

class mongokit.paginator.Paginator(cursor, page=1, limit=10)

Provides pagination on a Cursor object

Keyword arguments: cursor – Cursor of a returned query page – The page number requested limit – The number of items per page

Properties: items – Returns the paginated Cursor object is_paginated – Boolean value determining if the cursor has multiple pages start_index – int index of the first item on the requested page end_index – int index of the last item on the requested page current_page – int page number of the requested page previous_page– int page number of the previous page w.r.t. current requested page next_page – int page number of the next page w.r.t. current requested page has_next – True or False if the Cursor has a next page has_previous – True or False if the Cursor has a previous page page_range – list of page numbers num_pages – int of the number of pages count – int total number of items on the cursor

count

current_page

end_index

has_next

has_previous

is_paginated

items

next_page

num_pages

page_range

previous_page

start_index

Schema Document

exception mongokit.schema_document.AuthorizedTypeError

exception mongokit.schema_document.BadKeyError

class mongokit.schema_document.CustomType

init_type = None

mongo_type = None

python_type = None

to_bson(value)

convert type to a mongodb type

to_python(value)

convert type to a mongodb type

validate(value, path)

This method is optional. It add a validation layer. This method is been called in Document.validate()

value: the value of the field path: the field name (ie, ‘foo’ or ‘foo.bar’ if nested)

exception mongokit.schema_document.DefaultFieldTypeError

class mongokit.schema_document.DotCollapsedDict(passed_dict, remove_under_type=False, reference=None)

A special dictionary constructor that take a dict and provides a dot collapsed dict:

>>> DotCollapsedDict({'a':{'b':{'c':{'d':3}, 'e':5}, "g":2}, 'f':6})
{'a.b.c.d': 3, 'a.b.e': 5, 'a.g': 2, 'f': 6}

>>> DotCollapsedDict({'bla':{'foo':{unicode:{"bla":3}}, 'bar':'egg'}})
{'bla.foo.$unicode.bla': 3, 'bla.bar': "egg"}

>>> DotCollapsedDict({'bla':{'foo':{unicode:{"bla":3}}, 'bar':'egg'}}, remove_under_type=True)
{'bla.foo':{}, 'bla.bar':unicode}

>>> dic = {'bar':{'foo':3}, 'bla':{'g':2, 'h':3}}
>>> DotCollapsedDict(dic, reference={'bar.foo':None, 'bla':{'g':None, 'h':None}})
{'bar.foo':3, 'bla':{'g':2, 'h':3}}

class mongokit.schema_document.DotedDict(doc=None, warning=False)

Dot notation dictionary access

class mongokit.schema_document.DotExpandedDict(key_to_list_mapping)

A special dictionary constructor that takes a dictionary in which the keys may contain dots to specify inner dictionaries. It’s confusing, but this example should make sense.

>>> d = DotExpandedDict({'person.1.firstname': ['Simon'],           'person.1.lastname': ['Willison'],           'person.2.firstname': ['Adrian'],           'person.2.lastname': ['Holovaty']})
>>> d
{'person': {'1': {'lastname': ['Willison'], 'firstname': ['Simon']},
'2': {'lastname': ['Holovaty'], 'firstname': ['Adrian']}}}
>>> d['person']
{'1': {'lastname': ['Willison'], 'firstname': ['Simon']}, '2': {'lastname': ['Holovaty'], 'firstname': ['Adrian']}}
>>> d['person']['1']
{'lastname': ['Willison'], 'firstname': ['Simon']}

# Gotcha: Results are unpredictable if the dots are “uneven”: >>> DotExpandedDict({‘c.1’: 2, ‘c.2’: 3, ‘c’: 1}) {‘c’: 1}

exception mongokit.schema_document.DuplicateDefaultValueError

exception mongokit.schema_document.DuplicateRequiredError

class mongokit.schema_document.i18n(field_type=None, field_name=None)

CustomType to deal with i18n

mongo_type

alias of list

to_bson(value)

to_python(value)

exception mongokit.schema_document.i18nError

exception mongokit.schema_document.ModifierOperatorError

exception mongokit.schema_document.RequireFieldError

class mongokit.schema_document.SchemaDocument(doc=None, gen_skel=True, _gen_auth_types=True, _validate=True, lang='en', fallback_lang='en')

A SchemaDocument is dictionary with a building structured schema The validate method will check that the document match the underling structure. A structure must be specify in each SchemaDocument.

>>> class TestDoc(SchemaDocument):
...     structure = {
...         "foo":six.text_type,
...         "bar":int,
...         "nested":{
...            "bla":float}}

unicode, int, float are python types listed in mongokit.authorized_types.

>>> doc = TestDoc()
>>> doc
{'foo': None, 'bar': None, 'nested': {'bla': None}}

A SchemaDocument works just like dict:

>>> doc['bar'] = 3
>>> doc['foo'] = "test"

We can describe fields as required with the required attribute:

>>> TestDoc.required_fields = ['bar', 'nested.bla']
>>> doc = TestDoc()
>>> doc['bar'] = 2

Validation is made with the validate() method:

>>> doc.validate()  
Traceback (most recent call last):
...
RequireFieldError: nested.bla is required

Default values can be set by using the attribute default_values :

>>> TestDoc.default_values = {"bar":3, "nested.bla":2.0}
>>> doc = TestDoc()
>>> doc
{'foo': None, 'bar': 3, 'nested': {'bla': 2.0}}
>>> doc.validate()

Validators can be added in order to validate some values :

>>> TestDoc.validators = {"bar":lambda x: x>0, "nested.bla": lambda x: x<0}
>>> doc = TestDoc()
>>> doc['bar'] = 3
>>> doc['nested']['bla'] = 2.0
>>> doc.validate()
Traceback (most recent call last):
...
ValidationError: nested.bla does not pass the validator <lambda>

If you want to use the dot notation (ala json), you must set the use_dot_notation attribute to True:

>>> class TestDotNotation(SchemaDocument):
...     structure = {
...         "foo":{ "bar":unicode}
...     }
...     use_dot_notation=True

>>> doc = TestDotNotation()
>>> doc.foo.bar = u"bla"
>>> doc
{"foo":{"bar":u"bla}}

authorized_types = [<class 'NoneType'>, <class 'bool'>, <class 'int'>, <class 'float'>, <class 'list'>, <class 'dict'>, <class 'datetime.datetime'>, <class 'bson.binary.Binary'>, <class 'mongokit.schema_document.CustomType'>, <class 'str'>, <class 'bytes'>]

default_values = {}

dot_notation_warning = False

generate_skeleton()

validate and generate the skeleton of the document from the structure (unknown values are set to None)

get_lang()

i18n = []

raise_validation_errors = True

required_fields = []

set_lang(lang)

skip_validation = False

structure = None

use_dot_notation = False

use_schemaless = False

validate()

validate the document.

This method will verify if :

• the doc follow the structure,
• all required fields are filled

Additionally, this method will process all validators.

validators = {}

exception mongokit.schema_document.SchemaDocumentError

class mongokit.schema_document.SchemaProperties

exception mongokit.schema_document.SchemaTypeError

class mongokit.schema_document.Set(structure_type=None)

SET custom type to handle python set() type

init_type

alias of set

mongo_type

alias of list

python_type

alias of set

to_bson(value)

to_python(value)

validate(value, path)

exception mongokit.schema_document.StructureError

exception mongokit.schema_document.ValidationError

Versioned Document

class mongokit.versioned_document.RevisionDocument(doc=None, gen_skel=True, collection=None, lang='en', fallback_lang='en')

structure = {'id': <class 'str'>, 'revision': <class 'int'>, 'doc': <class 'dict'>}

class mongokit.versioned_document.VersionedDocument(doc=None, *args, **kwargs)

This object implement a vesionnized mongo document

delete(versioning=False, *args, **kwargs)

if versioning is True delete revisions documents as well

get_last_revision_id()

get_revision(revision_number)

get_revisions()

remove(query, versioning=False, *args, **kwargs)

if versioning is True, remove all revisions documents as well. Be careful when using this method. If your query match tons of documents, this might be very very slow.

save(versioning=True, *args, **kwargs)