Refs #27753 -- Favored force/smart_str() over force/smart_text().

3 files changed, 25 insertions, 33 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index d86769c4fb..46e99af993 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2079,7 +2079,7 @@ unpredictable value.
 randomly-generated ``SECRET_KEY`` to each new project.
 
 Uses of the key shouldn't assume that it's text or bytes. Every use should go
-through :func:`~django.utils.encoding.force_text` or
+through :func:`~django.utils.encoding.force_str` or
 :func:`~django.utils.encoding.force_bytes` to convert it to the desired type.
 
 Django will refuse to start if :setting:`SECRET_KEY` is not set.
diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
index 9d0311deef..177ada4ef1 100644
--- a/docs/ref/unicode.txt
+++ b/docs/ref/unicode.txt
@@ -108,7 +108,7 @@ Conversion functions
 The ``django.utils.encoding`` module contains a few functions that are handy
 for converting back and forth between strings and bytestrings.
 
-* ``smart_text(s, encoding='utf-8', strings_only=False, errors='strict')``
+* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
   converts its input to a string. The ``encoding`` parameter
   specifies the input encoding. (For example, Django uses this internally
   when processing form input data, which might not be UTF-8 encoded.) The
@@ -118,24 +118,23 @@ for converting back and forth between strings and bytestrings.
   that are accepted by Python's ``str()`` function for its error
   handling.
 
-* ``force_text(s, encoding='utf-8', strings_only=False,
-  errors='strict')`` is identical to ``smart_text()`` in almost all
-  cases. The difference is when the first argument is a :ref:`lazy
-  translation <lazy-translations>` instance. While ``smart_text()``
-  preserves lazy translations, ``force_text()`` forces those objects to a
-  string (causing the translation to occur). Normally, you'll want
-  to use ``smart_text()``. However, ``force_text()`` is useful in
-  template tags and filters that absolutely *must* have a string to work
-  with, not just something that can be converted to a string.
+* ``force_str(s, encoding='utf-8', strings_only=False, errors='strict')`` is
+  identical to ``smart_str()`` in almost all cases. The difference is when the
+  first argument is a :ref:`lazy translation <lazy-translations>` instance.
+  While ``smart_str()`` preserves lazy translations, ``force_str()`` forces
+  those objects to a string (causing the translation to occur). Normally,
+  you'll want to use ``smart_str()``. However, ``force_str()`` is useful in
+  template tags and filters that absolutely *must* have a string to work with,
+  not just something that can be converted to a string.
 
 * ``smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')``
-  is essentially the opposite of ``smart_text()``. It forces the first
+  is essentially the opposite of ``smart_str()``. It forces the first
   argument to a bytestring. The ``strings_only`` parameter has the same
-  behavior as for ``smart_text()`` and ``force_text()``. This is
+  behavior as for ``smart_str()`` and ``force_str()``. This is
   slightly different semantics from Python's builtin ``str()`` function,
   but the difference is needed in a few places within Django's internals.
 
-Normally, you'll only need to use ``force_text()``. Call it as early as
+Normally, you'll only need to use ``force_str()``. Call it as early as
 possible on any input data that might be either a string or a bytestring, and
 from then on, you can treat the result as always being a string.
 
@@ -280,7 +279,7 @@ A couple of tips to remember when writing your own template tags and filters:
 * Always return strings from a template tag's ``render()`` method
   and from template filters.
 
-* Use ``force_text()`` in preference to ``smart_text()`` in these
+* Use ``force_str()`` in preference to ``smart_str()`` in these
   places. Tag rendering and filter calls occur as the template is being
   rendered, so there is no advantage to postponing the conversion of lazy
   translation objects into strings. It's easier to work solely with
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 23a4d6dedd..62625cf62c 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -191,7 +191,7 @@ The functions defined in this module share the following properties:
 .. module:: django.utils.encoding
    :synopsis: A series of helper functions to manage character encoding.
 
-.. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
 
     Returns a ``str`` object representing arbitrary object ``s``. Treats
     bytestrings using the ``encoding`` codec.
@@ -204,11 +204,11 @@ The functions defined in this module share the following properties:
     Determine if the object instance is of a protected type.
 
     Objects of protected types are preserved as-is when passed to
-    ``force_text(strings_only=True)``.
+    ``force_str(strings_only=True)``.
 
-.. function:: force_text(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: force_str(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Similar to ``smart_text``, except that lazy instances are resolved to
+    Similar to ``smart_str()``, except that lazy instances are resolved to
     strings, rather than kept as lazy objects.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
@@ -230,22 +230,15 @@ The functions defined in this module share the following properties:
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
 
-.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
-
-    Alias of :func:`smart_text`. This function returns a ``str`` or a lazy
-    string.
-
-    For instance, this is suitable for writing to :data:`sys.stdout`.
+.. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Alias of :func:`smart_bytes` on Python 2 (in older versions of Django that
-    support it).
+    Alias of :func:`force_str` for backwards compatibility, especially in code
+    that supports Python 2.
 
-.. function:: force_str(s, encoding='utf-8', strings_only=False, errors='strict')
-
-    Alias of :func:`force_text`. This function always returns a ``str``.
+.. function:: force_text(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Alias of :func:`force_bytes` on Python 2 (in older versions of Django that
-    support it).
+    Alias of :func:`force_str` for backwards compatibility, especially in code
+    that supports Python 2.
 
 .. function:: iri_to_uri(iri)
 
@@ -622,7 +615,7 @@ escaping HTML.
     interpolation, some of the formatting options provided by ``str.format()``
     (e.g. number formatting) will not work, since all arguments are passed
     through :func:`conditional_escape` which (ultimately) calls
-    :func:`~django.utils.encoding.force_text` on the values.
+    :func:`~django.utils.encoding.force_str` on the values.
 
 .. function:: format_html_join(sep, format_string, args_generator)