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 anDocument.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 useObjectID
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
andread_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 itsuse()
method called to set a db, anAttributeError
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
andkwargs
are passed to motor’sdelete_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
andkwargs
are passed to motor’sfind
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 specifyreturn_document=ReturnDocument.AFTER
this method will reload thereplacement
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 theMongo
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 specifydrop=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 isTrue
.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
andkwargs
are passed to motor’sreplace_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.
-
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 namedMongo
. 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
.
-