#27921: Documentation of make_aware() with is_dst is misleading
-------------------------------------+-------------------------------------
Reporter: Kevin Christopher | Owner: nobody
Henry |
Type: Bug | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Kevin Christopher Henry):
We can definitely all agree that this is a hard subject to document
concisely and accurately.
I think the current version is just too concise to be acceptably accurate.
It gives the impression that the wall clock time changes, and by not
specifying the time zone of the 1:30 and 3:30 risks leaving the impression
that they differ by two hours instead of one. Here's an attempt at
avoiding that while keeping the example (at the cost of being a bit more
verbose):
> The `pytz.NonExistentTimeError` exception is raised if you try to make
`value` aware during a DST transition such that the time never occurred.
For example, if the 2:00 hour is skipped during a DST transition, trying
to make 2:30 aware in that time zone will lead to an exception. To avoid
that you can use `is_dst` to specify how `make_aware` should interpret
such a non-existing time. If `True` then the above time would be
interpreted as 2:30 DST time (equivalent to 1:30 local time). Conversely,
if `False` the time would be interpreted as 2:30 standard time (equivalent
to 3:30 local time).
(Coincidentally, we're passing through a block of NonExistent time here in
`America/New_York` as I write this...)
--
Ticket URL: <https://code.djangoproject.com/ticket/27921#comment:8>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/065.f1bdbcd0b6dda8425f2d98eb489e06ca%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
