Documents and Indexes

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

class mongoalchemy.document.DocumentMeta
mro() → list

return a type’s method resolution order

class mongoalchemy.document.Document(retrieved_fields=None, loading_from_db=False, **kwargs)
Parameters:
  • retrieved_fields – The names of the fields returned when loading a partial object. This argument should not be explicitly set by subclasses
  • **kwargs – The values for all of the fields in the document. Any additional fields will raise a ExtraValueException and any missing (but required) fields will raise a MissingValueException. Both types of exceptions are subclasses of DocumentException.
mongo_id

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

config_namespace = 'global'

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”

config_polymorphic = None

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.

config_polymorphic_collection = False

Use the base class collection name for the subclasses. Default: False

config_polymorphic_identity = None

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

config_full_name = None

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

config_default_sort = None

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)].

config_extra_fields = 'error'

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()

classmethod add_subclass(subclass)

Register a subclass of this class. Maps the subclass to the value of subclass.config_polymorphic_identity if available.

classmethod get_subclass(obj)

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.

get_dirty_ops(with_required=False)

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.
get_extra_fields()

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.

classmethod get_fields()

Returns a dict mapping the names of the fields in a document or subclass to the associated Field

classmethod class_name()

Returns the name of the class. The name of the class is also the default collection name.

classmethod get_collection_name()

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.

classmethod get_indexes()

Returns all of the Index instances for the current class.

classmethod transform_incoming(obj, session)

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.

has_id()
to_ref(db=None)
class mongoalchemy.document.DictDoc

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.

setdefault(name, value)

if the name is set, return its value. Otherwse set name to value and return value

exception mongoalchemy.document.BadIndexException
class mongoalchemy.document.Index

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')
ASCENDING = 1
DESCENDING = -1
expire(after)

Add an expire after option to the index

Param:after: Number of second before expiration
ascending(name)

Add a descending index for name to this index.

Parameters:name – Name to be used in the index
descending(name)

Add a descending index for name to this index.

Parameters:name – Name to be used in the index
geo2d(name, min=None, max=None)

Create a 2d index. See: http://www.mongodb.org/display/DOCS/Geospatial+Indexing

Parameters:
  • name – Name of the indexed column
  • min – minimum value for the index
  • max – minimum value for the index
geo_haystack(name, bucket_size)

Create a Haystack index. See: http://www.mongodb.org/display/DOCS/Geospatial+Haystack+Indexing

Parameters:
  • name – Name of the indexed column
  • bucket_size – Size of the haystack buckets (see mongo docs)
unique(drop_dups=False)

Make this index unique, optionally dropping duplicate entries.

Parameters:drop_dups – Drop duplicate objects while creating the unique index? Default to False
ensure(collection)

Call the pymongo method ensure_index on the passed collection.

Parameters:collection – the pymongo collection to ensure this index is on
class mongoalchemy.document.Value(field, document, from_db=False, extra=False, retrieved=True)
clear_dirty()
delete()

Document

class mongoalchemy.document.Document(retrieved_fields=None, loading_from_db=False, **kwargs)
Parameters:
  • retrieved_fields – The names of the fields returned when loading a partial object. This argument should not be explicitly set by subclasses
  • **kwargs – The values for all of the fields in the document. Any additional fields will raise a ExtraValueException and any missing (but required) fields will raise a MissingValueException. Both types of exceptions are subclasses of DocumentException.
mongo_id

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

config_namespace = 'global'

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”

config_polymorphic = None

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.

config_polymorphic_collection = False

Use the base class collection name for the subclasses. Default: False

config_polymorphic_identity = None

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

config_full_name = None

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

config_default_sort = None

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)].

config_extra_fields = 'error'

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()

classmethod add_subclass(subclass)

Register a subclass of this class. Maps the subclass to the value of subclass.config_polymorphic_identity if available.

classmethod get_subclass(obj)

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.

get_dirty_ops(with_required=False)

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.
get_extra_fields()

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.

classmethod get_fields()

Returns a dict mapping the names of the fields in a document or subclass to the associated Field

classmethod class_name()

Returns the name of the class. The name of the class is also the default collection name.

classmethod get_collection_name()

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.

classmethod get_indexes()

Returns all of the Index instances for the current class.

classmethod transform_incoming(obj, session)

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.

has_id()
to_ref(db=None)

Index

class mongoalchemy.document.Index

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')
ASCENDING = 1
DESCENDING = -1
expire(after)

Add an expire after option to the index

Param:after: Number of second before expiration
ascending(name)

Add a descending index for name to this index.

Parameters:name – Name to be used in the index
descending(name)

Add a descending index for name to this index.

Parameters:name – Name to be used in the index
geo2d(name, min=None, max=None)

Create a 2d index. See: http://www.mongodb.org/display/DOCS/Geospatial+Indexing

Parameters:
  • name – Name of the indexed column
  • min – minimum value for the index
  • max – minimum value for the index
geo_haystack(name, bucket_size)

Create a Haystack index. See: http://www.mongodb.org/display/DOCS/Geospatial+Haystack+Indexing

Parameters:
  • name – Name of the indexed column
  • bucket_size – Size of the haystack buckets (see mongo docs)
unique(drop_dups=False)

Make this index unique, optionally dropping duplicate entries.

Parameters:drop_dups – Drop duplicate objects while creating the unique index? Default to False
ensure(collection)

Call the pymongo method ensure_index on the passed collection.

Parameters:collection – the pymongo collection to ensure this index is on

Table Of Contents

Previous topic

Field Types

Next topic

Expression Language — Querying and Updating

This Page