Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

282 lines (160 sloc) 5.994 kB


distillery is another fatory_girl like for python ORMs.


pip install distillery

Defining distilleries

Each distillery has a __model__ and a set of attributes and methods. The __model__ is the ORM model class from which instance will be produced:

class UserDistillery(MyOrmDistillery):
    __model__ = User


A distillery class attribute defines default values for specific model field:

class UserDistillery(MyOrmDistillery):
    __model__ = User

    username = "defaultusername"

All new User outputted from UserDistillery will have defaultusername as username field value while there's no override.

Methods (a.k.a. "lazy attributes")

A distillery class method allow to build dinamic value for specific field:

from distillery import lazy

class UserDistillery(MyOrmDistillery):
    __model__ = User

    username = "defaultusername"

    def email_address(cls, instance, sequence):
        return "%s@%s" % (instance.username,

All new User outputted from UserDistillery will have an email_address computed from his username and his company domain.

Note: all lazies received an instance and a sequence that are respectively the object instance and an auto incremented sequence.

After create hook

A distillery can provide an _after_create class method.

class UserDistillery(MyOrmDistillery):
    __model__ = User

    username = "defaultusername"

    def _after_create(cls, instance):
        # Do stuff after instance creation
        # ...

Using distilleries


Inits and populates an instance:

user = UserDistillery.init()
assert user.username == "defaultusername"
assert is None

user = UserDistillery.create(username="overriddenusername")
assert user.username == "overriddenusername"
assert is None


Inits, populates and persists an instance:

user = UserDistillery.create()
assert user.username == "defaultusername"
assert is not None


Massively creates instances.

users = UserDistillery.bulk(12, username='user_%(i)%')
assert users[7].username = 'user_7'


distillery provides a Set class that act as a fixture container.

A Set needs a __distillery__ class member from where all instances will born:

from distillery import Set

class UserSet(Set):
    __distillery__ = UserDistillery

    class jeanphix:
        username = 'jeanphix'

Then simply instanciate the UserSet to access the fixture object:

users = UserSet()
assert users.jeanphix.username == 'jeanphix'

Cross Set relations are also allowed:

from distillery import Set

class CompanySet(Set):
    __distillery__ = CompanyDistillery

    class my_company:
        name = "My company"

class UserSet(Set):
    __distillery__ = UserDistillery

    class jeanphix:
        username = 'jeanphix'
        company =

users = UserSet()
assert == 'My company'

Set fixtures can be callable:

class ProfileSet(Set)
    class __distillery__:
        __model__ = Profile

    admin = lambda s: UserDistillery.create(username="admin").profile

Set fixtures can provide an _after_create listener:

class ProfileSet(Set):
    class __distillery__:
        __model__ = Profile

    class admin:
        def _after_create(cls, profile):
   = 'Full name'

assert ProfileSet() == 'Full name'

Set can create fixture instances on demand when they are accessed by setting on_demand constructor parameter:

users = UserSet(on_demand=True)
users.jeanphix  # jeanphix will be created here.

Set can act as container for other sets:

class fixtures(Set):
    users = UserSet

assert fixtures().users.jeanphix.username == 'jeanphix'

Self relation within a Set can be handle with a callable:

class UserSet(Set):
    # ...
    class my_user:
        # ...

    class another_user:
        best_friend = classmethod(lambda c: UserSet.my_user)



Django models could be distilled using DjangoDistillery that only requires a __model__ class member:

from distillery import DjangoDistillery

from django.auth.models import User

class UserDistillery(DjangoDistillery):
    __model__ = User

    #  ...


SQLAlchemy distilleries require a __model__ and a __session__ class members:

from distillery import SQLAlchemyDistillery

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine('sqlite://', echo=False)
Session = sessionmaker()
session = Session()
Base = declarative_base()

class User(Base):
    #  ...

class UserDistillery(SQLAlchemyDistillery):
    __model__ = User
    __session__ = session

    #  ...
Jump to Line
Something went wrong with that request. Please try again.