unicode: Changed all tests and documentation to use __unicode__ instead of

__str__ in places where it's appropriate to do so.


git-svn-id: http://code.djangoproject.com/svn/django/branches/unicode@5386 bcc190cf-cafb-0310-a4f2-bffc1f526a37

46 files changed, 182 insertions, 135 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 6f13b3a467..376cc69822 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -15,14 +15,14 @@ a weblog application::
         name = models.CharField(maxlength=100)
         tagline = models.TextField()
 
-        def __str__(self):
+        def __unicode__(self):
             return self.name
 
     class Author(models.Model):
         name = models.CharField(maxlength=50)
         email = models.URLField()
 
-        def __str__(self):
+        def __unicode__(self):
             return self.name
 
     class Entry(models.Model):
@@ -32,7 +32,7 @@ a weblog application::
         pub_date = models.DateTimeField()
         authors = models.ManyToManyField(Author)
 
-        def __str__(self):
+        def __unicode__(self):
             return self.headline
 
 Creating objects
diff --git a/docs/forms.txt b/docs/forms.txt
index f6cb55a3f6..18d3d3fcbe 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -47,7 +47,7 @@ this document, we'll be working with the following model, a "place" object::
         class Admin:
             pass
 
-        def __str__(self):
+        def __unicode__(self):
             return self.name
 
 Defining the above class is enough to create an admin interface to a ``Place``,
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 9f63b44ee8..a25a703d64 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1339,10 +1339,11 @@ A few special cases to note about ``list_display``:
               born_in_fifties.boolean = True
 
 
-    * The ``__str__()`` method is just as valid in ``list_display`` as any
-      other model method, so it's perfectly OK to do this::
+    * 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::
 
-          list_display = ('__str__', 'some_other_field')
+          list_display = ('__unicode__', '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 at the
@@ -1748,11 +1749,13 @@ A few object methods have special meaning:
 -----------
 
 ``__str__()`` is a Python "magic method" that defines what should be returned
-if you call ``str()`` on the object. Django uses ``str(obj)`` in a number of
-places, most notably as the value displayed to render 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 string for the
-object's ``__str__``. Although this isn't required, it's strongly encouraged.
+if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related
+function, ``unicode(obj)`` -- see below) in a number of places, most notably
+as the value displayed to render 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 string for the object's ``__str__``.
+Although this isn't required, it's strongly encouraged (see the description of
+``__unicode__``, below, before putting ``_str__`` methods everywhere).
 
 For example::
 
@@ -1761,7 +1764,32 @@ For example::
         last_name = models.CharField(maxlength=50)
 
         def __str__(self):
-            return '%s %s' % (self.first_name, self.last_name)
+            # Note use of django.utils.encoding.smart_str() here because
+            # first_name and last_name will be unicode strings.
+            return smart_str('%s %s' % (self.first_name, self.last_name))
+
+``__unicode__``
+---------------
+
+The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
+object. Since Django's database backends will return Unicode strings in your
+model's attributes, you would normally want to write a ``__unicode__()``
+method for your model. The example in the previous section could be written
+more simply as::
+
+    class Person(models.Model):
+        first_name = models.CharField(maxlength=50)
+        last_name = models.CharField(maxlength=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 ``__str__()``
+method, Django will automatically provide you with a ``__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.
 
 ``get_absolute_url``
 --------------------
diff --git a/docs/newforms.txt b/docs/newforms.txt
index bb6c179648..b8b6e00a96 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1333,7 +1333,7 @@ Consider this set of models::
         title = models.CharField(maxlength=3, choices=TITLE_CHOICES)
         birth_date = models.DateField(blank=True, null=True)
 
-        def __str__(self):
+        def __unicode__(self):
             return self.name
 
     class Book(models.Model):
diff --git a/docs/overview.txt b/docs/overview.txt
index 7b3559663a..041ad152c7 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -27,7 +27,7 @@ quick example::
     class Reporter(models.Model):
         full_name = models.CharField(maxlength=70)
 
-        def __str__(self):
+        def __unicode__(self):
             return self.full_name
 
     class Article(models.Model):
@@ -36,7 +36,7 @@ quick example::
         article = models.TextField()
         reporter = models.ForeignKey(Reporter)
 
-        def __str__(self):
+        def __unicode__(self):
             return self.headline
 
 Install it
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index c40b051b19..d5f5fda5b2 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -474,22 +474,38 @@ Once you're in the shell, explore the database API::
 
 Wait a minute. ``<Poll: Poll object>`` is, utterly, an unhelpful
 representation of this object. Let's fix that by editing the polls model (in
-the ``polls/models.py`` file) and adding a ``__str__()`` method to both
+the ``polls/models.py`` file) and adding a ``__unicode__()`` method to both
 ``Poll`` and ``Choice``::
 
     class Poll(models.Model):
         # ...
