Merge tag '2.6.1' into debian/unstable

Release of factory_boy 2.6.1

8 files changed, 548 insertions, 66 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 7d77f7f..fa542f4 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -1,6 +1,107 @@
 ChangeLog
 =========
 
+.. _v2.6.0:
+
+2.6.0 (2015-10-20)
+------------------
+
+*New:*
+
+    - Add :attr:`factory.FactoryOptions.rename` to help handle conflicting names (:issue:`206`)
+    - Add support for random-yet-realistic values through `fake-factory <https://pypi.python.org/pypi/fake-factory>`_,
+      through the :class:`factory.Faker` class.
+    - :class:`factory.Iterator` no longer begins iteration of its argument at import time,
+      thus allowing to pass in a lazy iterator such as a Django queryset
+      (i.e ``factory.Iterator(models.MyThingy.objects.all())``).
+    - Simplify imports for ORM layers, now available through a simple ``factory`` import,
+      at ``factory.alchemy.SQLAlchemyModelFactory`` / ``factory.django.DjangoModelFactory`` / ``factory.mongoengine.MongoEngineFactory``.
+
+*Bugfix:*
+
+    - :issue:`201`: Properly handle custom Django managers when dealing with abstract Django models.
+    - :issue:`212`: Fix :meth:`factory.django.mute_signals` to handle Django's signal caching
+    - :issue:`228`: Don't load :func:`django.apps.apps.get_model()` until required
+    - :issue:`219`: Stop using :meth:`mogo.model.Model.new()`, deprecated 4 years ago.
+
+.. _v2.5.2:
+
+2.5.2 (2015-04-21)
+------------------
+
+*Bugfix:*
+
+    - Add support for Django 1.7/1.8
+    - Add support for mongoengine>=0.9.0 / pymongo>=2.1
+
+.. _v2.5.1:
+
+2.5.1 (2015-03-27)
+------------------
+
+*Bugfix:*
+
+    - Respect custom managers in :class:`~factory.django.DjangoModelFactory` (see :issue:`192`)
+    - Allow passing declarations (e.g :class:`~factory.Sequence`) as parameters to :class:`~factory.django.FileField`
+      and :class:`~factory.django.ImageField`.
+
+.. _v2.5.0:
+
+2.5.0 (2015-03-26)
+------------------
+
+*New:*
+
+    - Add support for getting/setting :mod:`factory.fuzzy`'s random state (see :issue:`175`, :issue:`185`).
+    - Support lazy evaluation of iterables in :class:`factory.fuzzy.FuzzyChoice` (see :issue:`184`).
+    - Support non-default databases at the factory level (see :issue:`171`)
+    - Make :class:`factory.django.FileField` and :class:`factory.django.ImageField` non-post_generation, i.e normal fields also available in ``save()`` (see :issue:`141`).
+
+*Bugfix:*
+
+    - Avoid issues when using :meth:`factory.django.mute_signals` on a base factory class (see :issue:`183`).
+    - Fix limitations of :class:`factory.StubFactory`, that can now use :class:`factory.SubFactory` and co (see :issue:`131`).
+
+
+*Deprecation:*
+
+    - Remove deprecated features from :ref:`v2.4.0`
+    - Remove the auto-magical sequence setup (based on the latest primary key value in the database) for Django and SQLAlchemy;
+      this relates to issues :issue:`170`, :issue:`153`, :issue:`111`, :issue:`103`, :issue:`92`, :issue:`78`. See https://github.com/rbarrois/factory_boy/commit/13d310f for technical details.
+
+.. warning:: Version 2.5.0 removes the 'auto-magical sequence setup' bug-and-feature.
+             This could trigger some bugs when tests expected a non-zero sequence reference.
+
+Upgrading
+"""""""""
+
+.. warning:: Version 2.5.0 removes features that were marked as deprecated in :ref:`v2.4.0 <v2.4.0>`.
+
+All ``FACTORY_*``-style attributes are now declared in a ``class Meta:`` section:
+
+.. code-block:: python
+
+    # Old-style, deprecated
+    class MyFactory(factory.Factory):
+        FACTORY_FOR = models.MyModel
+        FACTORY_HIDDEN_ARGS = ['a', 'b', 'c']
+
+    # New-style
+    class MyFactory(factory.Factory):
+        class Meta:
+            model = models.MyModel
+            exclude = ['a', 'b', 'c']
+
+A simple shell command to upgrade the code would be:
+
+.. code-block:: sh
+
+    # sed -i: inplace update
+    # grep -l: only file names, not matching lines
+    sed -i 's/FACTORY_FOR =/class Meta:\n        model =/' $(grep -l FACTORY_FOR $(find . -name '*.py'))
+
+This takes care of all ``FACTORY_FOR`` occurences; the files containing other attributes to rename can be found with ``grep -R  FACTORY .``
+
 
 .. _v2.4.1:
 
@@ -19,7 +120,7 @@ ChangeLog
 *New:*
 
     - Add support for :attr:`factory.fuzzy.FuzzyInteger.step`, thanks to `ilya-pirogov <https://github.com/ilya-pirogov>`_ (:issue:`120`)
-    - Add :meth:`~factory.django.mute_signals` decorator to temporarily disable some signals, thanks to `ilya-pirogov <https://github.com>`_ (:issue:`122`)
+    - Add :meth:`~factory.django.mute_signals` decorator to temporarily disable some signals, thanks to `ilya-pirogov <https://github.com/ilya-pirogov>`_ (:issue:`122`)
     - Add :class:`~factory.fuzzy.FuzzyFloat` (:issue:`124`)
     - Declare target model and other non-declaration fields in a ``class Meta`` section.
 
@@ -31,8 +132,6 @@ ChangeLog
       For :class:`factory.Factory`:
 
       * Rename :attr:`~factory.Factory.FACTORY_FOR` to :attr:`~factory.FactoryOptions.model`
-
-      * Rename :attr:`~factory.Factory.FACTORY_FOR` to :attr:`~factory.FactoryOptions.model`
       * Rename :attr:`~factory.Factory.ABSTRACT_FACTORY` to :attr:`~factory.FactoryOptions.abstract`
       * Rename :attr:`~factory.Factory.FACTORY_STRATEGY` to :attr:`~factory.FactoryOptions.strategy`
       * Rename :attr:`~factory.Factory.FACTORY_ARG_PARAMETERS` to :attr:`~factory.FactoryOptions.inline_args`
diff --git a/docs/conf.py b/docs/conf.py
index 4f76d45..d5b86f4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,7 +51,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Factory Boy'
-copyright = u'2011-2013, Raphaël Barrois, Mark Sandstrom'
+copyright = u'2011-2015, Raphaël Barrois, Mark Sandstrom'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -114,7 +114,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -247,7 +247,7 @@ intersphinx_mapping = {
         'http://docs.djangoproject.com/en/dev/_objects/',
     ),
     'sqlalchemy': (
-        'http://docs.sqlalchemy.org/en/rel_0_8/',
-        'http://docs.sqlalchemy.org/en/rel_0_8/objects.inv',
+        'http://docs.sqlalchemy.org/en/rel_0_9/',
+        'http://docs.sqlalchemy.org/en/rel_0_9/objects.inv',
     ),
 }
diff --git a/docs/examples.rst b/docs/examples.rst
index ee521e3..e7f6057 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -114,9 +114,9 @@ We can now use our factories, for tests:
         def test_get_profile_stats(self):
             profiles = []
 
-            profiles.extend(factories.ProfileFactory.batch_create(4))
-            profiles.extend(factories.FemaleProfileFactory.batch_create(2))
-            profiles.extend(factories.ProfileFactory.batch_create(2, planet="Tatooine"))
+            profiles.extend(factories.ProfileFactory.create_batch(4))
+            profiles.extend(factories.FemaleProfileFactory.create_batch(2))
+            profiles.extend(factories.ProfileFactory.create_batch(2, planet="Tatooine"))
 
             stats = business_logic.profile_stats(profiles)
             self.assertEqual({'Earth': 6, 'Mars': 2}, stats.planets)
@@ -130,7 +130,7 @@ Or for fixtures:
     from . import factories
 
     def make_objects():
-        factories.ProfileFactory.batch_create(size=50)
+        factories.ProfileFactory.create_batch(size=50)
 
         # Let's create a few, known objects.
         factories.ProfileFactory(
diff --git a/docs/fuzzy.rst b/docs/fuzzy.rst
index 1480419..6b06608 100644
--- a/docs/fuzzy.rst
+++ b/docs/fuzzy.rst
@@ -8,6 +8,8 @@ Some tests may be interested in testing with fuzzy, random values.
 This is handled by the :mod:`factory.fuzzy` module, which provides a few
 random declarations.
 
+.. note:: Use ``import factory.fuzzy`` to load this module.
+
 
 FuzzyAttribute
 --------------
@@ -62,8 +64,11 @@ FuzzyChoice
     The :class:`FuzzyChoice` fuzzer yields random choices from the given
     iterable.
 
-    .. note:: The passed in :attr:`choices` will be converted into a list at
-              declaration time.
+    .. note:: The passed in :attr:`choices` will be converted into a list upon
+              first use, not at declaration time.
+
+              This allows passing in, for instance, a Django queryset that will
+              only hit the database during the database, not at import time.
 
     .. attribute:: choices
 
@@ -338,3 +343,33 @@ They should inherit from the :class:`BaseFuzzyAttribute` class, and override its
 
         The method responsible for generating random values.
         *Must* be overridden in subclasses.
+
+
+Managing randomness
+-------------------
+
+Using :mod:`random` in factories allows to "fuzz" a program efficiently.
+However, it's sometimes required to *reproduce* a failing test.
+
+:mod:`factory.fuzzy` uses a separate instance of :class:`random.Random`,
+and provides a few helpers for this:
+
+.. method:: get_random_state()
+
+    Call :meth:`get_random_state` to retrieve the random generator's current
+    state.
+
+.. method:: set_random_state(state)
+
+    Use :meth:`set_random_state` to set a custom state into the random generator
+    (fetched from :meth:`get_random_state` in a previous run, for instance)
+
+.. method:: reseed_random(seed)
+
+    The :meth:`reseed_random` function allows to load a chosen seed into the random generator.
+
+
+Custom :class:`BaseFuzzyAttribute` subclasses **SHOULD**
+use :obj:`factory.fuzzy._random` as a randomness source; this ensures that
+data they generate can be regenerated using the simple state from
+:meth:`get_random_state`.
diff --git a/docs/ideas.rst b/docs/ideas.rst
index f3c9e62..6e3962d 100644
--- a/docs/ideas.rst
+++ b/docs/ideas.rst
@@ -6,4 +6,4 @@ This is a list of future features that may be incorporated into factory_boy:
 
 * When a :class:`Factory` is built or created, pass the calling context throughout the calling chain instead of custom solutions everywhere
 * Define a proper set of rules for the support of third-party ORMs
-
+* Properly evaluate nested declarations (e.g ``factory.fuzzy.FuzzyDate(start_date=factory.SelfAttribute('since'))``)
diff --git a/docs/orms.rst b/docs/orms.rst
index 2aa27b2..af20917 100644
--- a/docs/orms.rst
+++ b/docs/orms.rst
@@ -15,7 +15,7 @@ Django
 
 
 The first versions of factory_boy were designed specifically for Django,
-but the library has now evolved to be framework-independant.
+but the library has now evolved to be framework-independent.
 
 Most features should thus feel quite familiar to Django users.
 
@@ -35,20 +35,29 @@ All factories for a Django :class:`~django.db.models.Model` should use the
     * The :attr:`~factory.FactoryOptions.model` attribute also supports the ``'app.Model'``
       syntax
     * :func:`~factory.Factory.create()` uses :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`
-    * :func:`~factory.Factory._setup_next_sequence()` selects the next unused primary key value
     * When using :class:`~factory.RelatedFactory` or :class:`~factory.PostGeneration`
       attributes, the base object will be :meth:`saved <django.db.models.Model.save>`
       once all post-generation hooks have run.
 
-    .. attribute:: FACTORY_DJANGO_GET_OR_CREATE
 
-        .. deprecated:: 2.4.0
-                        See :attr:`DjangoOptions.django_get_or_create`.
+.. note:: With Django versions 1.8.0 to 1.8.3, it was no longer possible to call ``.build()``
+          on a factory if this factory used a :class:`~factory.SubFactory` pointing
+          to another model: Django refused to set a :class:`~djang.db.models.ForeignKey`
+          to an unsaved :class:`~django.db.models.Model` instance.
+
+          See https://code.djangoproject.com/ticket/10811 and https://code.djangoproject.com/ticket/25160 for details.
 
 
 .. class:: DjangoOptions(factory.base.FactoryOptions)
 
-    The ``class Meta`` on a :class:`~DjangoModelFactory` supports an extra parameter:
+    The ``class Meta`` on a :class:`~DjangoModelFactory` supports extra parameters:
+
+    .. attribute:: database
+
+        .. versionadded:: 2.5.0
+
+        All queries to the related model will be routed to the given database.
+        It defaults to ``'default'``.
 
     .. attribute:: django_get_or_create
 
@@ -117,7 +126,7 @@ Extra fields
         :param str from_path: Use data from the file located at ``from_path``,
                               and keep its filename
         :param file from_file: Use the contents of the provided file object; use its filename
-                               if available
+                               if available, unless ``filename`` is also provided.
         :param bytes data: Use the provided bytes as file contents
         :param str filename: The filename for the FileField
 
@@ -264,6 +273,34 @@ factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngin
 
               This feature makes it possible to use :class:`~factory.SubFactory` to create embedded document.
 
+A minimalist example:
+
+.. code-block:: python
+
+    import mongoengine
+
+    class Address(mongoengine.EmbeddedDocument):
+        street = mongoengine.StringField()
+
+    class Person(mongoengine.Document):
+        name = mongoengine.StringField()
+        address = mongoengine.EmbeddedDocumentField(Address)
+
+    import factory
+
+    class AddressFactory(factory.mongoengine.MongoEngineFactory):
+        class Meta:
+            model = Address
+
+        street = factory.Sequence(lambda n: 'street%d' % n)
+
+    class PersonFactory(factory.mongoengine.MongoEngineFactory):
+        class Meta:
+            model = Person
+
+        name = factory.Sequence(lambda n: 'name%d' % n)
+        address = factory.SubFactory(AddressFactory)
+
 
 SQLAlchemy
 ----------
@@ -284,12 +321,7 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:
     This class provides the following features:
 
     * :func:`~factory.Factory.create()` uses :meth:`sqlalchemy.orm.session.Session.add`
-    * :func:`~factory.Factory._setup_next_sequence()` selects the next unused primary key value
 
-    .. attribute:: FACTORY_SESSION
-
-        .. deprecated:: 2.4.0
-                        See :attr:`~SQLAlchemyOptions.sqlalchemy_session`.
 
 .. class:: SQLAlchemyOptions(factory.base.FactoryOptions)
 
@@ -301,7 +333,11 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:
         SQLAlchemy session to use to communicate with the database when creating
         an object through this :class:`SQLAlchemyModelFactory`.
 
-A (very) simple exemple:
+    .. attribute:: force_flush
+
+        Force a session flush() at the end of :func:`~factory.alchemy.SQLAlchemyModelFactory._create()`.
+
+A (very) simple example:
 
 .. code-block:: python
 
@@ -309,9 +345,8 @@ A (very) simple exemple:
     from sqlalchemy.ext.declarative import declarative_base
     from sqlalchemy.orm import scoped_session, sessionmaker
 
-    session = scoped_session(sessionmaker())
     engine = create_engine('sqlite://')
-    session.configure(bind=engine)
+    session = scoped_session(sessionmaker(bind=engine))
     Base = declarative_base()
 
 
@@ -324,8 +359,9 @@ A (very) simple exemple:
 
     Base.metadata.create_all(engine)
 
+    import factory
 
-    class UserFactory(SQLAlchemyModelFactory):
+    class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
         class Meta:
             model = User
             sqlalchemy_session = session   # the SQLAlchemy session object
@@ -341,3 +377,112 @@ A (very) simple exemple:
     <User: User 1>
     >>> session.query(User).all()
     [<User: User 1>]
+
+
+Managing sessions
+"""""""""""""""""
+
+Since `SQLAlchemy`_ is a general purpose library,
+there is no "global" session management system.
+
+The most common pattern when working with unit tests and ``factory_boy``
+is to use `SQLAlchemy`_'s :class:`sqlalchemy.orm.scoping.scoped_session`:
+
+* The test runner configures some project-wide :class:`~sqlalchemy.orm.scoping.scoped_session`
+* Each :class:`~SQLAlchemyModelFactory` subclass uses this
+  :class:`~sqlalchemy.orm.scoping.scoped_session` as its :attr:`~SQLAlchemyOptions.sqlalchemy_session`
+* The :meth:`~unittest.TestCase.tearDown` method of tests calls
+  :meth:`Session.remove <sqlalchemy.orm.scoping.scoped_session.remove>`
+  to reset the session.
+
+.. note:: See the excellent :ref:`SQLAlchemy guide on scoped_session <sqlalchemy:unitofwork_contextual>`
+          for details of :class:`~sqlalchemy.orm.scoping.scoped_session`'s usage.
+
+          The basic idea is that declarative parts of the code (including factories)
+          need a simple way to access the "current session",
+          but that session will only be created and configured at a later point.
+
+          The :class:`~sqlalchemy.orm.scoping.scoped_session` handles this,
+          by virtue of only creating the session when a query is sent to the database.
+
+
+Here is an example layout:
+
+- A global (test-only?) file holds the :class:`~sqlalchemy.orm.scoping.scoped_session`:
+
+.. code-block:: python
+
+    # myprojet/test/common.py
+
+    from sqlalchemy import orm
+    Session = orm.scoped_session(orm.sessionmaker())
+
+
+- All factory access it:
+
+.. code-block:: python
+
+    # myproject/factories.py
+
+    import factory
+    import factory.alchemy
+
+    from . import models
+    from .test import common
+
+    class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
+        class Meta:
+            model = models.User
+
+            # Use the not-so-global scoped_session
+            # Warning: DO NOT USE common.Session()!
+            sqlalchemy_session = common.Session
+
+        name = factory.Sequence(lambda n: "User %d" % n)
+
+
+- The test runner configures the :class:`~sqlalchemy.orm.scoping.scoped_session` when it starts:
+
+.. code-block:: python
+
+    # myproject/test/runtests.py
+
+    import sqlalchemy
+
+    from . import common
+
+    def runtests():
+        engine = sqlalchemy.create_engine('sqlite://')
+
+        # It's a scoped_session, and now is the time to configure it.
+        common.Session.configure(bind=engine)
+
+        run_the_tests
+
+
+- :class:`test cases <unittest.TestCase>` use this ``scoped_session``,
+  and clear it after each test (for isolation):
+
+.. code-block:: python
+
+    # myproject/test/test_stuff.py
+
+    import unittest
+
+    from . import common
+
+    class MyTest(unittest.TestCase):
+
+        def setUp(self):
+            # Prepare a new, clean session
+            self.session = common.Session()
+
+        def test_something(self):
+            u = factories.UserFactory()
+            self.assertEqual([u], self.session.query(User).all())
+
+        def tearDown(self):
+            # Rollback the session => no changes to the database
+            self.session.rollback()
+            # Remove it, so that the next test gets a new Session()
+            common.Session.remove()
diff --git a/docs/recipes.rst b/docs/recipes.rst
index 72dacef..df86bac 100644
--- a/docs/recipes.rst
+++ b/docs/recipes.rst
@@ -33,6 +33,29 @@ use the :class:`~factory.SubFactory` declaration:
         group = factory.SubFactory(GroupFactory)
 
 
