Ticket #17715: 17715.diff

docs/intro/tutorial01.txt

@@ -219 +219 @@
   an empty string if your database server is on the same physical
   machine (not used for SQLite).
 
-If you're new to databases, we recommend simply using SQLite (by
-setting :setting:`ENGINE` to ``'django.db.backends.sqlite3'``). SQLite
-is included as part of Python 2.5 and later, so you won't need to
-install anything else.
+If you're new to databases, we recommend simply using SQLite by setting
+:setting:`ENGINE` to ``'django.db.backends.sqlite3'`` and :setting:`NAME` to
+``'database.sqlite3'``. SQLite is included as part of Python 2.5 and later, so
+you won't need to install anything else.
 
 .. note::
 
@@ -233 +233 @@
     If you're using SQLite, you don't need to create anything beforehand - the
     database file will be created automatically when it is needed.
 
-While you're editing :file:`settings.py`, take note of the
-:setting:`INSTALLED_APPS` setting towards the bottom of the file. That variable
-holds the names of all Django applications that are activated in this Django
-instance. Apps can be used in multiple projects, and you can package and
-distribute them for use by others in their projects.
+While you're editing :file:`settings.py`, set :setting:`TIME_ZONE` to your
+time zone. The default value isn't correct for you, unless you happen to live
+near Chicago.
 
+Also, take note of the :setting:`INSTALLED_APPS` setting towards the bottom of
+the file. That variable holds the names of all Django applications that are
+activated in this Django instance. Apps can be used in multiple projects, and
+you can package and distribute them for use by others in their projects.
+
 By default, :setting:`INSTALLED_APPS` contains the following apps, all of which
 come with Django:
 
@@ -414 +417 @@
         'django.contrib.contenttypes',
         'django.contrib.sessions',
         'django.contrib.sites',
+        'django.contrib.messages',
+        'django.contrib.staticfiles',
+        # Uncomment the next line to enable the admin:
+        # 'django.contrib.admin',
+        # Uncomment the next line to enable admin documentation:
+        # 'django.contrib.admindocs',
         'polls',
     )
 
@@ -437 +446 @@
     );
     CREATE TABLE "polls_choice" (
         "id" serial NOT NULL PRIMARY KEY,
-        "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
+        "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id") DEFERRABLE INITIALLY DEFERRED,
         "choice" varchar(200) NOT NULL,
         "votes" integer NOT NULL
     );
@@ -454 +463 @@
 * Primary keys (IDs) are added automatically. (You can override this, too.)
 
 * By convention, Django appends ``"_id"`` to the foreign key field name.
-  Yes, you can override this, as well.
+  (Yes, you can override this, as well.)
 
 * The foreign key relationship is made explicit by a ``REFERENCES``
   statement.
@@ -501 +510 @@
 
     python manage.py syncdb
 
-The :djadmin:`syncdb` command runs the sql from 'sqlall' on your database for
-all apps in :setting:`INSTALLED_APPS` that don't already exist in your database.
-This creates all the tables, initial data and indexes for any apps you have
-added to your project since the last time you ran syncdb. :djadmin:`syncdb` can
-be called as often as you like, and it will only ever create the tables that
-don't exist.
+The :djadmin:`syncdb` command runs the sql from :djadmin:`sqlall` on your
+database for all apps in :setting:`INSTALLED_APPS` that don't already exist in
+your database. This creates all the tables, initial data and indexes for any
+apps you have added to your project since the last time you ran syncdb.
+:djadmin:`syncdb` can be called as often as you like, and it will only ever
+create the tables that don't exist.
 
 Read the :doc:`django-admin.py documentation </ref/django-admin>` for full
 information on what the ``manage.py`` utility can do.
@@ -537 +546 @@
 
 Once you're in the shell, explore the :doc:`database API </topics/db/queries>`::
 
-    >>> from polls.models import Poll, Choice # Import the model classes we just wrote.
+    >>> from polls.models import Poll, Choice   # Import the model classes we just wrote.
 
     # No polls are in the system yet.
     >>> Poll.objects.all()
     []
 
     # Create a new Poll.
-    >>> import datetime
-    >>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())
+    # Support for time zones is enabled in the default settings file, so
+    # Django expects a datetime with a tzinfo attribute in pub_date. Just use
+    # timezone.now() instead of datetime.datetime.now() for now; it will do
+    # the right thing in all circumstances. See the time zone docs for more.
+    >>> from django.utils import timezone
+    >>> p = Poll(question="What's new?", pub_date=timezone.now())
 
     # Save the object into the database. You have to call save() explicitly.
     >>> p.save()
@@ -559 +572 @@
 
     # Access database columns via Python attributes.
     >>> p.question
-    "What's up?"
+    "What's new?"
     >>> p.pub_date
-    datetime.datetime(2007, 7, 15, 12, 00, 53)
+    datetime.datetime(2012, 7, 15, 12, 0, 53, 775217, tzinfo=<UTC>)
 
     # Change values by changing the attributes, then calling save().
-    >>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
+    >>> p.question = "What's up?"
     >>> p.save()
 
     # objects.all() displays all the polls in the database.
@@ -617 +630 @@
 demonstration::
 
     import datetime
+    from django.utils import timezone
     # ...
     class Poll(models.Model):
         # ...
-        def was_published_today(self):
-            return self.pub_date.date() == datetime.date.today()
+        def was_published_recently(self):
+            return self.pub_date >= timezone.now() - datetime.timedelta(days=1)
 
