Field Types

Field

class mongoalchemy.fields.Field(required=True, default=UNSET, default_f=None, db_field=None, allow_none=False, on_update='$set', validator=None, unwrap_validator=None, wrap_validator=None, _id=False, proxy=None, iproxy=None, ignore_missing=False)
Parameters:
  • required – The field must be passed when constructing a document (optional. default: True)
  • default – Default value to use if one is not given (optional.)
  • db_field – name to use when saving or loading this field from the database (optional. default is the name the field is assigned to on a documet)
  • allow_none – allow None as a value (optional. default: False)
  • validator – a callable which will be called on objects when wrapping/unwrapping
  • unwrap_validator – a callable which will be called on objects when unwrapping
  • wrap_validator – a callable which will be called on objects when wrapping
  • _id – Set the db_field to _id. If a field has this the “mongo_id” field will also be removed from the document the field is on.

The general validator is called after the field’s validator, but before either of the wrap/unwrap versions. The validator should raise a BadValueException if it fails, but if it returns False the field will raise an exception with a generic message.

is_sequence_field = False

Is this a sequence? used by elemMatch

Primitive Fields

class mongoalchemy.fields.StringField(max_length=None, min_length=None, **kwargs)

Unicode Strings. unicode is used to wrap and unwrap values, and any subclass of basestring is an acceptable input

Parameters:
  • max_length – maximum string length
  • min_length – minimum string length
  • kwargs – arguments for Field
is_sequence_field = False
class mongoalchemy.fields.BoolField(**kwargs)

True or False.

is_sequence_field = False
class mongoalchemy.fields.NumberField(constructor, min_value=None, max_value=None, **kwargs)

Base class for numeric fields

Parameters:
  • max_value – maximum value
  • min_value – minimum value
  • kwargs – arguments for Field
is_sequence_field = False
class mongoalchemy.fields.IntField(**kwargs)

Subclass of NumberField for int

Parameters:
  • max_length – maximum value
  • min_length – minimum value
  • kwargs – arguments for Field
is_sequence_field = False
class mongoalchemy.fields.FloatField(**kwargs)

Subclass of NumberField for float

Parameters:
  • max_value – maximum value
  • min_value – minimum value
  • kwargs – arguments for Field
is_sequence_field = False
class mongoalchemy.fields.TupleField(*item_types, **kwargs)

Represents a field which is a tuple of a fixed size with specific types for each element in the field.

Examples TupleField(IntField(), BoolField()) would accept [19, False] as a value for both wrapping and unwrapping.

Parameters:
  • item_types – instances of Field, in the order they will appear in the tuples.
  • kwargs – arguments for Field
is_sequence_field = False
class mongoalchemy.fields.EnumField(item_type, *values, **kwargs)

Represents a single value out of a list of possible values, all of the same type. == is used for comparison

Example: EnumField(IntField(), 4, 6, 7) would accept anything in (4, 6, 7) as a value. It would not accept 5.

Parameters:
  • item_type – Instance of Field to use for validation, and (un)wrapping
  • values – Possible values. item_type.is_valid_wrap(value) should be True
is_sequence_field = False
class mongoalchemy.fields.ObjectIdField(session=None, auto=False, **kwargs)

pymongo Object ID object. Currently this is probably too strict. A string version of an ObjectId should also be acceptable

gen()

Helper method to create a new ObjectId

is_sequence_field = False
class mongoalchemy.fields.AnythingField(required=True, default=UNSET, default_f=None, db_field=None, allow_none=False, on_update='$set', validator=None, unwrap_validator=None, wrap_validator=None, _id=False, proxy=None, iproxy=None, ignore_missing=False)

A field that passes through whatever is set with no validation. Useful for free-form objects

Parameters:
  • required – The field must be passed when constructing a document (optional. default: True)
  • default – Default value to use if one is not given (optional.)
  • db_field – name to use when saving or loading this field from the database (optional. default is the name the field is assigned to on a documet)
  • allow_none – allow None as a value (optional. default: False)
  • validator – a callable which will be called on objects when wrapping/unwrapping
  • unwrap_validator – a callable which will be called on objects when unwrapping
  • wrap_validator – a callable which will be called on objects when wrapping
  • _id – Set the db_field to _id. If a field has this the “mongo_id” field will also be removed from the document the field is on.

The general validator is called after the field’s validator, but before either of the wrap/unwrap versions. The validator should raise a BadValueException if it fails, but if it returns False the field will raise an exception with a generic message.

is_sequence_field = False

Date and Time Fields

class mongoalchemy.fields.DateTimeField(min_date=None, max_date=None, use_tz=False, **kwargs)

Field for datetime objects.

Parameters:
  • max_date – maximum date
  • min_date – minimum date
  • use_tz – Require a timezone-aware datetime (via pytz). Values are converted to UTC before saving. min and max dates are currently ignored when use_tz is on. You MUST pass a timezone into the session
  • kwargs – arguments for Field
