From d50993b1bda6e8c0fab1c062affa61a4e3b35216 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= Date: Tue, 5 Mar 2013 22:16:54 +0100 Subject: Improve doc on post-generation hooks (Closes #36). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was the last missing bit from PR#36 by @gotgenes. Signed-off-by: Raphaël Barrois --- docs/reference.rst | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) (limited to 'docs/reference.rst') 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') -- cgit v1.2.3