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.