Opened 13 years ago
Closed 13 years ago
#17738 closed Cleanup/optimization (fixed)
Add a time zone FAQ
Reported by: | Aymeric Augustin | Owned by: | Aymeric Augustin |
---|---|---|---|
Component: | Documentation | Version: | 1.4-beta-1 |
Severity: | Release blocker | Keywords: | |
Cc: | Triage Stage: | Ready for checkin | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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.
Attachments (1)
Change History (7)
follow-up: 4 comment:1 by , 13 years ago
comment:4 by , 13 years ago
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)
by , 13 years ago
Attachment: | 17738.diff added |
---|
comment:5 by , 13 years ago
Has patch: | set |
---|---|
Triage Stage: | Accepted → Ready for checkin |
A good idea. I think the tutorial part I (which deals with datetimes) should point to the FAQ.
Some basic issues to deal with:
Europe/Helsinki
time zone. How do I correctly turn that into a aware datetime? A: ...DateTimeField
), and show it to users as just a date. If you store it as aDateField
, some users will see the edit they just did as "yesterday" or worse, "tomorrow".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.