Merged Unicode branch into trunk (r4952:5608). This should be fully

backwards compatible for all practical purposes.

Fixed #2391, #2489, #2996, #3322, #3344, #3370, #3406, #3432, #3454, #3492, #3582, #3690, #3878, #3891, #3937, #4039, #4141, #4227, #4286, #4291, #4300, #4452, #4702


git-svn-id: http://code.djangoproject.com/svn/django/trunk@5609 bcc190cf-cafb-0310-a4f2-bffc1f526a37

tests/modeltests/str/models.py

@@ -1,23 +1,39 @@
+# -*- coding: utf-8 -*-
 """
-2. Adding __str__() to models
+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.
+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):
+        # Caution: this is only safe if you are certain that headline will be
+        # in ASCII.
         return self.headline
 
-__test__ = {'API_TESTS':"""
+class InternationalArticle(models.Model):
+    headline = models.CharField(maxlength=100)
+    pub_date = models.DateTimeField()
+
+    def __unicode__(self):
+        return self.headline
+
+__test__ = {'API_TESTS':ur"""
 # Create an Article.
 >>> from datetime import datetime
 >>> a = Article(headline='Area man programs in Python', pub_date=datetime(2005, 7, 28))
@@ -28,4 +44,10 @@ __test__ = {'API_TESTS':"""
 
 >>> a
 <Article: Area man programs in Python>
+
+>>> a1 = InternationalArticle(headline=u'Girl wins €12.500 in lottery', pub_date=datetime(2005, 7, 28))
+
+# The default str() output will be the UTF-8 encoded output of __unicode__().
+>>> str(a1)
+'Girl wins \xe2\x82\xac12.500 in lottery'
 """}