Add a time zone FAQ

[Aymeric Augustin]

Feedback on the new time zone support shows that many developers aren't familiar with aware datetime objects.

The time zone docs should be refactored to highlight the common issues in a FAQ, in order to help everyone learn the new rules.

[Anssi Kääriäinen]

A good idea. I think the tutorial part I (which deals with datetimes) should point to the FAQ.

Some basic issues to deal with:

• Q: How do I activate a time zone? Where can I see all the available time zones? A: For the first question, use activate(timezone). For the second question: ???
• Q: I have this string "2012-02-21 10:28:45". It is in Europe/Helsinki time zone. How do I correctly turn that into a aware datetime? A: ...
• Q: How about it is just in the users current time zone, any difference here? A: As above, but you can get the current time zone by get_current_timezone().
• Q: How do I get a datetime in my timezone? A: You can get it by using localtime(value). However, are you sure you want to? In most situations it is better to handle the datetimes in UTC, and just display it in local time zone.
• Q: How do I compare datetimes correctly? A: Comparing two UTC-datetimes is easy: it just works. However, if you want to compare if two datetimes happened on the same day/month, you most likely want to do it in the user's time zone: convert first to localtime, then compare the local dates. For example, is the dt's date today? localtime(dt).date() == localtime(now()).date()?
• Q: I want to show users the date of last edit. How do I do that? A: Current date is affected by the user's time zone (usually it is a different day in Australia than in USA). So, you should store the last edit date as a datetime (DateTimeField), and show it to users as just a date. If you store it as a DateField, some users will see the edit they just did as "yesterday" or worse, "tomorrow".
• Q: Why are datetimes stored in UTC and why should I care? A: See these links (pytz had at least a good explanation of this, no?).
• Q: Should I install pytz? A: Yes. Django works without it, but you get nicer behaviour with pytz installed.

I probably went a bit overboard with these questions, but I figured it is better to put all these questions here so that you can pick the ones which seem like frequent ones.

[Aymeric Augustin]

That's a very good list, thanks :)

[Aymeric Augustin]

Related: #17808.

[Aymeric Augustin]

I've integrated some questions as is in the patch. Here's why I altered or didn't keep others.

• Q: How do I activate a time zone? A: use activate(timezone)

It's easy to locate "Selecting the current time zone" in the sidebar. I don't find it useful to repeat that information in the FAQ.

• Q: I have this string "2012-02-21 10:28:45". It is in Europe/Helsinki time zone. How do I correctly turn that into a aware datetime? A: ...
• Q: How about it is just , any difference here? A: As above, but you can get the current time zone by get_current_timezone()

I kept the first question, because the value may come from an external, naive API.
I left out the second one because user input is supposed to come through forms, and the form layers deals with the conversion for you. I don't want to suggest emulating built-in functionality.

• Q: How do I get a datetime in my timezone? A: You can get it by using localtime(value). However, are you sure you want to? In most situations it is better to handle the datetimes in UTC, and just display it in local time zone.

localtime was specifically written for use by the template engine. I've decided to remove it from the public API, because it performs lots of template-specific checks and then just calls value.astimezone(get_current_timezone()).

• Q: How do I compare datetimes correctly? A: Comparing two UTC-datetimes is easy: it just works. However, if you want to compare if two datetimes happened on the same day/month, you most likely want to do it in the user's time zone: convert first to localtime, then compare the local dates. For example, is the dt's date today? localtime(dt).date() == localtime(now()).date()?

The real difficulty is that, contrary to common assumptions, an aware datetime doesn't have a deterministic date -- that is, you can have dt1 == dt2 but dt1.date() != dt2.date(). This is already covered in another question (date of last edit)

[Aymeric Augustin]

In [17645]:

Fixed #17738 -- Extended the time zone documentation with a FAQ. Thanks Anssi for the questions and Jannis for the review.