-Note the addition of ``import datetime`` to reference Python's standard
-``datetime`` module.
+Note the addition of ``import datetime`` and ``from django.utils import
+timezone``, to reference Python's standard ``datetime`` module and Django's
+time zone-related utilities respectively.
 
 Save these changes and start a new Python interactive shell by running
 ``python manage.py shell`` again::
@@ -642 +657 @@
     >>> Poll.objects.filter(question__startswith='What')
     [<Poll: What's up?>]
 
-    # Get the poll whose year is 2007.
-    >>> Poll.objects.get(pub_date__year=2007)
+    # Get the poll whose year is 2012.
+    >>> Poll.objects.get(pub_date__year=2012)
     <Poll: What's up?>
 
     >>> Poll.objects.get(id=2)
@@ -659 +674 @@
 
     # Make sure our custom method worked.
     >>> p = Poll.objects.get(pk=1)
-    >>> p.was_published_today()
-    False
+    >>> p.was_published_recently()
+    True
 
     # Give the Poll a couple of Choices. The create call constructs a new
     # choice object, does the INSERT statement, adds the choice to the set
@@ -693 +708 @@
     # 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 2007.
-    >>> Choice.objects.filter(poll__pub_date__year=2007)
+    # Find all Choices for any poll whose pub_date is in 2012.
+    >>> Choice.objects.filter(poll__pub_date__year=2012)
     [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
 
     # Let's delete one of the choices. Use delete() for that.

docs/intro/tutorial02.txt

@@ -18 +18 @@
     displayed on the public site. Django solves the problem of creating a
     unified interface for site administrators to edit content.
 
-    The admin isn't necessarily intended to be used by site visitors; it's for
-    site managers.
+    The admin isn't intended to be used by site visitors; it's for site
+    managers.
 
 Activate the admin site
 =======================
@@ -27 +27 @@
 The Django admin site is not activated by default -- it's an opt-in thing. To
 activate the admin site for your installation, do these three things:
 
-* Add ``"django.contrib.admin"`` to your :setting:`INSTALLED_APPS` setting.
+* Uncomment ``"django.contrib.admin"`` in the :setting:`INSTALLED_APPS` setting.
 
 * Run ``python manage.py syncdb``. Since you have added a new application
   to :setting:`INSTALLED_APPS`, the database tables need to be updated.
@@ -101 +101 @@
 .. image:: _images/admin02t.png
    :alt: Django admin index page
 
-You should see a few other types of editable content, including groups, users
+You should see a few types of editable content, including groups, users
 and sites. These are core features Django ships with by default.
 
 Make the poll app modifiable in the admin
@@ -169 +169 @@
 
 * Delete -- Displays a delete confirmation page.
 
+If the value of "Date published" doesn't match the time when you created the
+poll in Tutorial 1, it probably means you forgot to set the correct value for
+the :setting:`TIME_ZONE` setting. Change it, reload the page, and check that
+the correct value appears.
+
 Change the "Date published" by clicking the "Today" and "Now" shortcuts. Then
 click "Save and continue editing." Then click "History" in the upper right.
 You'll see a page listing all changes made to this object via the Django admin,
@@ -337 +342 @@
         # ...
         list_display = ('question', 'pub_date')
 
-Just for good measure, let's also include the ``was_published_today`` custom
+Just for good measure, let's also include the ``was_published_recently`` custom
 method from Tutorial 1::
 
     class PollAdmin(admin.ModelAdmin):
         # ...
-        list_display = ('question', 'pub_date', 'was_published_today')
+        list_display = ('question', 'pub_date', 'was_published_recently')
 
 Now the poll change list page looks like this:
 
@@ -350 +355 @@
    :alt: Polls change list page, updated
 
 You can click on the column headers to sort by those values -- except in the
-case of the ``was_published_today`` header, because sorting by the output of
+case of the ``was_published_recently`` header, because sorting by the output of
 an arbitrary method is not supported. Also note that the column header for
-``was_published_today`` is, by default, the name of the method (with
+``was_published_recently`` is, by default, the name of the method (with
 underscores replaced with spaces). But you can change that by giving that
 method (in ``models.py``) a ``short_description`` attribute::
 
     class Poll(models.Model):
         # ...
-        def was_published_today(self):
-            return self.pub_date.date() == datetime.date.today()
-        was_published_today.short_description = 'Published today?'
+        def was_published_recently(self):
+            return self.pub_date >= timezone.now() - datetime.timedelta(days=1)
+        was_published_recently.short_description = 'Published less than 1 day ago?'
 
 Edit your admin.py file again and add an improvement to the Poll change list page: Filters. Add the
 following line to ``PollAdmin``::
@@ -374 +379 @@
    :alt: Polls change list page, updated
 
 The type of filter displayed depends on the type of field you're filtering on.
-Because ``pub_date`` is a DateTimeField, Django knows to give the default
-filter options for DateTimeFields: "Any date," "Today," "Past 7 days,"
-"This month," "This year."
+Because ``pub_date`` is a :class:`~django.db.models.fields.DateTimeField`,
+Django knows to give the default filter options for ``DateTimeField``s: "Any
+date," "Today," "Past 7 days," "This month," "This year."
 
 This is shaping up well. Let's add some search capability::
 

django/utils/timezone.py

@@ -32 +32 @@
     Used only when pytz isn't available.
     """
 
+    def __repr__(self):
+        return "<UTC>"
+
     def utcoffset(self, dt):
         return ZERO
 
@@ -60 +63 @@
         self.DSTDIFF = self.DSTOFFSET - self.STDOFFSET
         tzinfo.__init__(self)
 
+    def __repr__(self):
+        return "<LocalTimezone>"
+
     def utcoffset(self, dt):
         if self._isdst(dt):
             return self.DSTOFFSET