Got a RuntimeWarning when following the tutorial

[Claude Paroz]

With the new timezone support, creating a Poll object as described in part 1 of the tutorial gives a RuntimeWarning:

>>> from polls.models import Poll, Choice
>>> import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())
>>> p.save()
/home/claude/.../django/db/models/fields/__init__.py:808: RuntimeWarning:
  DateTimeField received a naive datetime (2012-02-17 13:39:45.928590) while time zone support is active.
  RuntimeWarning)

That's not nice for beginners :-(

[Aymeric Augustin]

The tutorial should be changed to use timezone.now() instead, and include a not about this, with a link to the timezone docs.

[Aymeric Augustin]

I've reviewed the tutorial, and adapted parts 1 and 2 for time zone support.

The patch includes a few other minor fixes.

[Aymeric Augustin]

Unfortunately, I've changed slightly the example to dodge a datetime => date conversion, which isn't deterministic for aware datetimes.

As a consequence:

• either we'll have to update again the screenshots that were just updated in r17543 -- sorry Claude :/
• or I can change back the name and description of this function, but then its name won't reflect its behavier, which isn't nice.

I would really appreciate if someone reviewed the patch before I commit it.

[Anssi Kääriäinen]

I can read through it today. I have already read through it quickly, and I think avoiding the harder issues with timezone handling is a good choice. However, to me it seems that new users must read through the timezone documentation (or perhaps the upcoming FAQ) to understand the gotchas in this area. There aren't many, but they are things that will likely be encountered in new projects. So, adding some links in the part I of the tutorial seems necessary.

[Claude Paroz]

+1 for adding a link to time zone docs. Apart from that, it looks fine. Don't worry about updating the screenshots, I'm only a robot :-)

[Anssi Kääriäinen]

The changes look good. I can't spot anything obviously broken. A new user going through the tutorial is the best review here.

Avoiding the hard timezone issues in the tutorial is a good choice. But as said before, links to documentation explaining these things is needed. In general there are surprisingly hard issues due to Python's implementation of datetimes, and the problems with different databases. In addition, many new users haven't given enough thought to these issues. For example "which day is it now" type issues will surprise users. So, giving users pointers on how to deal with timezone issues as early as possible is good in my opinion.

Reiterating my thoughts here, but it would be just wonderful if there was a django.utils.datetime module which would be fully timezone aware when using USE_TZ=True. The common single-timezone setup, where UTC times are used just to dodge issues with DST issues could be handled fully hidden from the user. Use from django.utils import datetime where you used import datetime before. No other changes to tutorial needed. However, this is of course impossible to do for Django 1.4, and might be too hard/laborious to implement ever.

[Aymeric Augustin]

In [17591]:

Fixed #17715 -- Updated the tutorial for time zone support, plus a few other improvements.