A mongoalchemy document is used to define a mapping between a python object and a document in a Mongo Database. Mappings are defined by creating a subclass of Document with attributes to define what maps to what. The two main types of attributes are Field and Index
A Field is used to define the type of a field in mongo document, any constraints on the values, and to provide methods for transforming a value from a python object into something Mongo understands and vice-versa.
A Index is used to define an index on the underlying collection programmatically. A document can have multiple indexes by adding extra Index attributes
Parameters: |
|
---|
Default field for the mongo object ID (_id in the database). This field is automatically set on objects when they are saved into the database. This field can be overridden in subclasses if the default ID is not acceptable
The namespace is used to determine how string class names should be looked up. If an instance of DocumentField is created using a string, it will be looked up using the value of this variable and the string. To have more than one namespace create a subclass of Document overriding this class variable. To turn off caching all together, create a subclass where namespace is set to None. Doing this will disable using strings to look up document names, which will make creating self-referencing documents impossible. The default value is “global”
The variable to use when determining which class to instantiate a database object with. It is the name of an attribute which will be used to decide the type of the object. If you want more control over which class is selected, you can override get_subclass.
Use the base class collection name for the subclasses. Default: False
When using a string value with config_polymorphic_on in a parent class, this is the value that the attribute is compared to when determining
If namespaces are being used, the key for a class is normally the class name. In some cases the same class name may be used in different modules. This field allows a longer unambiguous name to be given. It may also be used in error messages or string representations of the class
The default sort to use when querying. If set, this sort will be applied to any query which a sort isn’t used on. The format is the same as pymongo. Example [('foo', 1), ('bar', -1)].
Controls the method to use when dealing with fields passed in to the document constructor. Possible values are ‘error’ and ‘ignore’. Any fields which couldn’t be mapped can be retrieved (and edited) using get_extra_fields()
Register a subclass of this class. Maps the subclass to the value of subclass.config_polymorphic_identity if available.
Get the subclass to use when instantiating a polymorphic object. The default implementation looks at cls.config_polymorphic to get the name of an attribute. Subclasses automatically register their value for that attribute on creation via their config_polymorphic_identity field. This process is then repeated recursively until None is returned (indicating that the current class is the correct one)
This method can be overridden to allow any method you would like to use to select subclasses. It should return either the subclass to use or None, if the original class should be used.
Returns a dict with the update operations necessary to make the changes to this object to the database version. It is mainly used internally for update() but may be useful for diagnostic purposes as well.
Parameters: | with_required – Also include any field which is required. This is useful if the method is being called for the purposes of an upsert where all required fields must always be sent. |
---|
if Document.config_extra_fields is set to ‘ignore’, this method will return a dictionary of the fields which couldn’t be mapped to the document.
Returns a dict mapping the names of the fields in a document or subclass to the associated Field
Returns the name of the class. The name of the class is also the default collection name.
See also
Returns the collection name used by the class. If the config_collection_name attribute is set it is used, otherwise the name of the class is used.
Tranform the SON object into one which will be able to be unwrapped by this document class.
This method is designed for schema migration systems.
Adds a mapping interface to a document. Supports __getitem__ and __contains__. Both methods will only retrieve values assigned to a field, not methods or other attributes.
if the name is set, return its value. Otherwse set name to value and return value
This class is used in the class definition of a Document to specify a single, possibly compound, index. pymongo‘s ensure_index will be called on each index before a database operation is executed on the owner document class.
Example
>>> class Donor(Document):
... name = StringField()
... age = IntField(min_value=0)
... blood_type = StringField()
...
... i_name = Index().ascending('name')
... type_age = Index().ascending('blood_type').descending('age')
Add an expire after option to the index
Param: | after: Number of second before expiration |
---|
Add a descending index for name to this index.
Parameters: | name – Name to be used in the index |
---|
Add a descending index for name to this index.
Parameters: | name – Name to be used in the index |
---|
Create a 2d index. See: http://www.mongodb.org/display/DOCS/Geospatial+Indexing
Parameters: |
|
---|
Create a Haystack index. See: http://www.mongodb.org/display/DOCS/Geospatial+Haystack+Indexing
Parameters: |
|
---|
Make this index unique, optionally dropping duplicate entries.
Parameters: | drop_dups – Drop duplicate objects while creating the unique index? Default to False |
---|
Call the pymongo method ensure_index on the passed collection.
Parameters: | collection – the pymongo collection to ensure this index is on |
---|
Parameters: |
|
---|
Default field for the mongo object ID (_id in the database). This field is automatically set on objects when they are saved into the database. This field can be overridden in subclasses if the default ID is not acceptable
The namespace is used to determine how string class names should be looked up. If an instance of DocumentField is created using a string, it will be looked up using the value of this variable and the string. To have more than one namespace create a subclass of Document overriding this class variable. To turn off caching all together, create a subclass where namespace is set to None. Doing this will disable using strings to look up document names, which will make creating self-referencing documents impossible. The default value is “global”
The variable to use when determining which class to instantiate a database object with. It is the name of an attribute which will be used to decide the type of the object. If you want more control over which class is selected, you can override get_subclass.
Use the base class collection name for the subclasses. Default: False
When using a string value with config_polymorphic_on in a parent class, this is the value that the attribute is compared to when determining
If namespaces are being used, the key for a class is normally the class name. In some cases the same class name may be used in different modules. This field allows a longer unambiguous name to be given. It may also be used in error messages or string representations of the class
The default sort to use when querying. If set, this sort will be applied to any query which a sort isn’t used on. The format is the same as pymongo. Example [('foo', 1), ('bar', -1)].
Controls the method to use when dealing with fields passed in to the document constructor. Possible values are ‘error’ and ‘ignore’. Any fields which couldn’t be mapped can be retrieved (and edited) using get_extra_fields()
Register a subclass of this class. Maps the subclass to the value of subclass.config_polymorphic_identity if available.
Get the subclass to use when instantiating a polymorphic object. The default implementation looks at cls.config_polymorphic to get the name of an attribute. Subclasses automatically register their value for that attribute on creation via their config_polymorphic_identity field. This process is then repeated recursively until None is returned (indicating that the current class is the correct one)
This method can be overridden to allow any method you would like to use to select subclasses. It should return either the subclass to use or None, if the original class should be used.
Returns a dict with the update operations necessary to make the changes to this object to the database version. It is mainly used internally for update() but may be useful for diagnostic purposes as well.
Parameters: | with_required – Also include any field which is required. This is useful if the method is being called for the purposes of an upsert where all required fields must always be sent. |
---|
if Document.config_extra_fields is set to ‘ignore’, this method will return a dictionary of the fields which couldn’t be mapped to the document.
Returns a dict mapping the names of the fields in a document or subclass to the associated Field
Returns the name of the class. The name of the class is also the default collection name.
See also
Returns the collection name used by the class. If the config_collection_name attribute is set it is used, otherwise the name of the class is used.
Returns all of the Index instances for the current class.
Tranform the SON object into one which will be able to be unwrapped by this document class.
This method is designed for schema migration systems.
This class is used in the class definition of a Document to specify a single, possibly compound, index. pymongo‘s ensure_index will be called on each index before a database operation is executed on the owner document class.
Example
>>> class Donor(Document):
... name = StringField()
... age = IntField(min_value=0)
... blood_type = StringField()
...
... i_name = Index().ascending('name')
... type_age = Index().ascending('blood_type').descending('age')
Add an expire after option to the index
Param: | after: Number of second before expiration |
---|
Add a descending index for name to this index.
Parameters: | name – Name to be used in the index |
---|
Add a descending index for name to this index.
Parameters: | name – Name to be used in the index |
---|
Create a 2d index. See: http://www.mongodb.org/display/DOCS/Geospatial+Indexing
Parameters: |
|
---|
Create a Haystack index. See: http://www.mongodb.org/display/DOCS/Geospatial+Haystack+Indexing
Parameters: |
|
---|
Make this index unique, optionally dropping duplicate entries.
Parameters: | drop_dups – Drop duplicate objects while creating the unique index? Default to False |
---|
Call the pymongo method ensure_index on the passed collection.
Parameters: | collection – the pymongo collection to ensure this index is on |
---|