summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-01 01:35:26 +0100
committerRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-03 21:38:46 +0100
commitebdfb8cc5bab1e59b593a4ea60e55b9e7af455ef (patch)
tree893373eb7e207a9115d0df16922ee64508aaa22a /docs
parent050af55b77372b39fb6efecfb93bb6ee8ee425ed (diff)
downloadfactory-boy-ebdfb8cc5bab1e59b593a4ea60e55b9e7af455ef.tar
factory-boy-ebdfb8cc5bab1e59b593a4ea60e55b9e7af455ef.tar.gz
Improve Iterator and SubFactory declarations.
* Iterator now cycles by default * Iterator can be provided with a custom getter * SubFactory accepts a factory import path as well Deprecates: * InfiniteIterator * CircularSubFactory Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/reference.rst78
1 files changed, 72 insertions, 6 deletions
diff --git a/docs/reference.rst b/docs/reference.rst
index 289a9a8..edbd527 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -607,7 +607,9 @@ Circular imports
Some factories may rely on each other in a circular manner.
This issue can be handled by passing the absolute import path to the target
-:class:`Factory` to the :class:`SubFactory`:
+:class:`Factory` to the :class:`SubFactory`.
+
+.. versionadded:: 1.3.0
.. code-block:: python
@@ -633,6 +635,19 @@ Obviously, such circular relationships require careful handling of loops:
<john (group: MyGroup)>
+.. class:: CircularSubFactory(module_name, symbol_name, **kwargs)
+
+ .. OHAI_VIM**
+
+ Lazily imports ``module_name.symbol_name`` at the first call.
+
+.. deprecated:: 1.3.0
+ Merged into :class:`SubFactory`; will be removed in 2.0.0.
+
+ Replace ``factory.CircularSubFactory('some.module', 'Symbol', **kwargs)``
+ with ``factory.SubFactory('some.module.Symbol', **kwargs)``
+
+
SelfAttribute
"""""""""""""
@@ -708,14 +723,13 @@ Iterator
The :class:`Iterator` declaration takes succesive values from the given
iterable. When it is exhausted, it starts again from zero (unless ``cycle=False``).
-.. note:: Versions prior to 1.3.0 declared both :class:`Iterator` (for ``cycle=False``)
- and :class:`InfiniteIterator` (for ``cycle=True``).
-
- :class:`InfiniteIterator` is deprecated as of 1.3.0 and will be removed in 2.0.0
-
The ``cycle`` argument is only useful for advanced cases, where the provided
iterable has no end (as wishing to cycle it means storing values in memory...).
+.. versionadded:: 1.3.0
+ The ``cycle`` argument is available as of v1.3.0; previous versions
+ had a behaviour equivalent to ``cycle=False``.
+
Each call to the factory will receive the next value from the iterable:
.. code-block:: python
@@ -750,6 +764,8 @@ This is handled by the :attr:`~Iterator.getter` attribute: this is a function
that accepts as sole parameter a value from the iterable, and returns an
adequate value.
+.. versionadded:: 1.3.0
+
.. code-block:: python
class UserFactory(factory.Factory):
@@ -759,6 +775,56 @@ adequate value.
category = factory.Iterator(User.CATEGORY_CHOICES, getter=lambda c: c[0])
+Decorator
+~~~~~~~~~
+
+.. function:: iterator(func)
+
+
+When generating items of the iterator gets too complex for a simple list comprehension,
+use the :func:`iterator` decorator:
+
+.. warning:: The decorated function takes **no** argument,
+ notably no ``self`` parameter.
+
+.. code-block:: python
+
+ class UserFactory(factory.Factory):
+ FACTORY_FOR = User
+
+ @factory.iterator
+ def name():
+ with open('test/data/names.dat', 'r') as f:
+ for line in f:
+ yield line
+
+
+InfiniteIterator
+~~~~~~~~~~~~~~~~
+
+.. class:: InfiniteIterator(iterable)
+
+ Equivalent to ``factory.Iterator(iterable)``.
+
+.. deprecated:: 1.3.0
+ Merged into :class:`Iterator`; will be removed in v2.0.0.
+
+ Replace ``factory.InfiniteIterator(iterable)``
+ with ``factory.Iterator(iterable)``.
+
+
+.. function:: infinite_iterator(function)
+
+ Equivalent to ``factory.iterator(func)``.
+
+
+.. deprecated:: 1.3.0
+ Merged into :func:`iterator`; will be removed in v2.0.0.
+
+ Replace ``@factory.infinite_iterator`` with ``@factory.iterator``.
+
+
+
post-building hooks
"""""""""""""""""""