From ebdfb8cc5bab1e59b593a4ea60e55b9e7af455ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= Date: Fri, 1 Mar 2013 01:35:26 +0100 Subject: Improve Iterator and SubFactory declarations. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- docs/reference.rst | 78 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 72 insertions(+), 6 deletions(-) (limited to 'docs') 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: +.. 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 """"""""""""""""""" -- cgit v1.2.3