+Choosing from a populated table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the target of the :class:`~django.db.models.ForeignKey` should be
+chosen from a pre-populated table
+(e.g :class:`django.contrib.contenttypes.models.ContentType`),
+simply use a :class:`factory.Iterator` on the chosen queryset:
+
+.. code-block:: python
+
+    import factory, factory.django
+    from . import models
+
+    class UserFactory(factory.django.DjangoModelFactory):
+        class Meta:
+            model = models.User
+
+        language = factory.Iterator(models.Language.objects.all())
+
+Here, ``models.Language.objects.all()`` won't be evaluated until the
+first call to ``UserFactory``; thus avoiding DB queries at import time.
+
+
 Reverse dependencies (reverse ForeignKey)
 -----------------------------------------
 
@@ -125,8 +148,8 @@ factory_boy related factories.
           method.
 
 
-Simple ManyToMany
------------------
+Simple Many-to-many relationship
+--------------------------------
 
 Building the adequate link between two models depends heavily on the use case;
 factory_boy doesn't provide a "all in one tools" as for :class:`~factory.SubFactory`
@@ -144,7 +167,7 @@ hook:
 
     class User(models.Model):
         name = models.CharField()
-        groups = models.ManyToMany(Group)
+        groups = models.ManyToManyField(Group)
 
 
     # factories.py
