Fixed #21951 -- Updated docs to use __str__ for Python 3

Thanks Tim Graham for the report and recommendations

docs/ref/contrib/admin/actions.txt

@@ -57,8 +57,7 @@ simple news application with an ``Article`` model::
         body = models.TextField()
         status = models.CharField(max_length=1, choices=STATUS_CHOICES)
 
-        # On Python 3: def __str__(self):
-        def __unicode__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return self.title
 
 A common task we might perform with a model like this is to update an

docs/ref/contrib/admin/index.txt

@@ -512,7 +512,7 @@ subclass::
         list_display = ('first_name', 'last_name')
 
     If you don't set ``list_display``, the admin site will display a single
-    column that displays the ``__unicode__()`` (``__str__()`` on Python 3)
+    column that displays the ``__str__()`` (``__unicode__()`` on Python 2)
     representation of each object.
 
     You have four possible values that can be used in ``list_display``:
@@ -563,7 +563,7 @@ subclass::
     A few special cases to note about ``list_display``:
 
     * If the field is a ``ForeignKey``, Django will display the
-      ``__unicode__()`` (``__str__()`` on Python 3) of the related object.
+      ``__str__()`` (``__unicode__()`` on Python 2) of the related object.
 
     * ``ManyToManyField`` fields aren't supported, because that would
       entail executing a separate SQL statement for each row in the table.
@@ -626,11 +626,11 @@ subclass::
               list_display = ('name', 'born_in_fifties')
 
 
-    * The ``__str__()`` and ``__unicode__()`` methods are just as valid in
-      ``list_display`` as any other model method, so it's perfectly OK to
-      do this::
+    * The ``__str__()`` (``__unicode__()`` on Python 2) method is just
+      as valid in ``list_display`` as any other model method, so it's
+      perfectly OK to do this::
 
-          list_display = ('__unicode__', 'some_other_field')
+          list_display = ('__str__', 'some_other_field')
 
     * Usually, elements of ``list_display`` that aren't actual database
       fields can't be used in sorting (because Django does all the sorting

docs/ref/contrib/contenttypes.txt

@@ -259,8 +259,7 @@ A simple example is a tagging system, which might look like this::
         object_id = models.PositiveIntegerField()
         content_object = GenericForeignKey('content_type', 'object_id')
 
-        # On Python 3: def __str__(self):
-        def __unicode__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return self.tag
 
 A normal :class:`~django.db.models.ForeignKey` can only "point

docs/ref/contrib/gis/commands.txt

@@ -65,7 +65,7 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
 
 .. django-admin-option:: --name-field <name_field>
 
-   Generates a ``__unicode__`` routine (``__str__`` on Python 3) on the model
+   Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model
    that will return the given field name.
 
 .. django-admin-option:: --no-imports

docs/ref/contrib/gis/layermapping.txt

@@ -61,8 +61,7 @@ Example
         poly = models.PolygonField(srid=4269) # we want our model in a different SRID
         objects = models.GeoManager()
 
-        # On Python 3: def __str__(self):
-        def __unicode__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return 'Name: %s' % self.name
 
 3. Use :class:`LayerMapping` to extract all the features and place them in the

docs/ref/contrib/gis/tutorial.txt

@@ -244,8 +244,7 @@ model to represent this data::
         objects = models.GeoManager()
 
         # Returns the string representation of the model.
-        # On Python 3: def __str__(self):
-        def __unicode__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return self.name
 
 Please note two important things:

docs/ref/forms/api.txt

@@ -653,16 +653,16 @@ Customizing the error list format
 
 By default, forms use ``django.forms.utils.ErrorList`` to format validation
 errors. If you'd like to use an alternate class for displaying errors, you can
-pass that in at construction time (replace ``__unicode__`` by ``__str__`` on
-Python 3)::
+pass that in at construction time (replace ``__str__`` by ``__unicode__`` on
+Python 2)::
 
     >>> from django.forms.utils import ErrorList
     >>> class DivErrorList(ErrorList):
-    ...     def __unicode__(self):
+    ...     def __str__(self):              # __unicode__ on Python 2
     ...         return self.as_divs()
     ...     def as_divs(self):
-    ...         if not self: return u''
-    ...         return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
+    ...         if not self: return ''
+    ...         return '<div class="errorlist">%s</div>' % ''.join(['<div class="error">%s</div>' % e for e in self])
     >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
     >>> f.as_p()
     <div class="errorlist"><div class="error">This field is required.</div></div>
@@ -687,8 +687,8 @@ lazy developers -- they're not the only way a form object can be displayed.
    Used to display HTML or access attributes for a single field of a
    :class:`Form` instance.
 
-   The ``__unicode__()`` and ``__str__()`` methods of this object displays
-   the HTML for this field.
+   The ``__str__()`` (``__unicode__`` on Python 2) method of this
+   object displays the HTML for this field.
 
 To retrieve a single ``BoundField``, use dictionary lookup syntax on your form
 using the field's name as the key::

docs/ref/forms/fields.txt

@@ -1047,7 +1047,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
         initial value, no empty choice is created (regardless of the value
         of ``empty_label``).
 
-    The ``__unicode__`` (``__str__`` on Python 3) method of the model will be
+    The ``__str__`` (``__unicode__`` on Python 2) method of the model will be
     called to generate string representations of the objects for use in the
     field's choices; to provide customized representations, subclass
     ``ModelChoiceField`` and override ``label_from_instance``. This method will

docs/ref/models/instances.txt

@@ -463,9 +463,29 @@ the conversion to string objects when required.
 
 .. method:: Model.__str__()
 
-The ``__str__()`` method is called whenever you call ``str()`` on an object. The main use for this method directly inside Django is when the ``repr()`` output of a model is displayed anywhere (for example, in debugging output).
-Thus, you should return a nice, human-readable string for the object's
-``__str__()``.  It isn't required to put ``__str__()`` methods everywhere if you have sensible :meth:`~Model.__unicode__()` methods.
+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
+representation of the model from the ``__str__()`` 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 __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::

docs/ref/models/querysets.txt

@@ -812,17 +812,16 @@ For example, suppose you have these models::
         name = models.CharField(max_length=50)
         toppings = models.ManyToManyField(Topping)
 
-        # On Python 3: def __str__(self):
-        def __unicode__(self):
-            return u"%s (%s)" % (self.name, u", ".join([topping.name
-                                                        for topping in self.toppings.all()]))
+        def __str__(self):              # __unicode__ on Python 2
+            return "%s (%s)" % (self.name, ", ".join([topping.name
+                                                      for topping in self.toppings.all()]))
 
 and run::
 
     >>> Pizza.objects.all()
-    [u"Hawaiian (ham, pineapple)", u"Seafood (prawns, smoked salmon)"...
+    ["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...
 
-The problem with this is that every time ``Pizza.__unicode__()`` asks for
+The problem with this is that every time ``Pizza.__str__()`` asks for
 ``self.toppings.all()`` it has to query the database, so
 ``Pizza.objects.all()`` will run a query on the Toppings table for **every**
 item in the Pizza ``QuerySet``.