Add support for get_or_create in DjangoModelFactory.

2 files changed, 35 insertions, 2 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 9a4a64e..4b24797 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -13,8 +13,8 @@ ChangeLog
     - The default :attr:`~factory.Sequence.type` for :class:`~factory.Sequence` is now :obj:`int`
     - Fields listed in :attr:`~factory.Factory.FACTORY_HIDDEN_ARGS` won't be passed to
       the associated class' constructor
-
-    - Add support for ``get_or_create`` in :class:`~factory.DjangoModelFactory`
+    - Add support for ``get_or_create`` in :class:`~factory.DjangoModelFactory`,
+      through :attr:`~factory.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`.
 
 *Removed:*
 
diff --git a/docs/orms.rst b/docs/orms.rst
index d6ff3c3..8e5b6f6 100644
--- a/docs/orms.rst
+++ b/docs/orms.rst
@@ -35,3 +35,36 @@ All factories for a Django :class:`~django.db.models.Model` should use the
     * 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
+
+        Fields whose name are passed in this list will be used to perform a
+        :meth:`Model.objects.get_or_create() <django.db.models.query.QuerySet.get_or_create>`
+        instead of the usual :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`:
+
+        .. code-block:: python
+
+            class UserFactory(factory.DjangoModelFactory):
+                FACTORY_FOR = models.User
+                FACTORY_DJANGO_GET_OR_CREATE = ('username',)
+
+                username = 'john'
+
+        .. code-block:: pycon
+
+            >>> User.objects.all()
+            []
+            >>> UserFactory()                   # Creates a new user
+            <User: john>
+            >>> User.objects.all()
+            [<User: john>]
+
+            >>> UserFactory()                   # Fetches the existing user
+            <User: john>
+            >>> User.objects.all()              # No new user!
+            [<User: john>]
+
+            >>> UserFactory(username='jack')    # Creates another user
+            <User: jack>
+            >>> User.objects.all()
+            [<User: john>, <User: jack>]