
Introduction
************

The purpose of factory_boy is to provide a default way of getting a
new instance, while still being able to override some fields on a per-
call basis.

Note: This section will drive you through an overview of
  factory_boy's feature. New users are advised to spend a few minutes
  browsing through this list of useful helpers.Users looking for quick
  helpers may take a look at *Common recipes*, while those needing
  detailed documentation will be interested in the *Reference*
  section.


Basic usage
===========

Factories declare a set of attributes used to instantiate an object,
whose class is defined in the "class Meta"'s "model" attribute:

* Subclass "factory.Factory" (or a more suitable subclass)

* Add a "class Meta:" block

* Set its "model" attribute to the target class

* Add defaults for keyword args to pass to the associated class'
  "__init__" method

   import factory
   from . import base

   class UserFactory(factory.Factory):
       class Meta:
           model = base.User

       firstname = "John"
       lastname = "Doe"

You may now get "base.User" instances trivially:

   >>> john = UserFactory()
   <User: John Doe>

It is also possible to override the defined attributes by passing
keyword arguments to the factory:

   >>> jack = UserFactory(firstname="Jack")
   <User: Jack Doe>

A given class may be associated to many "Factory" subclasses:

   class EnglishUserFactory(factory.Factory):
       class Meta:
           model = base.User

       firstname = "John"
       lastname = "Doe"
       lang = 'en'


   class FrenchUserFactory(factory.Factory):
       class Meta:
           model = base.User

       firstname = "Jean"
       lastname = "Dupont"
       lang = 'fr'

   >>> EnglishUserFactory()
   <User: John Doe (en)>
   >>> FrenchUserFactory()
   <User: Jean Dupont (fr)>


Sequences
=========

When a field has a unique key, each object generated by the factory
should have a different value for that field. This is achieved with
the "Sequence" declaration:

   class UserFactory(factory.Factory):
       class Meta:
           model = models.User

       username = factory.Sequence(lambda n: 'user%d' % n)

   >>> UserFactory()
   <User: user1>
   >>> UserFactory()
   <User: user2>

Note: For more complex situations, you may also use the
  "@sequence()" decorator (note that "self" is not added as first
  parameter):

     class UserFactory(factory.Factory):
         class Meta:
             model = models.User

         @factory.sequence
         def username(n):
             return 'user%d' % n


LazyAttribute
=============

Some fields may be deduced from others, for instance the email based
on the username. The "LazyAttribute" handles such cases: it should
receive a function taking the object being built and returning the
value for the field:

   class UserFactory(factory.Factory):
       class Meta:
           model = models.User

       username = factory.Sequence(lambda n: 'user%d' % n)
       email = factory.LazyAttribute(lambda obj: '%s@example.com' % obj.username)

   >>> UserFactory()
   <User: user1 (user1@example.com)>

   >>> # The LazyAttribute handles overridden fields
   >>> UserFactory(username='john')
   <User: john (john@example.com)>

   >>> # They can be directly overridden as well
   >>> UserFactory(email='doe@example.com')
   <User: user3 (doe@example.com)>

Note: As for "Sequence", a "@lazy_attribute()" decorator is
  available:

   class UserFactory(factory.Factory):
       class Meta:
           model = models.User

       username = factory.Sequence(lambda n: 'user%d' % n)

       @factory.lazy_attribute
       def email(self):
           return '%s@example.com' % self.username


Inheritance
===========

Once a "base" factory has been defined for a given class, alternate
versions can be easily defined through subclassing.

The subclassed "Factory" will inherit all declarations from its
parent, and update them with its own declarations:

   class UserFactory(factory.Factory):
       class Meta:
           model = base.User

       firstname = "John"
       lastname = "Doe"
       group = 'users'

   class AdminFactory(UserFactory):
       admin = True
       group = 'admins'

   >>> user = UserFactory()
   >>> user
   <User: John Doe>
   >>> user.group
   'users'

   >>> admin = AdminFactory()
   >>> admin
   <User: John Doe (admin)>
   >>> admin.group  # The AdminFactory field has overridden the base field
   'admins'

Any argument of all factories in the chain can easily be overridden:

   >>> super_admin = AdminFactory(group='superadmins', lastname="Lennon")
   >>> super_admin
   <User: John Lennon (admin)>
   >>> super_admin.group  # Overridden at call time
   'superadmins'


Non-kwarg arguments
===================

Some classes take a few, non-kwarg arguments first.

This is handled by the "inline_args" attribute:

   class MyFactory(factory.Factory):
       class Meta:
           model = MyClass
           inline_args = ('x', 'y')

       x = 1
       y = 2
       z = 3

   >>> MyFactory(y=4)
   <MyClass(1, 4, z=3)>


Strategies
==========

All factories support two built-in strategies:

* "build" provides a local object

* "create" instantiates a local object, and saves it to the
  database.

Note: For 1.X versions, the "create" will actually call
  "AssociatedClass.objects.create", as for a Django model.Starting
  from 2.0, "factory.Factory.create()" simply calls
  "AssociatedClass(**kwargs)". You should use "DjangoModelFactory" for
  Django models.

When a "Factory" includes related fields ("SubFactory",
"RelatedFactory"), the parent's strategy will be pushed onto related
factories.

Calling a "Factory" subclass will provide an object through the
default strategy:

   class MyFactory(factory.Factory):
       class Meta:
           model = MyClass

   >>> MyFactory.create()
   <MyFactory: X (saved)>

   >>> MyFactory.build()
   <MyFactory: X (unsaved)>

   >>> MyFactory()  # equivalent to MyFactory.create()
   <MyClass: X (saved)>

The default strategy can be changed by setting the "class Meta"
"strategy" attribute.
