From 5394ff79b4ac51574f0e2a62f4335f85aa8436db Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= <mail@franek.fr>
Date: Sat, 15 Jun 2019 21:50:21 +0200
Subject: [PATCH] [DO NOT REVIEW] Change PostGenerationMethodCall example

User passwords do not depend on the generated object. The previous
example was tied to Django behavior, while `factory_boy` is a general
purpose library. Besides, this example gets in the way of removing the
duplicate call to `.save()` after `postgeneration` hooks.

Refs #366
---
 docs/reference.rst | 72 ++++++++++++----------------------------------
 1 file changed, 19 insertions(+), 53 deletions(-)

diff --git a/docs/reference.rst b/docs/reference.rst
index 12d7baac..a906acdf 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -1896,71 +1896,37 @@ Once the factory instance has been generated, the method specified in
 with any arguments specified in the :class:`PostGenerationMethodCall` declaration, by
 default.
 
-For example, to set a default password on a generated User instance
-during instantiation, we could make a declaration for a ``password``
-attribute like below:
+For example, we could use ``PostGenerationMethodCall`` to register created
+users in an external system.
 
 .. code-block:: python
 
-    class UserFactory(factory.Factory):
-        class Meta:
-            model = User
+    class User(models.Model):
+        name = models.CharField(max_length=191)
 
-        username = 'user'
-        password = factory.PostGenerationMethodCall('set_password',
-                                                    'defaultpassword')
+        def register(self, system, auth_token="ABC"):
+            self.registration_id = system.register(auth_token)
 
-When we instantiate a user from the ``UserFactory``, the factory
-will create a password attribute by calling ``User.set_password('defaultpassword')``.
-Thus, by default, our users will have a password set to ``'defaultpassword'``.
 
-.. code-block:: pycon
+    class UserFactory(factory.DjangoModelFactory):
+        class Meta:
+            model = User
 
-    >>> u = UserFactory()                             # Calls user.set_password('defaultpassword')
-    >>> u.check_password('defaultpassword')
-    True
+        name = 'user'
+        register = factory.PostGenerationMethodCall("register", DefaultRegistry())
 
 If the :class:`PostGenerationMethodCall` declaration contained no
 arguments or one argument, an overriding value can be passed
 directly to the method through a keyword argument matching the attribute name.
-For example we can override the default password specified in the declaration
-above by simply passing in the desired password as a keyword argument to the
-factory during instantiation.
 
 .. code-block:: pycon
 
-    >>> other_u = UserFactory(password='different')   # Calls user.set_password('different')
-    >>> other_u.check_password('defaultpassword')
-    False
-    >>> other_u.check_password('different')
-    True
-
-.. note::
-
-    For Django models, unless the object method called by
-    :class:`PostGenerationMethodCall` saves the object back to the
-    database, we will have to explicitly remember to save the object back
-    if we performed a ``create()``.
-
-    .. code-block:: pycon
-
-        >>> u = UserFactory.create()  # u.password has not been saved back to the database
-        >>> u.save()                  # we must remember to do it ourselves
-
-
-    We can avoid this by subclassing from :class:`DjangoModelFactory`,
-    instead, e.g.,
-
-    .. code-block:: python
-
-        class UserFactory(factory.django.DjangoModelFactory):
-            class Meta:
-                model = User
-
-            username = 'user'
-            password = factory.PostGenerationMethodCall('set_password',
-                                                        'defaultpassword')
-
+    >>> # DefaultRegistry uses UUID for identifiers.
+    >>> UserFactory().registration_id
+    'edf42c11-0065-43ad-ad3d-78ab7497aaae'
+    >>> # OtherRegistry uses int for identifiers.
+    >>> UserFactory(register=OtherRegistry()).registration_id
+    123456
 
 .. warning:: In order to keep a consistent and simple API, a :class:`PostGenerationMethodCall`
              allows *at most one* positional argument; all other parameters should be passed as
@@ -1971,8 +1937,8 @@ defaults present in the :class:`PostGenerationMethodCall` declaration.
 
 .. code-block:: pycon
 
-    >>> UserFactory(password__disabled=True)    # Calls user.set_password('', 'sha1', disabled=True)
-
+    >>> # Calls user.register(DefaultRegistry(), auth_token="DEF")
+    >>> UserFactory(register__auth_token="DEF")
 
 Module-level functions
 ----------------------