Fixed #20223 -- Added keep_lazy() as a replacement for allow_lazy().

Thanks to bmispelon and uruz for the initial patch.

4 files changed, 52 insertions, 10 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 6a312dc925..5fe2e142fb 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -124,6 +124,8 @@ details on these changes.
 * The ``cascaded_union`` property of ``django.contrib.gis.geos.MultiPolygon``
   will be removed.
 
+* ``django.utils.functional.allow_lazy()`` will be removed.
+
 .. _deprecation-removed-in-1.10:
 
 1.10
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 0a7dfd43de..369ec6eb51 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -522,6 +522,15 @@ Atom1Feed
 
 .. function:: allow_lazy(func, *resultclasses)
 
+    .. deprecated:: 1.10
+
+    Works like :meth:`~django.utils.functional.keep_lazy` except that it can't
+    be used as a decorator.
+
+.. function:: keep_lazy(func, *resultclasses)
+
+    .. versionadded:: 1.10
+
     Django offers many utility functions (particularly in ``django.utils``)
     that take a string as their first argument and do something to that string.
     These functions are used by template filters as well as directly in other
@@ -533,31 +542,58 @@ Atom1Feed
     because you might be using this function outside of a view (and hence the
     current thread's locale setting will not be correct).
 
-    For cases like this, use the ``django.utils.functional.allow_lazy()``
+    For cases like this, use the ``django.utils.functional.keep_lazy()``
     decorator. It modifies the function so that *if* it's called with a lazy
     translation as one of its arguments, the function evaluation is delayed
     until it needs to be converted to a string.
 
     For example::
 
-        from django.utils.functional import allow_lazy
+        from django.utils import six
+        from django.utils.functional import keep_lazy, keep_lazy_text
 
         def fancy_utility_function(s, ...):
             # Do some conversion on string 's'
             ...
-        # Replace unicode by str on Python 3
-        fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
+        fancy_utility_function = keep_lazy(six.text_type)(fancy_utility_function)
 
-    The ``allow_lazy()`` decorator takes, in addition to the function to
-    decorate, a number of extra arguments (``*args``) specifying the type(s)
-    that the original function can return. Usually, it's enough to include
-    ``unicode`` (or ``str`` on Python 3) here and ensure that your function
-    returns only Unicode strings.
+        # Or more succinctly:
+        @keep_lazy(six.text_type)
+        def fancy_utility_function(s, ...):
+            ...
+
+    The ``keep_lazy()`` decorator takes a number of extra arguments (``*args``)
+    specifying the type(s) that the original function can return. A common
+    use case is to have functions that return text. For these, you can just
+    pass the ``six.text_type`` type to ``keep_lazy`` (or even simpler, use the
+    :func:`keep_lazy_text` decorator described in the next section).
 
     Using this decorator means you can write your function and assume that the
     input is a proper string, then add support for lazy translation objects at
     the end.
 
+.. function:: keep_lazy_text(func)
+
+    .. versionadded:: 1.10
+
+    A shortcut for ``keep_lazy(six.text_type)(func)``.
+
+    If you have a function that returns text and you want to be able to take
+    lazy arguments while delaying their evaluation, simply use this decorator::
+
+        from django.utils import six
+        from django.utils.functional import keep_lazy, keep_lazy_text
+
+        # Our previous example was:
+        @keep_lazy(six.text_type)
+        def fancy_utility_function(s, ...):
+            ...
+
+        # Which can be rewritten as:
+        @keep_lazy_text
+        def fancy_utility_function(s, ...):
+            ...
+
 ``django.utils.html``
 =====================
 
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index f8e90bbed7..6f94154929 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -402,6 +402,10 @@ Miscellaneous
 * The ``makemigrations --exit`` option is deprecated in favor of the
   :djadminopt:`--check` option.
 
+* ``django.utils.functional.allow_lazy()`` is deprecated in favor of the new
+  :func:`~django.utils.functional.keep_lazy` function which can be used with a
+  more natural decorator syntax.
+
 .. _removed-features-1.10:
 
 Features removed in 1.10
diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt
index 718fa4762e..6725a624eb 100644
--- a/docs/topics/performance.txt
+++ b/docs/topics/performance.txt
@@ -223,7 +223,7 @@ QuerySet <when-querysets-are-evaluated>`. Avoiding the premature evaluation of
 a ``QuerySet`` can save making an expensive and unnecessary trip to the
 database.
 
-Django also offers an :meth:`~django.utils.functional.allow_lazy` decorator.
+Django also offers a :meth:`~django.utils.functional.keep_lazy` decorator.
 This allows a function that has been called with a lazy argument to behave
 lazily itself, only being evaluated when it needs to be. Thus the lazy argument
 - which could be an expensive one - will not be called upon for evaluation