[1.6.x] Fixed #20224 -- Update docs examples which mention __unicode__

Thanks Marc Tamlyn and Tim Graham for the review.
Backport of 7442eb1a24 from master.

8 files changed, 23 insertions, 4 deletions

diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index eb2fff05f5..18c30122fc 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -1002,6 +1002,7 @@ authentication app::
             # The user is identified by their email address
             return self.email
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.email
 
diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt
index 8c2d0db041..2f8d561541 100644
--- a/docs/topics/class-based-views/generic-display.txt
+++ b/docs/topics/class-based-views/generic-display.txt
@@ -89,6 +89,7 @@ We'll be using these models::
         class Meta:
             ordering = ["-name"]
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
@@ -98,6 +99,7 @@ We'll be using these models::
         email = models.EmailField()
         headshot = models.ImageField(upload_to='author_headshots')
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt
index 2076427768..42fa9cc1a1 100644
--- a/docs/topics/db/examples/many_to_many.txt
+++ b/docs/topics/db/examples/many_to_many.txt
@@ -16,6 +16,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
     class Publication(models.Model):
         title = models.CharField(max_length=30)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.title
 
@@ -26,6 +27,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
         headline = models.CharField(max_length=100)
         publications = models.ManyToManyField(Publication)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.headline
 
diff --git a/docs/topics/db/examples/many_to_one.txt b/docs/topics/db/examples/many_to_one.txt
index c869362d16..af112144b3 100644
--- a/docs/topics/db/examples/many_to_one.txt
+++ b/docs/topics/db/examples/many_to_one.txt
@@ -15,6 +15,7 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
         last_name = models.CharField(max_length=30)
         email = models.EmailField()
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return u"%s %s" % (self.first_name, self.last_name)
 
@@ -23,6 +24,7 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
         pub_date = models.DateField()
         reporter = models.ForeignKey(Reporter)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.headline
 
@@ -56,9 +58,9 @@ Article objects have access to their related Reporter objects::
 
     >>> r = a.reporter
 
-These are strings instead of unicode strings because that's what was used in
-the creation of this reporter (and we haven't refreshed the data from the
-database, which always returns unicode strings)::
+On Python 2, these are strings of type ``str`` instead of unicode strings
+because that's what was used in the creation of this reporter (and we haven't
+refreshed the data from the database, which always returns unicode strings)::
 
     >>> r.first_name, r.last_name
     ('John', 'Smith')
diff --git a/docs/topics/db/examples/one_to_one.txt b/docs/topics/db/examples/one_to_one.txt
index 09634c84c7..a86e5ed0ac 100644
--- a/docs/topics/db/examples/one_to_one.txt
+++ b/docs/topics/db/examples/one_to_one.txt
@@ -16,6 +16,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
         name = models.CharField(max_length=50)
         address = models.CharField(max_length=80)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return u"%s the place" % self.name
 
@@ -24,6 +25,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
         serves_hot_dogs = models.BooleanField()
         serves_pizza = models.BooleanField()
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return u"%s the restaurant" % self.place.name
 
@@ -31,6 +33,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
         restaurant = models.ForeignKey(Restaurant)
         name = models.CharField(max_length=50)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return u"%s the waiter at %s" % (self.name, self.restaurant)
 
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index c0ba53ddd7..2b565758e7 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -416,6 +416,7 @@ something like this::
     class Person(models.Model):
         name = models.CharField(max_length=128)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
@@ -423,6 +424,7 @@ something like this::
         name = models.CharField(max_length=128)
         members = models.ManyToManyField(Person, through='Membership')
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
@@ -709,7 +711,10 @@ of :ref:`methods automatically given to each model <model-instance-methods>`.
 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.__unicode__`
+: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
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index bdbdd3fa2a..4aa9429c73 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -23,6 +23,7 @@ models, which comprise a Weblog application:
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
@@ -30,6 +31,7 @@ models, which comprise a Weblog application:
         name = models.CharField(max_length=50)
         email = models.EmailField()
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name
 
@@ -44,6 +46,7 @@ models, which comprise a Weblog application:
         n_pingbacks = models.IntegerField()
         rating = models.IntegerField()
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.headline
 
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index bd9e14aea4..d961ee41d5 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -162,6 +162,7 @@ Consider this set of models::
         title = models.CharField(max_length=3, choices=TITLE_CHOICES)
         birth_date = models.DateField(blank=True, null=True)
 
+        # On Python 3: def __str__(self):
         def __unicode__(self):
             return self.name