Installation¶

You can install Booby directly from PyPI using pip or easy_install:

$ pip install booby

Or install the latest sources from Github:

$ pip install -e git+git://github.com/jaimegildesagredo/booby.git#egg=booby

Also you can download a source code package from Github and install it using setuptools:

$ tar xvf booby-{version}.tar.gz
$ cd booby
$ python setup.py install

Models¶

The models module contains the booby highest level abstraction: the Model.

To define a model you should subclass the Model class and add a list of fields as attributes. And then you could instantiate your Model and work with these objects.

Something like this:

class Repo(Model):
     name = fields.String()
     owner = fields.Embedded(User)

booby = Repo(
    name='Booby',
    owner={
        'login': 'jaimegildesagredo',
        'name': 'Jaime Gil de Sagredo'
    })

print booby.to_json()
'{"owner": {"login": "jaimegildesagredo", "name": "Jaime Gil de Sagredo"}, "name": "Booby"}'

class models.Model(**kwargs)¶

The Model class. All Booby models should subclass this.

By default the Model’s __init__() takes a list of keyword arguments to initialize the fields values. If any of these keys is not a field then raises errors.FieldError. Of course you can overwrite the Model’s __init__() to get a custom behavior.

You can get or set Model fields values in two different ways: through object attributes or dict-like items:

>>> booby.name is booby['name']
True
>>> booby['name'] = 'booby'
>>> booby['foo'] = 'bar'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
errors.FieldError: foo
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
errors.FieldError: foo

Parameters:	**kwargs – Keyword arguments with the fields values to initialize the model.

is_valid¶

This property will be True if there are not validation errors in this model fields. If there are any error then will be False.

This property wraps the Model.validate() method to be used in a boolean context.

to_json(*args, **kwargs)¶

This method returns the model as a json string. It receives the same arguments as the builtin json.dump() function.

To build a json representation of this model this method iterates over the object to build a dict and then serializes it as json.

update(*args, **kwargs)¶

This method updates the model fields values with the given dict. The model can be updated passing a dict object or keyword arguments, like the Python’s builtin dict.update().

validate()¶

This method validates the entire model. That is, validates all the fields within this model.

If some field validation fails, then this method raises the same exception that the field.validate() method had raised.

validation_errors¶

Generator of field name and validation error string pairs for each validation error on this model fields.

Fields¶

The fields module contains a list of Field classes for model’s definition.

The example below shows the most common fields and builtin validations:

class Token(Model):
    key = String()
    secret = String()

class User(Model):
    login = String(required=True)
    name = String()
    role = String(choices=['admin', 'moderator', 'user'])
    email = Email(required=True)
    token = Embedded(Token, required=True)
    is_active = Boolean(default=False)

class fields.Boolean(*args, **kwargs)¶

Field subclass with builtin bool validation.

class fields.Collection(model, *args, **kwargs)¶

Field subclass with builtin list of models.Model validation, encoding and decoding.

Example:

class Token(Model):
    key = String()
    secret = String()

class User(Model):
    tokens = Collection(Token)


user = User({
    'tokens': [
        {
            'key': 'xxx',
            'secret': 'yyy'
        },
        {
            'key': 'zzz',
            'secret': 'xxx'
        },
    ]
})

user.tokens.append(Token(key='yyy', secret='xxx'))

class fields.Email(*args, **kwargs)¶

Field subclass with builtin email validation.

class fields.Embedded(model, *args, **kwargs)¶

Field subclass with builtin embedded models.Model validation.

class fields.Field(*validators, **kwargs)¶

This is the base class for all booby.fields. This class can also be used as field in any models.Model declaration.

Parameters:

default – This field default‘s value. If passed a callable object then uses its return value as the field’s default. This is particularly useful when working with mutable objects. If default is a callable it can optionaly receive the owner model instance as its first positional argument. required – If True this field value should not be None. choices – A list of values where this field value should be in. name – Specify an alternate key name to use when decoding and encoding. read_only – If True, the value is treated normally in decoding but omitted during encoding. *validators – A list of field validators as positional arguments.

class fields.Float(*args, **kwargs)¶

Field subclass with builtin float validation.

class fields.Integer(*args, **kwargs)¶

Field subclass with builtin integer validation.

class fields.List(*args, **kwargs)¶

Field subclass with builtin list validation and default value.

class fields.String(*args, **kwargs)¶

Field subclass with builtin string validation.

Validators¶

The validators module contains a set of fields validators.

A validator is any callable object which receives a value as the target for the validation. If the validation fails then should raise an errors.ValidationError exception with an error message.

Validators are passed to fields.Field and subclasses as possitional arguments.

class validators.Boolean¶

This validator forces fields values to be an instance of bool.

class validators.Email¶

This validator forces fields values to be strings and match a valid email address.

class validators.Float¶

This validator forces fields values to be an instance of float.

class validators.In(choices)¶

This validator forces fields to have their value in the given list.

Parameters:	choices – A list of possible values.

class validators.Integer¶

This validator forces fields values to be an instance of int.

class validators.List(*validators)¶

This validator forces field values to be a list. Also a list of inner validators could be specified to validate each list element. For example, to validate a list of models.Model you could do:

books = fields.Field(validators.List(validators.Model(YourBookModel)))

Parameters:	*validators – A list of inner validators as possitional arguments.

class validators.Model(model)¶

This validator forces fields values to be an instance of the given models.Model subclass and also performs a validation in the entire model object.

Parameters:	model – A subclass of models.Model

class validators.Required¶

This validator forces fields to have a value other than None.

class validators.String¶

This validator forces fields values to be an instance of basestring.

Inspection¶

The inspection module provides users and 3rd-party library developers a public api to access booby objects and classes internal data, such as defined fields, and some low-level type validations.

This module is based on the Python inspect module.

inspection.get_fields(model)¶

Returns a dict mapping the given model field names to their fields.Field objects.

Parameters:	model – The models.Model subclass or instance you want to get their fields.
Raises:	TypeError if the given model is not a model.

inspection.is_model(obj)¶

Returns True if the given object is a models.Model instance or subclass. If not then returns False.

Errors¶

The errors module contains all exceptions used by Booby.

exception errors.BoobyError¶

Base class for all Booby exceptions.

exception errors.FieldError¶

This exception is used as an equivalent to AttributeError for fields.

exception errors.ValidationError¶

This exception should be raised when a value doesn’t validate. See validators.

Changes¶