Field Types

Field

class ommongo.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

Primitive Fields

class ommongo.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 ommongo.fields.BoolField(**kwargs)

True or False.

is_sequence_field = False
class ommongo.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 ommongo.fields.IntField(**kwargs)

Subclass of NumberField for int

Parameters:
  • max_value – maximum value
  • min_value – minimum value
  • kwargs – arguments for Field
is_sequence_field = False
class ommongo.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 ommongo.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 ommongo.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 ommongo.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 ommongo.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 ommongo.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
ommongo.fields.CreatedField(name='created', tz_aware=False, **kwargs)

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
ommongo.fields.ModifiedField(tz_aware=False, **kwargs)

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

WARNINGS: When this field’s parent object is sent to the database its modified time is set. The local copy is not updated for technical reasons. Hopefully this will not be the case in the future.

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 ommongo.fields.ListField(item_type, **kwargs)

Field representing a python list.

Parameters:
  • item_type – Field 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.
is_sequence_field = True
rel(ignore_missing=False)
class ommongo.fields.SetField(item_type, **kwargs)

Field representing a python set.

Parameters:
  • item_type – Field 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.
is_sequence_field = True
rel(ignore_missing=False)

Mapping Type Fields

class ommongo.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 ommongo.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 ommongo.fields.DocumentField(document_class, **kwargs)

A field which wraps a Document

is_sequence_field = False

Reference Field

class ommongo.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 ommongo.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 ommongo.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
ommongo.fields.computed_field(computed_type, deps=None, **kwargs)