@@ -181,8 +204,8 @@ the ``groups`` declaration will add passed in groups to the set of groups for th
 user.
 
 
-ManyToMany with a 'through'
----------------------------
+Many-to-many relation with a 'through'
+--------------------------------------
 
 
 If only one link is required, this can be simply performed with a :class:`RelatedFactory`.
@@ -196,7 +219,7 @@ If more links are needed, simply add more :class:`RelatedFactory` declarations:
 
     class Group(models.Model):
         name = models.CharField()
-        members = models.ManyToMany(User, through='GroupLevel')
+        members = models.ManyToManyField(User, through='GroupLevel')
 
     class GroupLevel(models.Model):
         user = models.ForeignKey(User)
@@ -327,3 +350,97 @@ default :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`
            manager = cls._get_manager(model_class)
            # The default would use ``manager.create(*args, **kwargs)``
            return manager.create_user(*args, **kwargs)
+
+
+Forcing the sequence counter
+----------------------------
+
+A common pattern with factory_boy is to use a :class:`factory.Sequence` declaration
+to provide varying values to attributes declared as unique.
+
+However, it is sometimes useful to force a given value to the counter, for instance
+to ensure that tests are properly reproductible.
+
+factory_boy provides a few hooks for this:
+
+
+Forcing the value on a per-call basis
+    In order to force the counter for a specific :class:`~factory.Factory` instantiation,
+    just pass the value in the ``__sequence=42`` parameter:
+
+    .. code-block:: python
+
+        class AccountFactory(factory.Factory):
+            class Meta:
+                model = Account
+            uid = factory.Sequence(lambda n: n)
+            name = "Test"
+
+    .. code-block:: pycon
+
+        >>> obj1 = AccountFactory(name="John Doe", __sequence=10)
+        >>> obj1.uid  # Taken from the __sequence counter
+        10
+        >>> obj2 = AccountFactory(name="Jane Doe")
+        >>> obj2.uid  # The base sequence counter hasn't changed
+        1
+
+
+Resetting the counter globally
+    If all calls for a factory must start from a deterministic number,
+    use :meth:`factory.Factory.reset_sequence`; this will reset the counter
+    to its initial value (as defined by :meth:`factory.Factory._setup_next_sequence`).
+
+    .. code-block:: pycon
+
+        >>> AccountFactory().uid
+        1
+        >>> AccountFactory().uid
+        2
+        >>> AccountFactory.reset_sequence()
+        >>> AccountFactory().uid  # Reset to the initial value
+        1
+        >>> AccountFactory().uid
+        2
+
+    It is also possible to reset the counter to a specific value:
+
+    .. code-block:: pycon
+
+        >>> AccountFactory.reset_sequence(10)
+        >>> AccountFactory().uid
+        10
+        >>> AccountFactory().uid
+        11
+
+    This recipe is most useful in a :class:`~unittest.TestCase`'s
+    :meth:`~unittest.TestCase.setUp` method.
+
+
+Forcing the initial value for all projects
+    The sequence counter of a :class:`~factory.Factory` can also be set
+    automatically upon the first call through the
+    :meth:`~factory.Factory._setup_next_sequence` method; this helps when the
+    objects's attributes mustn't conflict with pre-existing data.
+
+    A typical example is to ensure that running a Python script twice will create
+    non-conflicting objects, by setting up the counter to "max used value plus one":
+
+    .. code-block:: python
+
+        class AccountFactory(factory.django.DjangoModelFactory):
+            class Meta:
+                model = models.Account
+
+            @classmethod
+            def _setup_next_sequence(cls):
+                try:
+                    return models.Accounts.objects.latest('uid').uid + 1
+                except models.Account.DoesNotExist:
+                    return 1
+
+    .. code-block:: pycon
+
+        >>> Account.objects.create(uid=42, name="Blah")
+        >>> AccountFactory.create()  # Sets up the account number based on the latest uid
+        <Account uid=43, name=Test>
diff --git a/docs/reference.rst b/docs/reference.rst
index b0dda50..b5ccd16 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -42,7 +42,7 @@ The :class:`Factory` class
         It will be automatically set to ``True`` if neither the :class:`Factory`
         subclass nor its parents define the :attr:`~FactoryOptions.model` attribute.
 
-        .. warning:: This flag is reset to ``False`` When a :class:`Factory` subclasses
+        .. warning:: This flag is reset to ``False`` when a :class:`Factory` subclasses
                      another one if a :attr:`~FactoryOptions.model` is set.
 
         .. versionadded:: 2.4.0
@@ -106,43 +106,36 @@ The :class:`Factory` class
         .. versionadded:: 2.4.0
 
 
-    .. attribute:: strategy
-
-        Use this attribute to change the strategy used by a :class:`Factory`.
-        The default is :data:`BUILD_STRATEGY`.
-
+    .. attribute:: rename
 
+        Sometimes, a model expect a field with a name already used by one
+        of :class:`Factory`'s methods.
 
-.. class:: Factory
-
-    .. note:: In previous versions, the fields of :class:`class Meta <factory.FactoryOptions>` were
-              defined as class attributes on :class:`Factory`. This is now deprecated and will be removed
-              in 2.5.0.
+        In this case, the :attr:`rename` attributes allows to define renaming
+        rules: the keys of the :attr:`rename` dict are those used in the
+        :class:`Factory` declarations, and their values the new name:
 
-              .. attribute:: FACTORY_FOR
+        .. code-block:: python
 
-                  .. deprecated:: 2.4.0
-                                  See :attr:`FactoryOptions.model`.
+            class ImageFactory(factory.Factory):
+                # The model expects "attributes"
+                form_attributes = ['thumbnail', 'black-and-white']
 
-              .. attribute:: ABSTRACT_FACTORY
+                class Meta:
+                    model = Image
+                    rename = {'form_attributes': 'attributes'}
 
-                  .. deprecated:: 2.4.0
-                                  See :attr:`FactoryOptions.abstract`.
+        .. versionadded: 2.6.0
 
-              .. attribute:: FACTORY_ARG_PARAMETERS
 
-                  .. deprecated:: 2.4.0
-                                  See :attr:`FactoryOptions.inline_args`.
+    .. attribute:: strategy
 
-              .. attribute:: FACTORY_HIDDEN_ARGS
+        Use this attribute to change the strategy used by a :class:`Factory`.
+        The default is :data:`CREATE_STRATEGY`.
 
-                  .. deprecated:: 2.4.0
-                                  See :attr:`FactoryOptions.exclude`.
 
-              .. attribute:: FACTORY_STRATEGY
 
-                  .. deprecated:: 2.4.0
-                                  See :attr:`FactoryOptions.strategy`.
+.. class:: Factory
 
 
     **Class-level attributes:**
@@ -258,7 +251,6 @@ The :class:`Factory` class
 
         .. OHAI_VIM**
 
-
     .. classmethod:: _setup_next_sequence(cls)
 
         This method will compute the first value to use for the sequence counter
@@ -398,7 +390,7 @@ factory_boy supports two main strategies for generating instances, plus stubs.
                  when using the ``create`` strategy.
 
                  That policy will be used if the
-                 :attr:`associated class <FactoryOptions.model` has an ``objects``
+                 :attr:`associated class <FactoryOptions.model>` has an ``objects``
                  attribute *and* the :meth:`~Factory._create` classmethod of the
                  :class:`Factory` wasn't overridden.
 
@@ -482,6 +474,83 @@ factory_boy supports two main strategies for generating instances, plus stubs.
 Declarations
 ------------
 
+
+Faker
+"""""
+
+.. class:: Faker(provider, locale=None, **kwargs)
+
+    .. OHAIVIM**
+
+    In order to easily define realistic-looking factories,
+    use the :class:`Faker` attribute declaration.
+
+    This is a wrapper around `fake-factory <https://pypi.python.org/pypi/fake-factory>`_;
+    its argument is the name of a ``fake-factory`` provider:
+
+    .. code-block:: python
+
+        class UserFactory(factory.Factory):
+            class Meta:
+                model = User
+
+            name = factory.Faker('name')
+
+    .. code-block:: pycon
+
+        >>> user = UserFactory()
+        >>> user.name
+        'Lucy Cechtelar'
+
+
+    .. attribute:: locale
+
+        If a custom locale is required for one specific field,
+        use the ``locale`` parameter:
+
+        .. code-block:: python
+
+            class UserFactory(factory.Factory):
+                class Meta:
+                    model = User
+
+                name = factory.Faker('name', locale='fr_FR')
+
+        .. code-block:: pycon
+
+            >>> user = UserFactory()
+            >>> user.name
+            'Jean Valjean'
+
+
+    .. classmethod:: override_default_locale(cls, locale)
+
+        If the locale needs to be overridden for a whole test,
+        use :meth:`~factory.Faker.override_default_locale`:
+
+        .. code-block:: pycon
+
+            >>> with factory.Faker.override_default_locale('de_DE'):
+            ...     UserFactory()
+            <User: Johannes Brahms>
+
+    .. classmethod:: add_provider(cls, locale=None)
+
+        Some projects may need to fake fields beyond those provided by ``fake-factory``;
+        in such cases, use :meth:`factory.Faker.add_provider` to declare additional providers
+        for those fields:
+
+        .. code-block:: python
+
+            factory.Faker.add_provider(SmileyProvider)
+
+            class FaceFactory(factory.Factory):
+                class Meta:
+                    model = Face
+
+                smiley = factory.Faker('smiley')
+
+
 LazyAttribute
 """""""""""""
 