-        def __str__(self):
+        def __unicode__(self):
             return self.question
 
     class Choice(models.Model):
         # ...
-        def __str__(self):
+        def __unicode__(self):
             return self.choice
 
-It's important to add ``__str__()`` methods to your models, not only for your
-own sanity when dealing with the interactive prompt, but also because objects'
-representations are used throughout Django's automatically-generated admin.
+It's important to add ``__unicode__()`` methods to your models, not only for
+your own sanity when dealing with the interactive prompt, but also because
+objects' representations are used throughout Django's automatically-generated
+admin.
+
+.. admonition:: Why ``__unicode__`` and not ``__str__``?
+
+    If you are wondering why we add a ``__unicode__()`` method, rather than a
+    simple ``__str__()`` method, it is because Django models will contain
+    unicode strings by default. The values returned from the database, for
+    example, are all unicode strings. In most cases, your code should be
+    prepared to handle non-ASCII characters and this is a litle fiddly in
+    ``__str__()`` methods, since you have to worry about which encoding to
+    use, amongst other things. If you create a ``__unicode__()`` method,
+    Django will provide a ``__str__()`` method that calls your
+    ``__unicode__()`` and then converts the result to UTF-8 strings when
+    required. So ``unicode(p)`` will return a unicode string and ``str(p)``
+    will return a normal string, with the characters encoded as UTF-8 when
+    necessary..
 
 Note these are normal Python methods. Let's add a custom method, just for
 demonstration::
@@ -509,7 +525,7 @@ Let's jump back into the Python interactive shell by running
 
     >>> from mysite.polls.models import Poll, Choice
 
-    # Make sure our __str__() addition worked.
+    # Make sure our __unicode__() addition worked.
     >>> Poll.objects.all()
     [<Poll: What's up?>]
 
diff --git a/tests/modeltests/basic/models.py b/tests/modeltests/basic/models.py
index 90e5d1755c..e4fcaf0312 100644
--- a/tests/modeltests/basic/models.py
+++ b/tests/modeltests/basic/models.py
@@ -14,7 +14,7 @@ class Article(models.Model):
     class Meta:
         ordering = ('pub_date','headline')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS': """
diff --git a/tests/modeltests/choices/models.py b/tests/modeltests/choices/models.py
index e287d973bc..cb1bd481cd 100644
--- a/tests/modeltests/choices/models.py
+++ b/tests/modeltests/choices/models.py
@@ -20,7 +20,7 @@ class Person(models.Model):
     name = models.CharField(maxlength=20)
     gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/custom_columns/models.py b/tests/modeltests/custom_columns/models.py
index f1be97c825..fb2487802c 100644
--- a/tests/modeltests/custom_columns/models.py
+++ b/tests/modeltests/custom_columns/models.py
@@ -21,8 +21,8 @@ class Author(models.Model):
     first_name = models.CharField(maxlength=30, db_column='firstname')
     last_name = models.CharField(maxlength=30, db_column='last')
 
-    def __str__(self):
-        return '%s %s' % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u'%s %s' % (self.first_name, self.last_name)
 
     class Meta:
         db_table = 'my_author_table'
@@ -32,7 +32,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100)
     authors = models.ManyToManyField(Author, db_table='my_m2m_table')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
     class Meta:
diff --git a/tests/modeltests/custom_managers/models.py b/tests/modeltests/custom_managers/models.py
index 99df875275..0b9edc88b9 100644
--- a/tests/modeltests/custom_managers/models.py
+++ b/tests/modeltests/custom_managers/models.py
@@ -23,8 +23,8 @@ class Person(models.Model):
     fun = models.BooleanField()
     objects = PersonManager()
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 # An example of a custom manager that sets get_query_set().
 
