summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-03 21:00:11 +0100
committerRaphaël Barrois <raphael.barrois@polytechnique.org>2013-03-03 21:38:46 +0100
commit94a7e2659e3e8b6a9183b59aed06223cc1706c87 (patch)
tree01d45a25e707c1513c188d27f01b9bdf42e9df6d /docs
parente8dc25b5db5b470a64cc6a89259d476269fcebb5 (diff)
downloadfactory-boy-94a7e2659e3e8b6a9183b59aed06223cc1706c87.tar
factory-boy-94a7e2659e3e8b6a9183b59aed06223cc1706c87.tar.gz
Update ChangeLog for 1.3.0
Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/changelog.rst65
-rw-r--r--docs/reference.rst27
2 files changed, 77 insertions, 15 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 1e6d45b..eccc0a6 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -24,24 +24,77 @@ ChangeLog
1.3.0 (current)
---------------
-*New:*
+.. warning:: This version deprecates many magic or unexplicit features that will be
+ removed in v2.0.0.
- - Add :class:`~factory.CircularSubFactory` to solve circular dependencies between factories
+ Please read the :ref:`changelog-1-3-0-upgrading` section, then run your
+ tests with ``python -W default`` to see all remaining warnings.
+
+New
+"""
+
+- **Global:**
+ - Rewrite the whole documentation
+ - Provide a dedicated :class:`~factory.MogoFactory` subclass of :class:`~factory.Factory`
+
+- **The Factory class:**
- Better creation/building customization hooks at :meth:`factory.Factory._build` and :meth:`factory.Factory.create`
- - Add support for passing non-kwarg parameters to a :class:`~factory.Factory` wrapped class
- - Enhance :class:`~factory.SelfAttribute` to handle "container" attribute fetching
+ - Add support for passing non-kwarg parameters to a :class:`~factory.Factory`
+ wrapped class through :attr:`~factory.Factory.FACTORY_ARG_PARAMETERS`.
- Keep the :attr:`~factory.Factory.FACTORY_FOR` attribute in :class:`~factory.Factory` classes
- - Provide a dedicated :class:`~factory.MogoFactory` subclass of :class:`~factory.Factory`
-*Pending deprecation:*
+- **Declarations:**
+ - Allow :class:`~factory.SubFactory` to solve circular dependencies between factories
+ - Enhance :class:`~factory.SelfAttribute` to handle "container" attribute fetching
+ - Add a :attr:`~factory.Iterator.getter` to :class:`~factory.Iterator`
+ declarations
+ - A :class:`~factory.Iterator` may be prevented from cycling by setting
+ its :attr:`~factory.Iterator.cycle` argument to ``False``
+
+
+Pending deprecation
+"""""""""""""""""""
The following features have been deprecated and will be removed in an upcoming release.
+- **Declarations:**
+ - :class:`~factory.InfiniteIterator` is deprecated in favor of :class:`~factory.Iterator`
+ - :class:`~factory.CircularSubFactory` is deprecated in favor of :class:`~factory.SubFactory`
+ - The ``extract_prefix`` argument to :meth:`~factory.post_generation` is now deprecated
+
+- **Factory:**
- Usage of :meth:`~factory.Factory.set_creation_function` and :meth:`~factory.Factory.set_building_function`
are now deprecated
- Implicit associated class discovery is no longer supported, you must set the :attr:`~factory.Factory.FACTORY_FOR`
attribute on all :class:`~factory.Factory` subclasses
+
+.. _changelog-1-3-0-upgrading:
+
+Upgrading
+"""""""""
+
+This version deprecates a few magic or undocumented features.
+All warnings will turn into errors starting from v2.0.0.
+
+In order to upgrade client code, apply the following rules:
+
+- Add a ``FACTORY_FOR`` attribute pointing to the target class to each
+ :class:`~factory.Factory`, instead of relying on automagic associated class
+ discovery
+- When using factory_boy for Django models, have each factory inherit from
+ :class:`~factory.DjangoModelFactory`
+- Replace ``factory.CircularSubFactory('some.module', 'Symbol')`` with
+ ``factory.SubFactory('some.module.Symbol')``
+- Replace ``factory.InfiniteIterator(iterable)`` with ``factory.Iterator(iterable)``
+- Replace ``@factory.post_generation()`` with ``@factory.post_generation``
+- Replace ``factory.set_building_function(SomeFactory, building_function)`` with
+ an override of the :meth:`~factory.Factory._build` method of ``SomeFactory``
+- Replace ``factory.set_creation_function(SomeFactory, creation_function)`` with
+ an override of the :meth:`~factory.Factory._create` method of ``SomeFactory``
+
+
+
1.2.0 (09/08/2012)
------------------
diff --git a/docs/reference.rst b/docs/reference.rst
index edbd527..efb70e8 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -720,15 +720,24 @@ Iterator
.. class:: Iterator(iterable, cycle=True, getter=None)
-The :class:`Iterator` declaration takes succesive values from the given
-iterable. When it is exhausted, it starts again from zero (unless ``cycle=False``).
+ The :class:`Iterator` declaration takes succesive values from the given
+ iterable. When it is exhausted, it starts again from zero (unless ``cycle=False``).
-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...).
+ .. attribute:: cycle
-.. versionadded:: 1.3.0
- The ``cycle`` argument is available as of v1.3.0; previous versions
- had a behaviour equivalent to ``cycle=False``.
+ 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``.
+
+ .. attribute:: getter
+
+ A custom function called on each value returned by the iterable.
+ See the :ref:`iterator-getter` section for details.
+
+ .. versionadded:: 1.3.0
Each call to the factory will receive the next value from the iterable:
@@ -756,6 +765,8 @@ When a value is passed in for the argument, the iterator will *not* be advanced:
>>> UserFactory().lang
'fr'
+.. _iterator-getter:
+
Getter
~~~~~~
@@ -764,8 +775,6 @@ 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):