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

6 files changed, 67 insertions, 23 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?>]