gis: Made necessary modifications for unicode, manage refactor, backend refactor and merged 5584-6000 via svnmerge from [repos:django/trunk trunk].

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

1 files changed, 43 insertions, 26 deletions

diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index fdac9c554e..cf2b76e9be 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -22,10 +22,10 @@ installed.
 .. admonition:: Where to get help:
 
     If you're having trouble going through this tutorial, please post a message
-    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll 
+    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll
     try to help.
 
-.. _django-users: http://groups.google.com/group/django-users 
+.. _django-users: http://groups.google.com/group/django-users
 .. _#django: irc://irc.freenode.net/django
 
 Creating a project
@@ -42,7 +42,7 @@ code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
 .. note::
-    
+
     You'll need to avoid naming projects after built-in Python or Django
     components. In particular, this means you should avoid using names like
     ``django`` (which will conflict with Django itself) or ``site`` (which
@@ -251,12 +251,12 @@ These concepts are represented by simple Python classes. Edit the
     from django.db import models
 
     class Poll(models.Model):
-        question = models.CharField(maxlength=200)
+        question = models.CharField(max_length=200)
         pub_date = models.DateTimeField('date published')
 
     class Choice(models.Model):
         poll = models.ForeignKey(Poll)
-        choice = models.CharField(maxlength=200)
+        choice = models.CharField(max_length=200)
         votes = models.IntegerField()
 
 The code is straightforward. Each model is represented by a class that
@@ -279,7 +279,7 @@ name for ``Poll.pub_date``. For all other fields in this model, the field's
 machine-readable name will suffice as its human-readable name.
 
 Some ``Field`` classes have required elements. ``CharField``, for example,
-requires that you give it a ``maxlength``. That's used not only in the database
+requires that you give it a ``max_length``. That's used not only in the database
 schema, but in validation, as we'll soon see.
 
 Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
@@ -321,7 +321,7 @@ Now Django knows ``mysite`` includes the ``polls`` app. Let's run another comman
 
     python manage.py sql polls
 
-You should see something similar to the following (the CREATE TABLE SQL statements 
+You should see something similar to the following (the CREATE TABLE SQL statements
 for the polls app)::
 
     BEGIN;
@@ -341,7 +341,7 @@ for the polls app)::
 Note the following:
 
     * The exact output will vary depending on the database you are using.
-    
+
     * Table names are automatically generated by combining the name of the app
       (``polls``) and the lowercase name of the model -- ``poll`` and
       ``choice``. (You can override this behavior.)
@@ -371,8 +371,8 @@ If you're interested, also run the following commands:
       construction of your models.
 
     * ``python manage.py sqlcustom polls`` -- Outputs any custom SQL statements
-      (such as table modifications or constraints) that are defined for the 
-      application. 
+      (such as table modifications or constraints) that are defined for the
+      application.
 
     * ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP
       TABLE`` statements for this app, according to which tables already exist
@@ -444,8 +444,8 @@ Once you're in the shell, explore the database API::
     []
 
     # Create a new Poll.
-    >>> from datetime import datetime
-    >>> p = Poll(question="What's up?", pub_date=datetime.now())
+    >>> import datetime
+    >>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())
 
     # Save the object into the database. You have to call save() explicitly.
     >>> p.save()
@@ -461,10 +461,10 @@ Once you're in the shell, explore the database API::
     >>> p.question
     "What's up?"
     >>> p.pub_date
-    datetime.datetime(2005, 7, 15, 12, 00, 53)
+    datetime.datetime(2007, 7, 15, 12, 00, 53)
 
     # Change values by changing the attributes, then calling save().
-    >>> p.pub_date = datetime(2005, 4, 1, 0, 0)
+    >>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
     >>> p.save()
 
     # objects.all() displays all the polls in the database.
@@ -474,22 +474,39 @@ 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're familiar with Python, you might be in the habit of adding
+    ``__str__()`` methods to your classes, not ``__unicode__()`` methods.
+    We use ``__unicode__()`` here because Django models deal with Unicode by
+    default. All data stored in your database is converted to Unicode when it's
+    returned.
+
+    Django models have a default ``__str__()`` method that calls
+    ``__unicode__()`` and converts the result to a UTF-8 bytestring. This means
+    that ``unicode(p)`` will return a Unicode string, and ``str(p)`` will return
+    a normal string, with characters encoded as UTF-8.
+
+    If all of this is jibberish to you, just remember to add ``__unicode__()``
+    methods to your models. With any luck, things should Just Work for you.
 
 Note these are normal Python methods. Let's add a custom method, just for
 demonstration::
@@ -509,7 +526,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?>]
 
@@ -520,9 +537,9 @@ Let's jump back into the Python interactive shell by running
     >>> Poll.objects.filter(question__startswith='What')
     [<Poll: What's up?>]
 
-    # Get the poll whose year is 2005. Of course, if you're going through this
+    # Get the poll whose year is 2007. Of course, if you're going through this
     # tutorial in another year, change as appropriate.
-    >>> Poll.objects.get(pub_date__year=2005)
+    >>> Poll.objects.get(pub_date__year=2007)
     <Poll: What's up?>
 
     >>> Poll.objects.get(id=2)
@@ -563,9 +580,9 @@ Let's jump back into the Python interactive shell by running
 
     # The API automatically follows relationships as far as you need.
     # Use double underscores to separate relationships.
-    # This works as many levels deep as you want. There's no limit.
-    # Find all Choices for any poll whose pub_date is in 2005.
-    >>> Choice.objects.filter(poll__pub_date__year=2005)
+    # This works as many levels deep as you want; there's no limit.
+    # Find all Choices for any poll whose pub_date is in 2007.
+    >>> Choice.objects.filter(poll__pub_date__year=2007)
     [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
 
     # Let's delete one of the choices. Use delete() for that.