@@ -565,7 +634,7 @@ This declaration takes a single argument, a function accepting a single paramete
 
 
 .. note:: An extra kwarg argument, ``type``, may be provided.
-          This feature is deprecated in 1.3.0 and will be removed in 2.0.0.
+          This feature was deprecated in 1.3.0 and will be removed in 2.0.0.
 
 
 .. code-block:: python
@@ -1221,7 +1290,7 @@ For instance, a :class:`PostGeneration` hook is declared as ``post``:
             model = SomeObject
 
         @post_generation
-        def post(self, create, extracted, **kwargs):
+        def post(obj, create, extracted, **kwargs):
             obj.set_origin(create)
 
 .. OHAI_VIM**
@@ -1343,6 +1412,23 @@ If a value if passed for the :class:`RelatedFactory` attribute, this disables
     1
 
 
+.. note:: The target of the :class:`RelatedFactory` is evaluated *after* the initial factory has been instantiated.
+          This means that calls to :class:`factory.SelfAttribute` cannot go higher than this :class:`RelatedFactory`:
+
+          .. code-block:: python
+
+              class CountryFactory(factory.Factory):
+                  class Meta:
+                      model = Country
+
+                  lang = 'fr'
+                  capital_city = factory.RelatedFactory(CityFactory, 'capital_of',
+                      # factory.SelfAttribute('..lang') will crash, since the context of
+                      # ``CountryFactory`` has already been evaluated.
+                      main_lang=factory.SelfAttribute('capital_of.lang'),
+                  )
+
+
 PostGeneration
 """"""""""""""