Fixed #24046 -- Deprecated the "escape" half of utils.safestring.

6 files changed, 28 insertions, 10 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 97179de7b0..69e223c01c 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -210,15 +210,6 @@ passed around inside the template code:
           # Do something with the "safe" string.
           ...
 
-* **Strings marked as "needing escaping"** are *always* escaped on
-  output, regardless of whether they are in an :ttag:`autoescape` block or
-  not. These strings are only escaped once, however, even if auto-escaping
-  applies.
-
-  Internally, these strings are of type ``EscapeBytes`` or
-  ``EscapeText``. Generally you don't have to worry about these; they
-  exist for the implementation of the :tfilter:`escape` filter.
-
 Template filter code falls into one of two situations:
 
 1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``,
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index b3d03dd37a..218e79d66f 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -168,6 +168,13 @@ details on these changes.
 * ``FileField`` methods ``get_directory_name()`` and ``get_filename()`` will be
   removed.
 
+* The ``mark_for_escaping()`` function and the classes it uses: ``EscapeData``,
+  ``EscapeBytes``, ``EscapeText``, ``EscapeString``, and ``EscapeUnicode`` will
+  be removed.
+
+* The ``escape`` filter will change to use
+  ``django.utils.html.conditional_escape()``.
+
 .. _deprecation-removed-in-1.10:
 
 1.10
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 0959679ed7..f44dbb0a6f 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1578,6 +1578,12 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off::
         {{ title|escape }}
     {% endautoescape %}
 
+.. deprecated:: 1.10
+
+    The "lazy" behavior of the ``escape`` filter is deprecated. It will change
+    to immediately apply :func:`~django.utils.html.conditional_escape` in
+    Django 2.0.
+
 .. templatefilter:: escapejs
 
 ``escapejs``
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 8328d91fc5..eadd036cb6 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -839,6 +839,8 @@ appropriate entities.
 
 .. function:: mark_for_escaping(s)
 
+    .. deprecated:: 1.10
+
     Explicitly mark a string as requiring HTML escaping upon output. Has no
     effect on ``SafeData`` subclasses.
 
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index a0b0a873cc..410180f838 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -1012,6 +1012,18 @@ This method must accept a :class:`~django.db.models.query.QuerySet` instance
 as its single argument and return a filtered version of the queryset for the
 model instance the manager is bound to.
 
+The "escape" half of ``django.utils.safestring``
+------------------------------------------------
+
+The ``mark_for_escaping()`` function and the classes it uses: ``EscapeData``,
+``EscapeBytes``, ``EscapeText``, ``EscapeString``, and ``EscapeUnicode`` are
+deprecated.
+
+As a result, the "lazy" behavior of the ``escape`` filter (where it would
+always be applied as the last filter no matter where in the filter chain it
+appeared) is deprecated. The filter will change to immediately apply
+:func:`~django.utils.html.conditional_escape` in Django 2.0.
+
 Miscellaneous
 -------------
 
diff --git a/docs/releases/1.7.2.txt b/docs/releases/1.7.2.txt
index 040c983fcb..056f432978 100644
--- a/docs/releases/1.7.2.txt
+++ b/docs/releases/1.7.2.txt
@@ -177,7 +177,7 @@ Bugfixes
   setup (:ticket:`24000`).
 
 * Restored support for objects that aren't :class:`str` or :class:`bytes` in
-  :func:`~django.utils.safestring.mark_for_escaping` on Python 3.
+  ``django.utils.safestring.mark_for_escaping()`` on Python 3.
 
 * Supported strings escaped by third-party libraries with the ``__html__``
   convention in the template engine (:ticket:`23831`).