From f2c075c40fd331b7d26a9db72aad249b2165eac4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Herv=C3=A9=20Cauwelier?= <herve.cauwelier@polyconseil.fr>
Date: Fri, 12 Feb 2016 17:31:04 +0100
Subject: factory: LazyFunction to just call a function in the simplest case

No need to wrap it in a lambda to strip the object argument from LazyAttribute or the sequence argument from Sequence.
---
 docs/examples.rst     |  2 ++
 docs/introduction.rst | 29 +++++++++++++++++++++++++++++
 docs/reference.rst    | 40 ++++++++++++++++++++++++++++++++++++++--
 3 files changed, 69 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/examples.rst b/docs/examples.rst
index e7f6057..6f26b7e 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -49,6 +49,7 @@ And now, we'll define the related factories:
 
 .. code-block:: python
 
+    import datetime
     import factory
     import random
 
@@ -61,6 +62,7 @@ And now, we'll define the related factories:
 
         username = factory.Sequence(lambda n: 'john%s' % n)
         email = factory.LazyAttribute(lambda o: '%s@example.org' % o.username)
+        date_joined = factory.LazyFunction(datetime.datetime.now)
 
 
     class ProfileFactory(factory.Factory):
diff --git a/docs/introduction.rst b/docs/introduction.rst
index d00154d..9a16c39 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -117,6 +117,35 @@ This is achieved with the :class:`~factory.Sequence` declaration:
                     return 'user%d' % n
 
 
+LazyFunction
+------------
+
+In simple cases, calling a function is enough to compute the value. If that function doesn't depend on the object
+being built, use :class:`~factory.LazyFunction` to call that function; it should receive a function taking no
+argument and returning the value for the field:
+
+.. code-block:: python
+
+    class LogFactory(factory.Factory):
+        class Meta:
+            model = models.Log
+
+        timestamp = factory.LazyFunction(datetime.now)
+
+.. code-block:: pycon
+
+    >>> LogFactory()
+    <Log: log at 2016-02-12 17:02:34>
+
+    >>> # The LazyFunction can be overriden
+    >>> LogFactory(timestamp=now - timedelta(days=1))
+    <Log: log at 2016-02-11 17:02:34>
+
+
+.. note:: For complex cases when you happen to write a specific function,
+          the :meth:`~factory.@lazy_attribute` decorator should be more appropriate.
+
+
 LazyAttribute
 -------------
 
diff --git a/docs/reference.rst b/docs/reference.rst
index b5ccd16..9e01213 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -90,7 +90,7 @@ The :class:`Factory` class
                     model = Order
                     exclude = ('now',)
 
-                now = factory.LazyAttribute(lambda o: datetime.datetime.utcnow())
+                now = factory.LazyFunction(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))
 
@@ -551,6 +551,42 @@ Faker
                 smiley = factory.Faker('smiley')
 
 
+LazyFunction
+""""""""""""
+
+.. class:: LazyFunction(method_to_call)
+
+The :class:`LazyFunction` is the simplest case where the value of an attribute
+does not depend on the object being built.
+
+It takes as argument a method to call (function, lambda...); that method should
+not take any argument, though keyword arguments are safe but unused,
+and return a value.
+
+.. code-block:: python
+
+    class LogFactory(factory.Factory):
+        class Meta:
+            model = models.Log
+
+        timestamp = factory.LazyFunction(datetime.now)
+
+.. code-block:: pycon
+
+    >>> LogFactory()
+    <Log: log at 2016-02-12 17:02:34>
+
+    >>> # The LazyFunction can be overriden
+    >>> LogFactory(timestamp=now - timedelta(days=1))
+    <Log: log at 2016-02-11 17:02:34>
+
+Decorator
+~~~~~~~~~
+
+The class :class:`LazyFunction` does not provide a decorator.
+
+For complex cases, use :meth:`LazyAttribute.lazy_attribute` directly.
+
 LazyAttribute
 """""""""""""
 
@@ -1041,7 +1077,7 @@ gains an "upward" semantic through the double-dot notation, as used in Python im
     >>> company.owner.language
     'fr'
 
-Obviously, this "follow parents" hability also handles overriding some attributes on call:
+Obviously, this "follow parents" ability also handles overriding some attributes on call:
 
 .. code-block:: pycon
 
-- 
cgit v1.2.3