Module motor_odm.document

This module contains the base class for interacting with Motor-ODM: Document. The Document class is the main entry point to Motor-ODM and provides its main interface.

class motor_odm.document.Document(**data: Any)

Bases: pydantic.main.BaseModel

This is the base class for all documents defined using Motor-ODM.

A Document is a pydantic model that can be inserted into a MongoDB collection. This class provides an easy interface for interacting with the database. Each document has an Document.id (named _id in MongoDB) by default by which it can be uniquely identified in the database. The name of this field cannot be customized however you can override it if you don’t want to use ObjectID values for your IDs.

Parameters

abstract – Mark subclasses as abstract in order to create an abstract document. An abstract document cannot be instantiated but can be subclassed. This enables you to extract common functionality from multiple documents into a common abstract super-document.

classmethod collection() → motor.core.AgnosticCollection

Returns the collection for this Document.

The collection uses the codec_options, read_preference, write_concern and read_concern from the document’s `Mongo` class.

async classmethod count_documents(filter: Mapping = None, *args: Any, **kwargs: Any) → int

Returns the number of documents in this class’s collection.

This method is filterable.

classmethod db() → motor.core.AgnosticDatabase

Returns the database that is currently associated with this document.

If no such database exists this returns the database of the parent document (its superclass). If no Document class had its use() method called to set a db, an AttributeError is raised.

async delete(*args: Any, **kwargs: Any) → bool

Deletes the document from the database.

This method does not modify the instance in any way. args and kwargs are passed to motor’s delete_one method.

Returns

True if the document was deleted.

async classmethod delete_many(*objects: GenericDocument) → int

Deletes all specified objects.

Parameters

objects – All objects to be deleted.

Returns

The number of documents deleted.

classmethod find(filter: DictStrAny = None, *args: Any, **kwargs: Any) → AsyncIterator[GenericDocument]

Returns an iterable over a cursor returning documents matching filter.

args and kwargs are passed to motor’s find method.

async classmethod find_one(filter: DictStrAny = None, *args: Any, **kwargs: Any) → Optional[GenericDocument]

Returns a single document from the collection.

async classmethod find_one_and_delete(filter: DictStrAny = None, *args: Any, **kwargs: Any) → Optional[GenericDocument]

Finds a document and deletes it.

This method works exactly like pymongo’s find_one_and_delete except that this returns a Document instance.

async classmethod find_one_and_replace(filter: DictStrAny, replacement: Union[DictStrAny, GenericDocument], return_document: bool = False, *args: Any, **kwargs: Any) → Optional[GenericDocument]

Finds a document and replaces it.

This method works exactly like pymongo’s find_one_and_replace except that this returns a Document instance. Note that if you specify return_document=ReturnDocument.AFTER this method will reload the replacement document.

async classmethod find_one_and_update(filter: DictStrAny, update: DictStrAny, *args: Any, **kwargs: Any) → Optional[GenericDocument]

Finds a document and updates it.

This method works exactly like pymongo’s find_one_and_update except that this returns a Document instance.

async classmethod init_indexes(drop: bool = True, session: motor.core.AgnosticClientSession = None, **kwargs: Any) → None

Creates the indexes for this collection of documents.

The indexes are specified in the indexes field of the Mongo class. By default this method makes sure that after the coroutine completes the collection’s indexes equal the specified indexes. If you do not want to drop existing indexes you can specify drop=True as keyword argument. Note however that this method will always override existing indexes.

Parameters

• drop – If True all indexes not specified by this collection will be dropped. Default is True.

• session – A session to use for any database actions.

• kwargs – Any keyword arguments are passed to the DB calls. This may be used to specify timeouts etc.

async insert(*args: Any, **kwargs: Any) → bool

Inserts the object into the database.

The object is inserted as a new object. If the document already exists this method will raise an error. Use save() instead if you want to update an existing value.

async classmethod insert_many(*objects: GenericDocument, **kwargs: Any) → None

Inserts multiple documents at once.

It is preferred to use this method over multiple insert() calls as the performance can be much better.

mongo(*, include: Union[AbstractSetIntStr, DictIntStrAny] = None, exclude: Union[AbstractSetIntStr, DictIntStrAny] = None) → DictStrAny

Converts this object into a dictionary suitable to be saved to MongoDB.

async reload(*args: Any, **kwargs: Any) → bool

Reloads a document from the database.

Use this method if a model might have changed in the database and you need to retrieve the current version. You do not need to call this after inserting a newly created object into the database.

async save(upsert: bool = True, *args: Any, **kwargs: Any) → bool

Saves this instance to the database.

By default this method creates the document in the database if it doesn’t exist. If you don’t want this behavior you can pass upsert=False.

Any args and kwargs are passed to motor’s replace_one method.

Parameters

upsert – Whether to create the document if it doesn’t exist.

Returns

True if the document was inserted/updated, False if nothing changed. This may also indicate that the document was not changed.

classmethod use(db: motor.core.AgnosticDatabase) → None

Sets the database to be used by this Document.

The database will also be used by subclasses of this class unless they use() their own database. This method has to be invoked before the ODM class can be used.

id: ObjectId = None

The document’s ID in the database.

By default this field is of type ObjectId but it can be overridden to supply your own ID types. Note that if you intend to override this field you must set its alias to _id in order for your IDs to be recognized as such by MongoDB.

class motor_odm.document.Mongo

Bases: object

This class defines the defaults for collection configurations.

Each collection (defined by a subclass of Document) can override these using an inner class named Mongo. Attributes are implicitly and transitively inherited from the Mongo classes of base classes.

abstract: bool = False

Whether the document is abstract.

The value for this field cannot be specified in the Mongo class but as a keyword argument on class creation.

codec_options: Optional[bson.codec_options.CodecOptions] = None

The codec options to use when accessing the collection.

Defaults to the database’s codec_options.

collection: Optional[str] = None

The name of the collection for a document. This attribute is required.

indexes: List[pymongo.operations.IndexModel] = []

A list of indexes to create for the collection.

read_concern: Optional[pymongo.read_concern.ReadConcern] = None

The read concern to use when accessing the collection.

Defaults to the database’s read_concern.

read_preference: Optional[pymongo.read_preferences.ReadPreference] = None

The read preference to use when accessing the collection.

Defaults to the database’s read_preference.

write_concern: Optional[pymongo.write_concern.WriteConcern] = None

The write concern to use when accessing the collection.

Defaults to the database’s write_concern.