Add Factory.FACTORY_HIDDEN_ARGS.

Fields listed in this class attributes will be removed from the
kwargs dict passed to the associated class for building/creation.

3 files changed, 35 insertions, 4 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index b9ea79f..9a4a64e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -10,8 +10,11 @@ ChangeLog
 
     - Allow overriding the base factory class for :func:`~factory.make_factory` and friends.
     - Add support for Python3 (Thanks to `kmike <https://github.com/kmike>`_ and `nkryptic <https://github.com/nkryptic>`_)
-    - Add support for ``get_or_create`` in :class:`~factory.DjangoModelFactory`
     - The default :attr:`~factory.Sequence.type` for :class:`~factory.Sequence` is now :obj:`int`
+    - Fields listed in :attr:`~factory.Factory.FACTORY_HIDDEN_ARGS` won't be passed to
+      the associated class' constructor
+
+    - Add support for ``get_or_create`` in :class:`~factory.DjangoModelFactory`
 
 *Removed:*
 
diff --git a/docs/ideas.rst b/docs/ideas.rst
index 004f722..914e640 100644
--- a/docs/ideas.rst
+++ b/docs/ideas.rst
@@ -5,7 +5,4 @@ Ideas
 This is a list of future features that may be incorporated into factory_boy:
 
 * **A 'options' attribute**: instead of adding more class-level constants, use a django-style ``class Meta`` Factory attribute with all options there
-* **factory-local fields**: Allow some fields to be available while building attributes,
-  but not passed to the associated class.
-  For instance, a ``global_kind`` field would be used to select values for many other fields.
 
diff --git a/docs/reference.rst b/docs/reference.rst
index d5b14a9..a2af327 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -50,6 +50,37 @@ The :class:`Factory` class
             <User: john>
             >>> User('john', 'john@example.com', firstname="John")  # actual call
 
+    .. attribute:: FACTORY_HIDDEN_ARGS
+
+        While writing a :class:`Factory` for some object, it may be useful to
+        have general fields helping defining others, but that should not be
+        passed to the target class; for instance, a field named 'now' that would
+        hold a reference time used by other objects.
+
+        Factory fields whose name are listed in :attr:`FACTORY_HIDDEN_ARGS` will
+        be removed from the set of args/kwargs passed to the underlying class;
+        they can be any valid factory_boy declaration:
+
+        .. code-block:: python
+
+            class OrderFactory(factory.Factory):
+                FACTORY_FOR = Order
+                FACTORY_HIDDEN_ARGS = ('now',)
+
+                now = factory.LazyAttribute(lambda o: datetime.datetime.utcnow())
+                started_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(hours=1))
+                paid_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(minutes=50))
+
+        .. code-block:: pycon
+
+            >>> OrderFactory()    # The value of 'now' isn't passed to Order()
+            <Order: started 2013-04-01 12:00:00, paid 2013-04-01 12:10:00>
+
+            >>> # An alternate value may be passed for 'now'
+            >>> OrderFactory(now=datetime.datetime(2013, 4, 1, 10))
+            <Order: started 2013-04-01 09:00:00, paid 2013-04-01 09:10:00>
+
+
     **Base functions:**
 
     The :class:`Factory` class provides a few methods for getting objects;