MangoEngine API Reference

The Model Class

class mangoengine.Model(**kwargs)

Derive from this class to make your own models.

  • _fields – A dictionary mapping any field names to their mangoengine.Field instances.
  • _allow_unknown_data – Sets the default value for the allow_unknown_data parameter in validate().
>>> class Person(Model):
...     name = StringField()
...     unrelated = 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: type object 'Person' has no attribute 'name'
>>> Person.unrelated
>>> Person._fields
{'name': <mangoengine.fields.StringField object at 0x2200d50>}
>>> person = Person(name = "John")
>>> person
Person(name = 'John')


The magic handling of the class attributes is made possible through the mangoengine.models.ModelMetaclass metaclass.

classmethod from_dict(dictionary, allow_unknown_data=None)

Creates a new instance of the model from the given dictionary.


Validation is not performed. Make sure to call validate() afterwards if validation is desired.

  • dictionary – The dictionary to pull the values from.
  • allow_unknown_data – If True, when an unknown attribute is found the validation will fail. Uses the value of self._allow_unknown_data if None is specified, or True if no such attribute exists.


class mangoengine.Field(nullable=False)

The base Field class. Should be inherited from and not used directly.

  • name – The name of the field in the model. For example, if the model defines a field hair_color as a StringField, that StringField‘s name should be set to "hair_color".
  • nullable – If False, the value of this field may not be None.
class mangoengine.StringField(**default_kwargs)

A string field. Only values of type str are accepted.

class mangoengine.UnicodeField(**default_kwargs)

A unicode string field. Only values of type unicode are accepted.

class mangoengine.NumericField(bounds=(None, None), **default_kwargs)

A numeric field. Only types of int, long, and double are accepted.

Variables:bounds – A two-tuple containing a lower and upper inclusive bound.
class mangoengine.IntegralField(bounds=(None, None), **default_kwargs)

An integral field. Only types of int and long are accepted.

Variables:bounds – A two-tuple containing a lower and upper inclusive bound.
class mangoengine.DictField(of_key=None, of_value=None, **default_kwargs)

A dictionary field. Only values of type dict are accepted.

  • of_key – The type of field that every key must be. Example, if this is a StringField, all keys in the dictionary must be strings.
  • of_value – Similar to of_key but affecting the values.
class mangoengine.ListField(of=None, **default_kwargs)

A list field. Only values of type list are accepted.

Variables:of – The type of field that each list item must be. For example, if a StringField is given, all list items must be strings.
class mangoengine.ModelField(model, **default_kwargs)

A field that can wrap any Model class.

Variables:model – The type of Model it accepts.


class mangoengine.ValidationFailure(field_name, description)

Raised by Model.validate() when the value given for a particular field is not valid.

  • field_name – The value of the field’s name attribute.
  • description – A description of the failure.
class mangoengine.UnknownAttribute(attribute_name)

Raised by Model.validate() when allow_unknown_data is False and an unknown attribute is encountered.

Inherits from ValidationFailure.

The ModelMetaclass Metaclass

This metaclass is not a part of the MangoEngine public interface and should not be accessed directly. It is useful to look at to understand how the models work however.

class mangoengine.models.ModelMetaclass[source]

A simple metaclass responsible for setting up Model classes appropriately.

The created class will have a _fields class variable that contains a dictionary mapping field names to instances of Field. For example...

>>> class Foo(Model):
...     a = StringField()
...     b = ListField()
...     unrelated = "string"
>>> Foo._fields
{'a': <mangoengine.fields.StringField object at 0x7fc8db7bb210>,
'b': <mangoengine.fields.ListField object at 0x7fc8db7bb990>}

Further, the original class variables that define fields are not preserved, but any other class variables are. Continuing from above...

>>> Foo.a
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: type object 'Foo' has no attribute 'a'
>>> Foo.unrelated


For a fantastic overview of metaclasses, see