@@ -39,7 +39,7 @@ class Book(models.Model):
     published_objects = PublishedBookManager()
     authors = models.ManyToManyField(Person, related_name='books')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.title
 
 # An example of providing multiple custom managers.
@@ -55,7 +55,7 @@ class Car(models.Model):
     cars = models.Manager()
     fast_cars = FastCarManager()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/custom_methods/models.py b/tests/modeltests/custom_methods/models.py
index e8fb751d54..5a6581805a 100644
--- a/tests/modeltests/custom_methods/models.py
+++ b/tests/modeltests/custom_methods/models.py
@@ -11,7 +11,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100)
     pub_date = models.DateField()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
     def was_published_today(self):
diff --git a/tests/modeltests/custom_pk/models.py b/tests/modeltests/custom_pk/models.py
index 6265b5fd6e..276fecc371 100644
--- a/tests/modeltests/custom_pk/models.py
+++ b/tests/modeltests/custom_pk/models.py
@@ -15,8 +15,8 @@ class Employee(models.Model):
     class Meta:
         ordering = ('last_name', 'first_name')
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 class Business(models.Model):
     name = models.CharField(maxlength=20, primary_key=True)
@@ -24,7 +24,7 @@ class Business(models.Model):
     class Meta:
         verbose_name_plural = 'businesses'
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/field_defaults/models.py b/tests/modeltests/field_defaults/models.py
index 8e803d00d8..7eafa03798 100644
--- a/tests/modeltests/field_defaults/models.py
+++ b/tests/modeltests/field_defaults/models.py
@@ -16,7 +16,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100, default='Default headline')
     pub_date = models.DateTimeField(default=datetime.now)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/fixtures/models.py b/tests/modeltests/fixtures/models.py
index 88c3230270..c713aa723d 100644
--- a/tests/modeltests/fixtures/models.py
+++ b/tests/modeltests/fixtures/models.py
@@ -14,7 +14,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100, default='Default headline')
     pub_date = models.DateTimeField()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
     class Meta:
diff --git a/tests/modeltests/generic_relations/models.py b/tests/modeltests/generic_relations/models.py
index a4bf36b08f..d77a2ee43d 100644
--- a/tests/modeltests/generic_relations/models.py
+++ b/tests/modeltests/generic_relations/models.py
@@ -24,7 +24,7 @@ class TaggedItem(models.Model):
     class Meta:
         ordering = ["tag"]
     
-    def __str__(self):
+    def __unicode__(self):
         return self.tag
 
 class Animal(models.Model):
@@ -33,7 +33,7 @@ class Animal(models.Model):
     
     tags = generic.GenericRelation(TaggedItem)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.common_name
         
 class Vegetable(models.Model):
@@ -42,7 +42,7 @@ class Vegetable(models.Model):
     
     tags = generic.GenericRelation(TaggedItem)
     
-    def __str__(self):
+    def __unicode__(self):
         return self.name
     
 class Mineral(models.Model):
@@ -51,7 +51,7 @@ class Mineral(models.Model):
     
     # note the lack of an explicit GenericRelation here...
     
-    def __str__(self):
+    def __unicode__(self):
         return self.name
         
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/get_latest/models.py b/tests/modeltests/get_latest/models.py
index 84c6273818..e54e5e32b7 100644
--- a/tests/modeltests/get_latest/models.py
+++ b/tests/modeltests/get_latest/models.py
@@ -17,7 +17,7 @@ class Article(models.Model):
     class Meta:
         get_latest_by = 'pub_date'
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 class Person(models.Model):
@@ -26,7 +26,7 @@ class Person(models.Model):
 
     # Note that this model doesn't have "get_latest_by" set.
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/get_object_or_404/models.py b/tests/modeltests/get_object_or_404/models.py
index 2ad459669f..5f449f4cfe 100644
--- a/tests/modeltests/get_object_or_404/models.py
+++ b/tests/modeltests/get_object_or_404/models.py
@@ -17,7 +17,7 @@ from django.shortcuts import get_object_or_404, get_list_or_404
 class Author(models.Model):
     name = models.CharField(maxlength=50)
     
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class ArticleManager(models.Manager):
@@ -30,7 +30,7 @@ class Article(models.Model):
     objects = models.Manager()
     by_a_sir = ArticleManager()
     