is_sequence_field = False
mongoalchemy.fields.CreatedField(name='created', tz_aware=False)

A shortcut field for creation time. It sets the current date and time when it enters the database and then doesn’t update on further saves.

If you’ve used the Django ORM, this is the equivalent of auto_now_add

Parameters:tz_aware – If this is True, the value will be returned in the local time of the session. It is always saved in UTC
mongoalchemy.fields.ModifiedField(name='modified', tz_aware=False)

A shortcut field for modified time. It sets the current date and time when it enters the database and then updates when the document is saved or updated

If you’ve used the Django ORM, this is the equivalent of auto_now

Parameters:tz_aware – If this is True, the value will be returned in the local time of the session. It is always saved in UTC

Sequence Type Fields

class mongoalchemy.fields.ListField(item_type, **kwargs)

Field representing a python list.

Parameters:
  • item_typeField instance used for validation and (un)wrapping
  • min_capacity – minimum number of items contained in values
  • max_capacity – maximum number of items contained in values
  • default_empty – the default is an empty sequence.
rel(ignore_missing=False)
is_sequence_field = True
class mongoalchemy.fields.SetField(item_type, **kwargs)

Field representing a python set.

Parameters:
  • item_typeField instance used for validation and (un)wrapping
  • min_capacity – minimum number of items contained in values
  • max_capacity – maximum number of items contained in values
  • default_empty – the default is an empty sequence.
rel(ignore_missing=False)
is_sequence_field = True

Mapping Type Fields

class mongoalchemy.fields.DictField(value_type, default_empty=False, **kwargs)

Stores String to value_type Dictionaries. For non-string keys use KVField. Strings also must obey the mongo key rules (no . or $)

Parameters:value_type – the Field type to use for the values
is_sequence_field = False
class mongoalchemy.fields.KVField(key_type, value_type, default_empty=False, **kwargs)

Like a DictField, except it allows arbitrary keys. The DB Format for a KVField is [ { 'k' : key, 'v' : value }, ...]. Queries on keys and values. can be done with .k and .v

Parameters:
  • key_type – the Field type to use for the keys
  • value_type – the Field type to use for the values
is_sequence_field = False

Document Field

class mongoalchemy.fields.DocumentField(document_class, **kwargs)

A field which wraps a Document

is_sequence_field = False

Reference Field

class mongoalchemy.fields.RefField(type=None, db=None, db_required=False, namespace='global', **kwargs)

A ref field wraps a mongo DBReference. It DOES NOT currently handle saving the referenced object or updates to it, but it can handle auto-loading.

Parameters:
  • type – (optional) the Field type to use for the values. It must be a DocumentField. If you want to save refs to raw mongo objects, you can leave this field out
  • db – (optional) The database to load the object from. Defaults to the same database as the object this field is bound to.
  • namespace – If using the namespace system and using a collection name instead of a type, selects which namespace to use
dereference(session, ref, allow_none=False)

Dereference a pymongo “DBRef” to this field’s underlying type

is_sequence_field = False
rel(allow_none=False)

Used to create an attribute which will auto-dereference a RefField or SRefField.

Example:

employer_ref = SRefField(Employer)
employer = employer_ref.rel()
class mongoalchemy.fields.SRefField(type, db=None, **kwargs)

A Simple RefField (SRefField) looks like an ObjectIdField in the database, but acts like a mongo DBRef. It uses the passed in type to determine where to look for the object (and assumes the current database).

dereference(session, ref, allow_none=False)

Dereference an ObjectID to this field’s underlying type

is_sequence_field = False
rel(allow_none=False)

Used to create an attribute which will auto-dereference a RefField or SRefField.

Example:

employer_ref = SRefField(Employer)
employer = employer_ref.rel()

Computed Field

class mongoalchemy.fields.ComputedField(computed_type, fun, one_time=False, deps=None, **kwargs)

A computed field is generated based on an object’s other values. It will generally be created with the @computed_field decorator, but can be passed an arbitrary function.

The function should take a dict which will contains keys with the names of the dependencies mapped to their values.

The computed value is recalculated every the field is accessed unless the one_time field is set to True.

Example:

>>> class SomeDoc(Document):
...     @computed_field
...     def last_modified(obj):
...         return datetime.datetime.utcnow()

Warning

The computed field interacts in an undefined way with partially loaded documents right now. If using this class watch out for strange behaviour.

Parameters:
  • fun – the function to compute the value of the computed field
  • computed_type – the type to use when wrapping the computed field
  • deps – the names of fields on the current object which should be passed in to compute the value
is_sequence_field = False
mongoalchemy.fields.computed_field(computed_type, deps=None, **kwargs)

Table Of Contents

Previous topic

Session

Next topic

Documents and Indexes

This Page