Add lazy loading to factory.Iterator.

factory.Iterator no longers begins iteration of its argument
on declaration, since this behavior may trigger database query
when that argument is, for instance, a Django queryset.

The ``factory.Iterator``'s argument will only be called when
the containing ``Factory`` is first evaluated; this means that
factories using ``factory.Iterator(models.MyThingy.objects.all())``
will no longer call the database at import time.

2 files changed, 26 insertions, 0 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 886db0b..0cbd4af 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -11,6 +11,9 @@ ChangeLog
     - 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())``).
 
 .. _v2.5.2:
 
diff --git a/docs/recipes.rst b/docs/recipes.rst
index 70eca46..3cbe6d2 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)
 -----------------------------------------