Fixed #25462 -- Removed Model.__unicode__() in favor of @python_2_unicode_compatible.

3 files changed, 16 insertions, 83 deletions

diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt
index de1f43708f..a92b757279 100644
--- a/docs/intro/tutorial02.txt
+++ b/docs/intro/tutorial02.txt
@@ -445,15 +445,18 @@ of this object. Let's fix that by editing the ``Question`` model (in the
     :filename: polls/models.py
 
     from django.db import models
+    from django.utils.encoding import python_2_unicode_compatible
 
+    @python_2_unicode_compatible  # only if you need to support Python 2
     class Question(models.Model):
         # ...
-        def __str__(self):              # __unicode__ on Python 2
+        def __str__(self):
             return self.question_text
 
+    @python_2_unicode_compatible  # only if you need to support Python 2
     class Choice(models.Model):
         # ...
-        def __str__(self):              # __unicode__ on Python 2
+        def __str__(self):
             return self.choice_text
 
 It's important to add :meth:`~django.db.models.Model.__str__` methods to your
@@ -461,23 +464,6 @@ models, not only for your own convenience when dealing with the interactive
 prompt, but also because objects' representations are used throughout Django's
 automatically-generated admin.
 
-.. admonition:: ``__str__`` or ``__unicode__``?
-
-    On Python 3, it's easy, just use
-    :meth:`~django.db.models.Model.__str__`.
-
-    On Python 2, you should define :meth:`~django.db.models.Model.__unicode__`
-    methods returning ``unicode`` values instead. Django models have a default
-    :meth:`~django.db.models.Model.__str__` method that calls
-    :meth:`~django.db.models.Model.__unicode__` and converts the result to a
-    UTF-8 bytestring. This means that ``unicode(p)`` will return a Unicode
-    string, and ``str(p)`` will return a bytestring, with characters encoded
-    as UTF-8. Python does the opposite: ``object`` has a ``__unicode__``
-    method that calls ``__str__`` and interprets the result as an ASCII
-    bytestring. This difference can create confusion.
-
-    If all of this is gibberish to you, just use Python 3.
-
 Note these are normal Python methods. Let's add a custom method, just for
 demonstration:
 
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 86438b64bc..16786c09d0 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -588,58 +588,23 @@ Other model instance methods
 
 A few object methods have special purposes.
 
-.. note::
-    On Python 3, as all strings are natively considered Unicode, only use the
-    ``__str__()`` method (the ``__unicode__()`` method is obsolete).
-    If you'd like compatibility with Python 2, you can decorate your model class
-    with :func:`~django.utils.encoding.python_2_unicode_compatible`.
-
-``__unicode__``
----------------
-
-.. method:: Model.__unicode__()
-
-The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
-object. Django uses ``unicode(obj)`` (or the related function, :meth:`str(obj)
-<Model.__str__>`) in a number of places. Most notably, to display an object in
-the Django admin site and as the value inserted into a template when it
-displays an object. Thus, you should always return a nice, human-readable
-representation of the model from the ``__unicode__()`` method.
-
-For example::
-
-    from django.db import models
-
-    class Person(models.Model):
-        first_name = models.CharField(max_length=50)
-        last_name = models.CharField(max_length=50)
-
-        def __unicode__(self):
-            return u'%s %s' % (self.first_name, self.last_name)
-
-If you define a ``__unicode__()`` method on your model and not a
-:meth:`~Model.__str__()` method, Django will automatically provide you with a
-:meth:`~Model.__str__()` that calls ``__unicode__()`` and then converts the
-result correctly to a UTF-8 encoded string object. This is recommended
-development practice: define only ``__unicode__()`` and let Django take care of
-the conversion to string objects when required.
-
 ``__str__``
 -----------
 
 .. method:: Model.__str__()
 
-The ``__str__()`` method is called whenever you call ``str()`` on an
-object. In Python 3, Django uses ``str(obj)`` in a number of
-places. Most notably, to display an object in the Django admin site
-and as the value inserted into a template when it displays an
-object. Thus, you should always return a nice, human-readable
+The ``__str__()`` method is called whenever you call ``str()`` on an object.
+Django uses ``str(obj)`` in a number of places. Most notably, to display an
+object in the Django admin site and as the value inserted into a template when
+it displays an object. Thus, you should always return a nice, human-readable
 representation of the model from the ``__str__()`` method.
 
 For example::
 
     from django.db import models
+    from django.utils.encoding import python_2_unicode_compatible
 
+    @python_2_unicode_compatible  # only if you need to support Python 2
     class Person(models.Model):
         first_name = models.CharField(max_length=50)
         last_name = models.CharField(max_length=50)
@@ -647,26 +612,8 @@ For example::
         def __str__(self):
             return '%s %s' % (self.first_name, self.last_name)
 
-In Python 2, the main use of ``__str__`` directly inside Django is
-when the ``repr()`` output of a model is displayed anywhere (for
-example, in debugging output). It isn't required to put ``__str__()``
-methods everywhere if you have sensible :meth:`~Model.__unicode__()`
-methods.
-
-The previous :meth:`~Model.__unicode__()` example could be similarly written
-using ``__str__()`` like this::
-
-    from django.db import models
-    from django.utils.encoding import force_bytes
-
-    class Person(models.Model):
-        first_name = models.CharField(max_length=50)
-        last_name = models.CharField(max_length=50)
-
-        def __str__(self):
-            # Note use of django.utils.encoding.force_bytes() here because
-            # first_name and last_name will be unicode strings.
-            return force_bytes('%s %s' % (self.first_name, self.last_name))
+If you'd like compatibility with Python 2, you can decorate your model class
+with :func:`~django.utils.encoding.python_2_unicode_compatible` as show above.
 
 ``__eq__``
 ----------
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index ed13e46374..53d2396f03 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -756,9 +756,6 @@ You can override most of these -- see `overriding predefined model methods`_,
 below -- but there are a couple that you'll almost always want to define:
 
 :meth:`~Model.__str__` (Python 3)
-    Python 3 equivalent of ``__unicode__()``.
-
-:meth:`~Model.__unicode__` (Python 2)
     A Python "magic method" that returns a unicode "representation" of any
     object. This is what Python and Django will use whenever a model
     instance needs to be coerced and displayed as a plain string. Most
@@ -768,6 +765,9 @@ below -- but there are a couple that you'll almost always want to define:
     You'll always want to define this method; the default isn't very helpful
     at all.
 
+``__unicode__()`` (Python 2)
+    Python 2 equivalent of ``__str__()``.
+
 :meth:`~Model.get_absolute_url`
     This tells Django how to calculate the URL for an object. Django uses
     this in its admin interface, and any time it needs to figure out a URL