Fixed #20224 -- Update docs examples which mention __unicode__

Thanks Marc Tamlyn and Tim Graham for the review.

11 files changed, 29 insertions, 13 deletions

diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt
index c79f978850..65d096921f 100644
--- a/docs/ref/contrib/admin/actions.txt
+++ b/docs/ref/contrib/admin/actions.txt
@@ -57,6 +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):
             return self.title
 
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 318ce297a2..70db52941c 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -438,7 +438,8 @@ 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__()`` representation of each object.
+    column that displays the ``__unicode__()`` (``__str__()`` on Python 3)
+    representation of each object.
 
     You have four possible values that can be used in ``list_display``:
 
@@ -488,7 +489,7 @@ subclass::
     A few special cases to note about ``list_display``:
 
     * If the field is a ``ForeignKey``, Django will display the
-      ``__unicode__()`` of the related object.
+      ``__unicode__()`` (``__str__()`` on Python 3) of the related object.
 
     * ``ManyToManyField`` fields aren't supported, because that would
       entail executing a separate SQL statement for each row in the table.
diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt
index 199401c64a..fcd66a5b03 100644
--- a/docs/ref/contrib/contenttypes.txt
+++ b/docs/ref/contrib/contenttypes.txt
@@ -270,6 +270,7 @@ A simple example is a tagging system, which might look like this::
         object_id = models.PositiveIntegerField()
         content_object = generic.GenericForeignKey('content_type', 'object_id')
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.tag
 
diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt
index 015a1f9741..3bacb03bc1 100644
--- a/docs/ref/contrib/gis/commands.txt
+++ b/docs/ref/contrib/gis/commands.txt
@@ -65,8 +65,8 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
 
 .. django-admin-option:: --name-field <name_field>
 
-   Generates a ``__unicode__`` routine on the model that will return the
-   the given field name.
+   Generates a ``__unicode__`` routine (``__str__`` on Python 3) on the model
+   that will return the the given field name.
 
 .. django-admin-option:: --no-imports
 
diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt
index dd0a41cbc0..381c7df133 100644
--- a/docs/ref/contrib/gis/layermapping.txt
+++ b/docs/ref/contrib/gis/layermapping.txt
@@ -60,6 +60,8 @@ Example
         name = models.CharField(max_length=25) # corresponds to the 'str' field
         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):
             return 'Name: %s' % self.name
 
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 56d90c8593..3df4db12a0 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -244,6 +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):
             return self.name
 
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index aa19719a68..5d54e01c3d 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -566,7 +566,8 @@ Customizing the error list format
 
 By default, forms use ``django.forms.util.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::
+pass that in at construction time (replace ``__unicode__`` by ``__str__`` on
+Python 3)::
 
     >>> from django.forms.util import ErrorList
     >>> class DivErrorList(ErrorList):
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 69e3aa71ad..ef4ed729bd 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1000,12 +1000,12 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
         initial value, no empty choice is created (regardless of the value
         of ``empty_label``).
 
-    The ``__unicode__`` 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 receive a model
-    object, and should return a string suitable for representing it. For
-    example::
+    The ``__unicode__`` (``__str__`` on Python 3) 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
+    receive a model object, and should return a string suitable for representing
+    it. For example::
 
         from django.forms import ModelChoiceField
 
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 17c9aa9fb7..f06866d9a1 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -430,6 +430,12 @@ 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__``
 ---------------
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 6e5e5c93ad..d3fe142d36 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -814,6 +814,7 @@ 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()]))
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index d7be7a4735..38c2bb322b 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -446,12 +446,14 @@ Atom1Feed
         def fancy_utility_function(s, ...):
             # Do some conversion on string 's'
             ...
+        # Replace unicode by str on Python 3
         fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
 
     The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
     a number of extra arguments (``*args``) specifying the type(s) that the
-    original function can return. Usually, it's enough to include ``unicode`` here
-    and ensure that your function returns only Unicode strings.
+    original function can return. Usually, it's enough to include ``unicode``
+    (or ``str`` on Python 3) here and ensure that your function returns only
+    Unicode strings.
 
     Using this decorator means you can write your function and assume that the
     input is a proper string, then add support for lazy translation objects at the