summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-05 22:16:54 +0100
committerRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-05 22:16:54 +0100
commitd50993b1bda6e8c0fab1c062affa61a4e3b35216 (patch)
tree86f6d9bf18af9efacc5502e8e7a7de82acc79ae9 /docs
parent2bc0fc8413c02a7faf3a116fe875d76bc3403117 (diff)
downloadfactory-boy-d50993b1bda6e8c0fab1c062affa61a4e3b35216.tar
factory-boy-d50993b1bda6e8c0fab1c062affa61a4e3b35216.tar.gz
Improve doc on post-generation hooks (Closes #36).
This was the last missing bit from PR#36 by @gotgenes. Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/reference.rst46
1 files changed, 45 insertions, 1 deletions
diff --git a/docs/reference.rst b/docs/reference.rst
index 85b299c..06eee85 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -847,7 +847,7 @@ InfiniteIterator
-post-building hooks
+Post-generation hooks
"""""""""""""""""""
Some objects expect additional method calls or complex processing for proper definition.
@@ -859,6 +859,49 @@ To support this pattern, factory_boy provides the following tools:
- :class:`RelatedFactory`: this builds or creates a given factory *after* building/creating the first Factory.
+Extracting parameters
+"""""""""""""""""""""
+
+All post-building hooks share a common base for picking parameters from the
+set of attributes passed to the :class:`Factory`.
+
+For instance, a :class:`PostGeneration` hook is declared as ``post``:
+
+.. code-block:: python
+
+ class SomeFactory(factory.Factory):
+ FACTORY_FOR = SomeObject
+
+ @post_generation
+ def post(self, create, extracted, **kwargs):
+ obj.set_origin(create)
+
+.. OHAI_VIM**
+
+
+When calling the factory, some arguments will be extracted for this method:
+
+- If a ``post`` argument is passed, it will be passed as the ``extracted`` field
+- Any argument starting with ``post__XYZ`` will be extracted, its ``post__`` prefix
+ removed, and added to the kwargs passed to the post-generation hook.
+
+Extracted arguments won't be passed to the :attr:`~Factory.FACTORY_FOR` class.
+
+Thus, in the following call:
+
+.. code-block:: pycon
+
+ >>> SomeFactory(
+ post=1,
+ post_x=2,
+ post__y=3,
+ post__z__t=42,
+ )
+
+The ``post`` hook will receive ``1`` as ``extracted`` and ``{'y': 3, 'z__t': 42}``
+as keyword arguments; ``{'post_x': 2}`` will be passed to ``SomeFactory.FACTORY_FOR``.
+
+
RelatedFactory
""""""""""""""
@@ -1048,6 +1091,7 @@ the extracted value must be iterable:
>>> UserFactory() # Calls user.set_password('', 'sha1')
>>> UserFactory(password=('test', 'md5')) # Calls user.set_password('test', 'md5')
+ >>> UserFactory(password__disabled=True) # Calls user.set_password('', 'sha1', disabled=True)
>>> # Always pass in a good iterable:
>>> UserFactory(password=('test',)) # Calls user.set_password('test')