[py3] Ported django.utils.encoding.

* Renamed smart_unicode to smart_text (but kept the old name under
  Python 2 for backwards compatibility).
* Renamed smart_str to smart_bytes.
* Re-introduced smart_str as an alias for smart_text under Python 3
  and smart_bytes under Python 2 (which is backwards compatible).
  Thus smart_str always returns a str objects.
* Used the new smart_str in a few places where both Python 2 and 3
  want a str.

9 files changed, 60 insertions, 32 deletions

diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 706cc25129..e73ef9aa42 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -688,7 +688,7 @@ smoothly:
 2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
    wrapping up as a field. There are a lot of places where the default
    behavior of the field code is to call
-   :func:`~django.utils.encoding.force_unicode` on the value. (In our
+   :func:`~django.utils.encoding.force_text` on the value. (In our
    examples in this document, ``value`` would be a ``Hand`` instance, not a
    ``HandField``). So if your :meth:`__unicode__` method automatically
    converts to the string form of your Python object, you can save yourself
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 74e6b48f07..92b5665bea 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -238,7 +238,7 @@ to you, the developer, to handle the fact that you will receive bytestrings if
 you configure your table(s) to use ``utf8_bin`` collation. Django itself should
 mostly work smoothly with such columns (except for the ``contrib.sessions``
 ``Session`` and ``contrib.admin`` ``LogEntry`` tables described below), but
-your code must be prepared to call ``django.utils.encoding.smart_unicode()`` at
+your code must be prepared to call ``django.utils.encoding.smart_text()`` at
 times if it really wants to work with consistent data -- Django will not do
 this for you (the database backend layer and the model population layer are
 separated internally so the database layer doesn't know it needs to make this
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 509ea9d30e..14541ad0d1 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -453,9 +453,9 @@ using ``__str__()`` like this::
         last_name = models.CharField(max_length=50)
 
         def __str__(self):
-            # Note use of django.utils.encoding.smart_str() here because
+            # Note use of django.utils.encoding.smart_bytes() here because
             # first_name and last_name will be unicode strings.
-            return smart_str('%s %s' % (self.first_name, self.last_name))
+            return smart_bytes('%s %s' % (self.first_name, self.last_name))
 
 ``get_absolute_url``
 --------------------
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 72d60453c3..531ff33da2 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -183,7 +183,7 @@ compose a prefix, version and key into a final cache key. The default
 implementation is equivalent to the function::
 
     def make_key(key, key_prefix, version):
-        return ':'.join([key_prefix, str(version), smart_str(key)])
+        return ':'.join([key_prefix, str(version), smart_bytes(key)])
 
 You may use any key function you want, as long as it has the same
 argument signature.
diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
index b9253e70b3..ffab647379 100644
--- a/docs/ref/unicode.txt
+++ b/docs/ref/unicode.txt
@@ -129,7 +129,7 @@ Conversion functions
 The ``django.utils.encoding`` module contains a few functions that are handy
 for converting back and forth between Unicode and bytestrings.
 
-* ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
+* ``smart_text(s, encoding='utf-8', strings_only=False, errors='strict')``
   converts its input to a Unicode 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
@@ -139,27 +139,27 @@ for converting back and forth between Unicode and bytestrings.
   that are accepted by Python's ``unicode()`` function for its error
   handling.
 
-  If you pass ``smart_unicode()`` an object that has a ``__unicode__``
+  If you pass ``smart_text()`` an object that has a ``__unicode__``
   method, it will use that method to do the conversion.
 
-* ``force_unicode(s, encoding='utf-8', strings_only=False,
-  errors='strict')`` is identical to ``smart_unicode()`` in almost all
+* ``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_unicode()``
-  preserves lazy translations, ``force_unicode()`` forces those objects to a
+  translation <lazy-translations>` instance. While ``smart_text()``
+  preserves lazy translations, ``force_text()`` forces those objects to a
   Unicode string (causing the translation to occur). Normally, you'll want
-  to use ``smart_unicode()``. However, ``force_unicode()`` is useful in
+  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.
 
-* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
-  is essentially the opposite of ``smart_unicode()``. It forces the first
+* ``smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')``
+  is essentially the opposite of ``smart_text()``. It forces the first
   argument to a bytestring. The ``strings_only`` parameter has the same
-  behavior as for ``smart_unicode()`` and ``force_unicode()``. This is
+  behavior as for ``smart_text()`` and ``force_text()``. 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 ``smart_unicode()``. Call it as early as
+Normally, you'll only need to use ``smart_text()``. Call it as early as
 possible on any input data that might be either Unicode or a bytestring, and
 from then on, you can treat the result as always being Unicode.
 
@@ -324,7 +324,7 @@ A couple of tips to remember when writing your own template tags and filters:
 * Always return Unicode strings from a template tag's ``render()`` method
   and from template filters.
 
-* Use ``force_unicode()`` in preference to ``smart_unicode()`` in these
+* Use ``force_text()`` in preference to ``smart_text()`` 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 Unicode
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 5157c399da..b6cb1035d3 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -178,33 +178,53 @@ The functions defined in this module share the following properties:
 
 .. class:: StrAndUnicode
 
-    A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8
-    bytestring. Useful as a mix-in.
+    A class that derives ``__str__`` from ``__unicode__``.
 
-.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+    On Python 2, ``__str__`` returns the output of ``__unicode__`` encoded as
+    a UTF-8 bytestring. On Python 3, ``__str__`` returns the output of
+    ``__unicode__``.
+
+    Useful as a mix-in. If you support Python 2 and 3 with a single code base,
+    you can inherit this mix-in and just define ``__unicode__``.
+
+.. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Returns a ``unicode`` object representing ``s``. Treats bytestrings using
-    the 'encoding' codec.
+    .. versionadded:: 1.5
+
+    Returns a text object representing ``s`` -- ``unicode`` on Python 2 and
+    ``str`` on Python 3. Treats bytestrings using the ``encoding`` codec.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
 
+.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    Historical name of :func:`smart_text`. Only available under Python 2.
+
 .. function:: is_protected_type(obj)
 
     Determine if the object instance is of a protected type.
 
     Objects of protected types are preserved as-is when passed to
-    ``force_unicode(strings_only=True)``.
+    ``force_text(strings_only=True)``.
 
-.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: force_text(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    .. versionadded:: 1.5
 
-    Similar to ``smart_unicode``, except that lazy instances are resolved to
+    Similar to ``smart_text``, 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
     objects.
 
-.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    Historical name of :func:`force_text`. Only available under Python 2.
+
+.. function:: smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    .. versionadded:: 1.5
 
     Returns a bytestring version of ``s``, encoded as specified in
     ``encoding``.
@@ -212,6 +232,14 @@ 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_bytes` on Python 2 and :func:`smart_text` on Python
+    3. This function always returns a :class:`str`.
+
+    For instance, this is  suitable for writing to :attr:`sys.stdout` on
+    Python 2 and 3.
+
 .. function:: iri_to_uri(iri)
 
     Convert an Internationalized Resource Identifier (IRI) portion to a URI
@@ -406,7 +434,7 @@ escaping HTML.
 
     Returns the given text with ampersands, quotes and angle brackets encoded
     for use in HTML. The input is first passed through
-    :func:`~django.utils.encoding.force_unicode` and the output has
+    :func:`~django.utils.encoding.force_text` and the output has
     :func:`~django.utils.safestring.mark_safe` applied.
 
 .. function:: conditional_escape(text)
@@ -448,7 +476,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_unicode` on the values.
+    :func:`~django.utils.encoding.force_text` on the values.
 
 
 .. _str.format: http://docs.python.org/library/stdtypes.html#str.format
diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt
index d58d3cadf4..f789ebde40 100644
--- a/docs/releases/1.5.txt
+++ b/docs/releases/1.5.txt
@@ -161,7 +161,7 @@ If you have written a :ref:`custom password hasher <auth_password_storage>`,
 your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept
 Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the
 hashing methods need byte strings, you can use the
-:func:`~django.utils.encoding.smart_str` utility to encode the strings.
+:func:`~django.utils.encoding.smart_bytes` utility to encode the strings.
 
 Validation of previous_page_number and next_page_number
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index d0bd9f6992..219b6c7795 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -864,7 +864,7 @@ key version to provide a final cache key. By default, the three parts
 are joined using colons to produce a final string::
 
     def make_key(key, key_prefix, version):
-        return ':'.join([key_prefix, str(version), smart_str(key)])
+        return ':'.join([key_prefix, str(version), smart_bytes(key)])
 
 If you want to combine the parts in different ways, or apply other
 processing to the final key (e.g., taking a hash digest of the key
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index 505ac17f09..ac1a77ed98 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -173,12 +173,12 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
 
     import json
     from django.utils.functional import Promise
-    from django.utils.encoding import force_unicode
+    from django.utils.encoding import force_text
 
     class LazyEncoder(json.JSONEncoder):
         def default(self, obj):
             if isinstance(obj, Promise):
-                return force_unicode(obj)
+                return force_text(obj)
             return super(LazyEncoder, self).default(obj)
 
 .. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders