Skip to main content

A model instances generator for Django

Project description

Django-fakery
=============

.. image:: https://travis-ci.org/fcurella/django-fakery.svg?branch=master
:target: https://travis-ci.org/fcurella/django-fakery


.. image:: https://coveralls.io/repos/fcurella/django-fakery/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/fcurella/django-fakery?branch=master

An easy-to-use implementation of `Creation Methods`_ (aka Object Factory) for Django, backed by ``Faker``.

.. _Creation Methods: http://xunitpatterns.com/Creation%20Method.html

``django_fakery`` will try to guess the field's value based on the field's name and type.

Installation
------------

Install with::

$ pip install django-fakery

QuickStart
----------

.. code-block:: python

from django_fakery import factory

factory.m('app.Model')(field='value')

Alternatively, you can use a more explict API:

.. code-block:: python

from django_fakery import factory

factory.make(
'app.Model',
fields={
'field': 'value',
}
)

We will use the short API throught the documentation.

The value of a field can be any python object, a callable, or a lambda:

.. code-block:: python

from django_fakery import factory
from django.utils import timezone

factory.m('app.Model')(created=timezone.now)

When using a lambda, it will receive two arguments: ``n`` is the iteration number, and ``f`` is an instance of ``faker``:

.. code-block:: python

user = factory.m('auth.User')(
username=lambda n, f: 'user_{}'.format(n),
)


You can create multiple objects by using the ``quantity`` parameter:

.. code-block:: python

from django_fakery import factory

factory.m('app.Model', quantity=4)

For convenience, when the value of a field is a string, it will be interpolated with the iteration number:

.. code-block:: python

user = factory.m('auth.User', quantity=4)(
username='user_{}',
)

Foreign keys
------------

Non-nullable ``ForeignKey`` s create related objects automatically.

If you want to explicitly create a related object, you can pass a factory like any other value:

.. code-block:: python

pizza = factory.m('food.Pizza')(
chef=factory.m('auth.User)(username='Gusteau'),
)

If you want to explicitly resue a related object, you can pass the instance like any other value:

.. code-block:: python
chef = factory.m('auth.User)(username='Gusteau')
pizza = factory.m('food.Pizza')(
chef=chef,
)

ManyToManies
------------

Because ``ManyToManyField``s are implicitly nullable (ie: they're always allowed to have their ``.count()`` equal to ``0``), related objects on those fields are not automatically created for you.

If you want to explicitly create a related objects, you can pass a list as the field's value:

.. code-block:: python

pizza = factory.m('food.Pizza')(
toppings=[
factory.m('food.Topping')(name='Anchovies')
],
)

You can also pass a factory, to create multiple objects:

.. code-block:: python

pizza = factory.m('food.Pizza')(
toppings=factory.m('food.Topping', quantity=5),
)

Lazies
------

You can refer to the created instance's own attributes or method by using `Lazy` objects.

For example, if you'd like to create user with email as username, and have them always match, you could do:

.. code-block:: python

from django_fakery import factory, Lazy

factory.m('auth.User')(
username=Lazy('email'),
)


If you want to assign a value returned by a method on the instance, you can pass the method's arguments to the ``Lazy`` object:

.. code-block:: python

from django_fakery import factory, Lazy

factory.make('myapp.Model')
myfield=Lazy('model_method', 'argument', keyword='keyword value'),
)

Pre-save and Post-save hooks
----------------------------

You can define functions to be called right before the instance is saved or right after:

.. code-block:: python

from django_fakery import factory

factory.m(
'auth.User',
pre_save=[
lambda u: u.set_password('password')
],
)(username='username')

Since settings a user's password is such a common case, we special-cased that scenario, so you can just pass it as a field:

.. code-block:: python

from django_fakery import factory

factory.m('auth.User')(
username='username',
password='password',
)

Non persistent instances
------------------------

You can build instances that are not saved to the database by using the `.b()` method, just like you'd use `.m()`:

.. code-block:: python

from django_fakery import factory

factory.b('app.Model')(
field='value',
)

Note that since the instance is not saved to the database, `.build()` does not support ManyToManies or post-save hooks.

If you're looking for a more explicit API, you can use the `.build()` method:

.. code-block:: python

from django_fakery import factory

factory.build(
'app.Model',
fields={
'field': 'value',
}
)


Blueprints
----------

Use a blueprint:

.. code-block:: python

from django_fakery import factory

user = factory.blueprint('auth.User')

user.make(quantity=10)

Blueprints can refer other blueprints:

.. code-block:: python

pizza = factory.blueprint('food.Pizza').fields(
chef=user,
)
)

You can also override the field values you previously specified:

.. code-block:: python

pizza = factory.blueprint('food.Pizza').fields(
chef=user,
thickness=1
)
)

pizza.m(quantity=10)(thickness=2)

Or, if you'd rather use the explicit api:

.. code-block:: python

pizza = factory.blueprint('food.Pizza').fields(
chef=user,
thickness=1
)
)

thicker_pizza = pizza.fields(thickness=2)
thicker_pizza.make(quantity=10)


Seeding the faker
-----------------

.. code-block:: python

from django_fakery import factory

factory.m('auth.User', seed=1234, quantity=4)(
username='regularuser_{}'
)

Credits
-------

The API is heavily inspired by `model_mommy`_.

.. _model_mommy: https://github.com/vandersonmota/model_mommy

License
-------

This software is released under the MIT License.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-fakery-1.5.3.tar.gz (9.7 kB view hashes)

Uploaded Source

Built Distribution

django_fakery-1.5.3-py2.py3-none-any.whl (16.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page