doc: Add recipe for SelfAttribute('..X').

Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>

1 files changed, 55 insertions, 2 deletions

diff --git a/docs/recipes.rst b/docs/recipes.rst
index 8af0c8f..b148cd5 100644
--- a/docs/recipes.rst
+++ b/docs/recipes.rst
@@ -25,7 +25,7 @@ use the :class:`~factory.SubFactory` declaration:
     import factory
     from . import models
 
-    class UserFactory(factory.Factory):
+    class UserFactory(factory.DjangoModelFactory):
         FACTORY_FOR = models.User
 
         first_name = factory.Sequence(lambda n: "Agent %03d" % n)
@@ -52,7 +52,7 @@ use a :class:`~factory.RelatedFactory` declaration:
 
 
     # factories.py
-    class UserFactory(factory.Factory):
+    class UserFactory(factory.DjangoModelFactory):
         FACTORY_FOR = models.User
 
         log = factory.RelatedFactory(UserLogFactory, 'user', action=models.UserLog.ACTION_CREATE)
@@ -60,3 +60,56 @@ use a :class:`~factory.RelatedFactory` declaration:
 
 When a :class:`UserFactory` is instantiated, factory_boy will call
 ``UserLogFactory(user=that_user, action=...)`` just before returning the created ``User``.
+
+
+Copying fields to a SubFactory
+------------------------------
+
+When a field of a related class should match one of the container:
+
+
+.. code-block:: python
+
+    # models.py
+    class Country(models.Model):
+        name = models.CharField()
+        lang = models.CharField()
+
+    class User(models.Model):
+        name = models.CharField()
+        lang = models.CharField()
+        country = models.ForeignKey(Country)
+
+    class Company(models.Model):
+        name = models.CharField()
+        owner = models.ForeignKey(User)
+        country = models.ForeignKey(Country)
+
+
+Here, we want:
+
+- The User to have the lang of its country (``factory.SelfAttribute('country.lang')``)
+- The Company owner to live in the country of the company (``factory.SelfAttribute('..country')``)
+
+.. code-block:: python
+
+    # factories.py
+    class CountryFactory(factory.DjangoModelFactory):
+        FACTORY_FOR = models.Country
+
+        name = factory.Iterator(["France", "Italy", "Spain"])
+        lang = factory.Iterator(['fr', 'it', 'es'])
+
+    class UserFactory(factory.DjangoModelFactory):
+        FACTORY_FOR = models.User
+
+        name = "John"
+        lang = factory.SelfAttribute('country.lang')
+        country = factory.SubFactory(CountryFactory)
+
+    class CompanyFactory(factory.DjangoModelFactory):
+        FACTORY_FOR = models.Company
+
+        name = "ACME, Inc."
+        country = factory.SubFactory(CountryFactory)
+        owner = factory.SubFactory(UserFactory, country=factory.SelfAttribute('..country))