MangoEngine API Reference¶

The Model Class¶

class mangoengine.Model(**kwargs)¶

Derive from this class to make your own models.

Variables:	_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
...
>>> Person.name
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: type object 'Person' has no attribute 'name'
>>> Person.unrelated
3
>>> Person._fields
{'name': <mangoengine.fields.StringField object at 0x2200d50>}
>>> person = Person(name = "John")
>>> person
Person(name = 'John')

Note

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.

Note

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

Parameters:	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.

Fields¶

class mangoengine.Field(nullable=False)¶

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

Variables:	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.

Variables:	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.

Errors¶

class mangoengine.ValidationFailure(field_name, description)¶

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

Variables:	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
'string'

Note

For a fantastic overview of metaclasses, see http://stackoverflow.com/a/6581949/1989056.