-    def __str__(self):
+    def __unicode__(self):
         return self.title
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/get_or_create/models.py b/tests/modeltests/get_or_create/models.py
index f974a82dee..ed26daa852 100644
--- a/tests/modeltests/get_or_create/models.py
+++ b/tests/modeltests/get_or_create/models.py
@@ -12,8 +12,8 @@ class Person(models.Model):
     last_name = models.CharField(maxlength=100)
     birthday = models.DateField()
 
-    def __str__(self):
-        return '%s %s' % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u'%s %s' % (self.first_name, self.last_name)
 
 __test__ = {'API_TESTS':"""
 # Acting as a divine being, create an Person.
diff --git a/tests/modeltests/lookup/models.py b/tests/modeltests/lookup/models.py
index d06a451503..2e577a6850 100644
--- a/tests/modeltests/lookup/models.py
+++ b/tests/modeltests/lookup/models.py
@@ -12,7 +12,7 @@ class Article(models.Model):
     class Meta:
         ordering = ('-pub_date', 'headline')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':r"""
diff --git a/tests/modeltests/m2m_and_m2o/models.py b/tests/modeltests/m2m_and_m2o/models.py
index 09affb002f..b5adc63b9d 100644
--- a/tests/modeltests/m2m_and_m2o/models.py
+++ b/tests/modeltests/m2m_and_m2o/models.py
@@ -14,8 +14,8 @@ class Issue(models.Model):
     cc = models.ManyToManyField(User, blank=True, related_name='test_issue_cc')
     client = models.ForeignKey(User, related_name='test_issue_client')
 
-    def __str__(self):
-        return str(self.num)
+    def __unicode__(self):
+        return unicode(self.num)
 
     class Meta:
         ordering = ('num',)
diff --git a/tests/modeltests/m2m_intermediary/models.py b/tests/modeltests/m2m_intermediary/models.py
index b917db6189..5e56f44872 100644
--- a/tests/modeltests/m2m_intermediary/models.py
+++ b/tests/modeltests/m2m_intermediary/models.py
@@ -16,14 +16,14 @@ class Reporter(models.Model):
     first_name = models.CharField(maxlength=30)
     last_name = models.CharField(maxlength=30)
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 class Article(models.Model):
     headline = models.CharField(maxlength=100)
     pub_date = models.DateField()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 class Writer(models.Model):
@@ -31,8 +31,8 @@ class Writer(models.Model):
     article = models.ForeignKey(Article)
     position = models.CharField(maxlength=100)
 
-    def __str__(self):
-        return '%s (%s)' % (self.reporter, self.position)
+    def __unicode__(self):
+        return u'%s (%s)' % (self.reporter, self.position)
 
 __test__ = {'API_TESTS':"""
 # Create a few Reporters.
diff --git a/tests/modeltests/m2m_multiple/models.py b/tests/modeltests/m2m_multiple/models.py
index 5a1aa122a9..78c35aafc2 100644
--- a/tests/modeltests/m2m_multiple/models.py
+++ b/tests/modeltests/m2m_multiple/models.py
@@ -14,7 +14,7 @@ class Category(models.Model):
     class Meta:
        ordering = ('name',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Article(models.Model):
@@ -25,7 +25,7 @@ class Article(models.Model):
     class Meta:
        ordering = ('pub_date',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/m2m_recursive/models.py b/tests/modeltests/m2m_recursive/models.py
index 15c713a759..28d98f0600 100644
--- a/tests/modeltests/m2m_recursive/models.py
+++ b/tests/modeltests/m2m_recursive/models.py
@@ -19,7 +19,7 @@ class Person(models.Model):
     friends = models.ManyToManyField('self')
     idols = models.ManyToManyField('self', symmetrical=False, related_name='stalkers')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/m2o_recursive/models.py b/tests/modeltests/m2o_recursive/models.py
index 0b528faf9e..7421061489 100644
--- a/tests/modeltests/m2o_recursive/models.py
+++ b/tests/modeltests/m2o_recursive/models.py
@@ -16,7 +16,7 @@ class Category(models.Model):
     name = models.CharField(maxlength=20)
     parent = models.ForeignKey('self', null=True, related_name='child_set')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/m2o_recursive2/models.py b/tests/modeltests/m2o_recursive2/models.py
index 5b7c5447ad..a8460d6149 100644
--- a/tests/modeltests/m2o_recursive2/models.py
+++ b/tests/modeltests/m2o_recursive2/models.py
@@ -14,7 +14,7 @@ class Person(models.Model):
     mother = models.ForeignKey('self', null=True, related_name='mothers_child_set')
     father = models.ForeignKey('self', null=True, related_name='fathers_child_set')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.full_name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/manipulators/models.py b/tests/modeltests/manipulators/models.py
index e1c2e6d767..7f1ff0e47b 100644
--- a/tests/modeltests/manipulators/models.py
+++ b/tests/modeltests/manipulators/models.py
@@ -10,15 +10,15 @@ class Musician(models.Model):
     first_name = models.CharField(maxlength=30)
     last_name = models.CharField(maxlength=30)
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 class Album(models.Model):
     name = models.CharField(maxlength=100)
     musician = models.ForeignKey(Musician)
     release_date = models.DateField(blank=True, null=True)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/many_to_many/models.py b/tests/modeltests/many_to_many/models.py
index 5e46ad428d..446a39b472 100644
--- a/tests/modeltests/many_to_many/models.py
+++ b/tests/modeltests/many_to_many/models.py
@@ -12,7 +12,7 @@ from django.db import models
 class Publication(models.Model):
     title = models.CharField(maxlength=30)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.title
 
     class Meta:
@@ -22,7 +22,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100)
     publications = models.ManyToManyField(Publication)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
     class Meta:
diff --git a/tests/modeltests/many_to_one/models.py b/tests/modeltests/many_to_one/models.py
index 6b5d09b714..1356b1924b 100644
--- a/tests/modeltests/many_to_one/models.py
+++ b/tests/modeltests/many_to_one/models.py
@@ -11,15 +11,15 @@ class Reporter(models.Model):
     last_name = models.CharField(maxlength=30)
     email = models.EmailField()
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 class Article(models.Model):
     headline = models.CharField(maxlength=100)
     pub_date = models.DateField()
     reporter = models.ForeignKey(Reporter)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
     class Meta:
diff --git a/tests/modeltests/many_to_one_null/models.py b/tests/modeltests/many_to_one_null/models.py
index fb0f6ac3b7..1469dbb5ca 100644
--- a/tests/modeltests/many_to_one_null/models.py
+++ b/tests/modeltests/many_to_one_null/models.py
@@ -10,7 +10,7 @@ from django.db import models
 class Reporter(models.Model):
     name = models.CharField(maxlength=30)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Article(models.Model):
@@ -20,7 +20,7 @@ class Article(models.Model):
     class Meta:
         ordering = ('headline',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/model_forms/models.py b/tests/modeltests/model_forms/models.py
index f60aa0ac1d..a21bef02ce 100644
--- a/tests/modeltests/model_forms/models.py
+++ b/tests/modeltests/model_forms/models.py
@@ -34,13 +34,13 @@ class Category(models.Model):
     name = models.CharField(maxlength=20)
     url = models.CharField('The URL', maxlength=40)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Writer(models.Model):
     name = models.CharField(maxlength=50, help_text='Use both first and last names.')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Article(models.Model):
@@ -58,14 +58,14 @@ class Article(models.Model):
             self.created = datetime.date.today()
         return super(Article, self).save()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 class PhoneNumber(models.Model):
     phone = models.PhoneNumberField()
     description = models.CharField(maxlength=20)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.phone
 
 __test__ = {'API_TESTS': """
diff --git a/tests/modeltests/model_inheritance/models.py b/tests/modeltests/model_inheritance/models.py
index babef73e0a..8fbd518928 100644
--- a/tests/modeltests/model_inheritance/models.py
+++ b/tests/modeltests/model_inheritance/models.py
@@ -10,21 +10,21 @@ class Place(models.Model):
     name = models.CharField(maxlength=50)
     address = models.CharField(maxlength=80)
 
-    def __str__(self):
-        return "%s the place" % self.name
+    def __unicode__(self):
+        return u"%s the place" % self.name
 
 class Restaurant(Place):
     serves_hot_dogs = models.BooleanField()
     serves_pizza = models.BooleanField()
 
-    def __str__(self):
-        return "%s the restaurant" % self.name
+    def __unicode__(self):
+        return u"%s the restaurant" % self.name
 
 class ItalianRestaurant(Restaurant):
     serves_gnocchi = models.BooleanField()
 
-    def __str__(self):
-        return "%s the italian restaurant" % self.name
+    def __unicode__(self):
+        return u"%s the italian restaurant" % self.name
 
 __test__ = {'API_TESTS':"""
 # Make sure Restaurant has the right fields in the right order.
diff --git a/tests/modeltests/one_to_one/models.py b/tests/modeltests/one_to_one/models.py
index 7488204ff1..99228d21a8 100644
--- a/tests/modeltests/one_to_one/models.py
+++ b/tests/modeltests/one_to_one/models.py
@@ -12,23 +12,23 @@ class Place(models.Model):
     name = models.CharField(maxlength=50)
     address = models.CharField(maxlength=80)
 
-    def __str__(self):
-        return "%s the place" % self.name
+    def __unicode__(self):
+        return u"%s the place" % self.name
 
 class Restaurant(models.Model):
     place = models.OneToOneField(Place)
     serves_hot_dogs = models.BooleanField()
     serves_pizza = models.BooleanField()
 
-    def __str__(self):
-        return "%s the restaurant" % self.place.name
+    def __unicode__(self):
+        return u"%s the restaurant" % self.place.name
 
 class Waiter(models.Model):
     restaurant = models.ForeignKey(Restaurant)
     name = models.CharField(maxlength=50)
 
-    def __str__(self):
-        return "%s the waiter at %s" % (self.name, self.restaurant)
+    def __unicode__(self):
+        return u"%s the waiter at %s" % (self.name, self.restaurant)
 
 class ManualPrimaryKey(models.Model):
     primary_key = models.CharField(maxlength=10, primary_key=True)
diff --git a/tests/modeltests/or_lookups/models.py b/tests/modeltests/or_lookups/models.py
index 5587f58438..142df16081 100644
--- a/tests/modeltests/or_lookups/models.py
+++ b/tests/modeltests/or_lookups/models.py
@@ -20,7 +20,7 @@ class Article(models.Model):
     class Meta:
        ordering = ('pub_date',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/ordering/models.py b/tests/modeltests/ordering/models.py
index 110ae3d7fc..1c4e08c11c 100644
--- a/tests/modeltests/ordering/models.py
+++ b/tests/modeltests/ordering/models.py
@@ -21,7 +21,7 @@ class Article(models.Model):
     class Meta:
         ordering = ('-pub_date', 'headline')
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/pagination/models.py b/tests/modeltests/pagination/models.py
index 94deb885f5..2834d293e4 100644
--- a/tests/modeltests/pagination/models.py
+++ b/tests/modeltests/pagination/models.py
@@ -12,7 +12,7 @@ class Article(models.Model):
     headline = models.CharField(maxlength=100, default='Default headline')
     pub_date = models.DateTimeField()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/reserved_names/models.py b/tests/modeltests/reserved_names/models.py
index affe3f649d..acec978d86 100644
--- a/tests/modeltests/reserved_names/models.py
+++ b/tests/modeltests/reserved_names/models.py
@@ -21,7 +21,7 @@ class Thing(models.Model):
     class Meta:
        db_table = 'select'
 
-    def __str__(self):
+    def __unicode__(self):
         return self.when
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/reverse_lookup/models.py b/tests/modeltests/reverse_lookup/models.py
index 4d6591551a..957c1dfb96 100644
--- a/tests/modeltests/reverse_lookup/models.py
+++ b/tests/modeltests/reverse_lookup/models.py
@@ -9,14 +9,14 @@ from django.db import models
 class User(models.Model):
     name = models.CharField(maxlength=200)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Poll(models.Model):
     question = models.CharField(maxlength=200)
     creator = models.ForeignKey(User)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.question
 
 class Choice(models.Model):
@@ -24,7 +24,7 @@ class Choice(models.Model):
     poll = models.ForeignKey(Poll, related_name="poll_choice")
     related_poll = models.ForeignKey(Poll, related_name="related_choice")
 
-    def __str(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/modeltests/save_delete_hooks/models.py b/tests/modeltests/save_delete_hooks/models.py
index 6e24c308ba..292cfd8e9e 100644
--- a/tests/modeltests/save_delete_hooks/models.py
+++ b/tests/modeltests/save_delete_hooks/models.py
@@ -11,8 +11,8 @@ class Person(models.Model):
     first_name = models.CharField(maxlength=20)
     last_name = models.CharField(maxlength=20)
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
     def save(self):
         print "Before save"
diff --git a/tests/modeltests/select_related/models.py b/tests/modeltests/select_related/models.py
index cd34bd1d84..235712ef27 100644
--- a/tests/modeltests/select_related/models.py
+++ b/tests/modeltests/select_related/models.py
@@ -13,49 +13,49 @@ from django.db import models
 
 class Domain(models.Model):
     name = models.CharField(maxlength=50)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Kingdom(models.Model):
     name = models.CharField(maxlength=50)
     domain = models.ForeignKey(Domain)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Phylum(models.Model):
     name = models.CharField(maxlength=50)
     kingdom = models.ForeignKey(Kingdom)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
     
 class Klass(models.Model):
     name = models.CharField(maxlength=50)
     phylum = models.ForeignKey(Phylum)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
     
 class Order(models.Model):
     name = models.CharField(maxlength=50)
     klass = models.ForeignKey(Klass)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Family(models.Model):
     name = models.CharField(maxlength=50)
     order = models.ForeignKey(Order)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Genus(models.Model):
     name = models.CharField(maxlength=50)
     family = models.ForeignKey(Family)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Species(models.Model):
     name = models.CharField(maxlength=50)
     genus = models.ForeignKey(Genus)
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 def create_tree(stringtree):
diff --git a/tests/modeltests/serializers/models.py b/tests/modeltests/serializers/models.py
index 339303fc0a..e5064a09fe 100644
--- a/tests/modeltests/serializers/models.py
+++ b/tests/modeltests/serializers/models.py
@@ -13,7 +13,7 @@ class Category(models.Model):
     class Meta:
        ordering = ('name',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Author(models.Model):
@@ -22,7 +22,7 @@ class Author(models.Model):
     class Meta:
         ordering = ('name',)
     
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 class Article(models.Model):
@@ -34,15 +34,15 @@ class Article(models.Model):
     class Meta:
        ordering = ('pub_date',)
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
 class AuthorProfile(models.Model):
     author = models.OneToOneField(Author)
     date_of_birth = models.DateField()
     
-    def __str__(self):
-        return "Profile of %s" % self.author
+    def __unicode__(self):
+        return u"Profile of %s" % self.author
 
 __test__ = {'API_TESTS':"""
 # Create some data:
diff --git a/tests/modeltests/str/models.py b/tests/modeltests/str/models.py
index a700daddcc..2c16bf3305 100644
--- a/tests/modeltests/str/models.py
+++ b/tests/modeltests/str/models.py
@@ -2,24 +2,27 @@
 """
 2. Adding __str__() or __unicode__() to models
 
-Although it's not a strict requirement, each model should have a ``__str__()``
-method to return a "human-readable" representation of the object. Do this not
-only for your own sanity when dealing with the interactive prompt, but also
-because objects' representations are used throughout Django's
-automatically-generated admin.
-
-For international applications, you should write ``__unicode__``() method
-instead.
+Although it's not a strict requirement, each model should have a
+``_str__()`` or ``__unicode__()`` method to return a "human-readable"
+representation of the object. Do this not only for your own sanity when dealing
+with the interactive prompt, but also because objects' representations are used
+throughout Django's automatically-generated admin.
+
+Normally,  you should write ``__unicode__``() method, since this will work for
+all field types (and Django will automatically provide an appropriate
+``__str__()`` method). However, you can write a ``__str__()`` method directly,
+if you prefer. You must be careful to encode the results correctly, though.
 """
 
 from django.db import models
+from django.utils.encoding import smart_str
 
 class Article(models.Model):
     headline = models.CharField(maxlength=100)
     pub_date = models.DateTimeField()
 
     def __str__(self):
-        return self.headline
+        return smart_str(self.headline)
 
 class InternationalArticle(models.Model):
     headline = models.CharField(maxlength=100)
diff --git a/tests/modeltests/transactions/models.py b/tests/modeltests/transactions/models.py
index e1fad8063e..d7eba6e4d3 100644
--- a/tests/modeltests/transactions/models.py
+++ b/tests/modeltests/transactions/models.py
@@ -14,8 +14,8 @@ class Reporter(models.Model):
     last_name = models.CharField(maxlength=30)
     email = models.EmailField()
 
-    def __str__(self):
-        return "%s %s" % (self.first_name, self.last_name)
+    def __unicode__(self):
+        return u"%s %s" % (self.first_name, self.last_name)
 
 __test__ = {'API_TESTS':"""
 >>> from django.db import connection, transaction
@@ -96,4 +96,4 @@ Exception: I meant to do that
 Traceback (most recent call last):
     ...
 TransactionManagementError: Transaction managed block ended with pending COMMIT/ROLLBACK
-"""
\ No newline at end of file
+"""
diff --git a/tests/modeltests/validation/models.py b/tests/modeltests/validation/models.py
index 5cf3a7622a..5be2f867a4 100644
--- a/tests/modeltests/validation/models.py
+++ b/tests/modeltests/validation/models.py
@@ -17,7 +17,7 @@ class Person(models.Model):
     favorite_moment = models.DateTimeField()
     email = models.EmailField()
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
 
 __test__ = {'API_TESTS':"""
diff --git a/tests/regressiontests/fixtures_regress/models.py b/tests/regressiontests/fixtures_regress/models.py
index dd407df353..31528238e9 100644
--- a/tests/regressiontests/fixtures_regress/models.py
+++ b/tests/regressiontests/fixtures_regress/models.py
@@ -4,8 +4,8 @@ class Animal(models.Model):
     name = models.CharField(maxlength=150)
     latin_name = models.CharField(maxlength=150)
 
-    def __str__(self):
-        return self.common_name    
+    def __unicode__(self):
+        return self.common_name
 
 class Plant(models.Model):
     name = models.CharField(maxlength=150)
@@ -26,4 +26,4 @@ __test__ = {'API_TESTS':"""
 >>> animal = Animal(name='Platypus', latin_name='Ornithorhynchus anatinus')
 >>> animal.save()
 
-"""}
\ No newline at end of file
+"""}
diff --git a/tests/regressiontests/null_queries/models.py b/tests/regressiontests/null_queries/models.py
index 21944d9e7a..2e903876bf 100644
--- a/tests/regressiontests/null_queries/models.py
+++ b/tests/regressiontests/null_queries/models.py
@@ -3,15 +3,15 @@ from django.db import models
 class Poll(models.Model):
     question = models.CharField(maxlength=200)
 
-    def __str__(self):
-        return "Q: %s " % self.question
+    def __unicode__(self):
+        return u"Q: %s " % self.question
 
 class Choice(models.Model):
     poll = models.ForeignKey(Poll)
     choice = models.CharField(maxlength=200)
 
-    def __str__(self):
-        return "Choice: %s in poll %s" % (self.choice, self.poll)
+    def __unicode__(self):
+        return u"Choice: %s in poll %s" % (self.choice, self.poll)
 
 __test__ = {'API_TESTS':"""
 # Regression test for the use of None as a query value. None is interpreted as 
diff --git a/tests/regressiontests/one_to_one_regress/models.py b/tests/regressiontests/one_to_one_regress/models.py
index b81f4266e1..be48c842ed 100644
--- a/tests/regressiontests/one_to_one_regress/models.py
+++ b/tests/regressiontests/one_to_one_regress/models.py
@@ -4,23 +4,23 @@ class Place(models.Model):
     name = models.CharField(maxlength=50)
     address = models.CharField(maxlength=80)
 
-    def __str__(self):
-        return "%s the place" % self.name
+    def __unicode__(self):
+        return u"%s the place" % self.name
 
 class Restaurant(models.Model):
     place = models.OneToOneField(Place)
     serves_hot_dogs = models.BooleanField()
     serves_pizza = models.BooleanField()
 
-    def __str__(self):
-        return "%s the restaurant" % self.place.name
+    def __unicode__(self):
+        return u"%s the restaurant" % self.place.name
 
 class Favorites(models.Model):
     name = models.CharField(maxlength = 50)
     restaurants = models.ManyToManyField(Restaurant)
 
-    def __str__(self):
-        return "Favorites for %s" % self.name
+    def __unicode__(self):
+        return u"Favorites for %s" % self.name
 
 __test__ = {'API_TESTS':"""
 # Regression test for #1064 and #1506: Check that we create models via the m2m