#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):
pytz does actually use `is_dst` to avoid the `NonExistentTimeError` (see
the linked question for some console tests). Though I agree, Aymeric, that
that usage seems less intuitive than in the `AmbiguousTimeError` case.
I wonder if this calls for ''less'' documentation rather than more. The
problem is that we're relying on a third-party library who's behavior is
not specified. The pytz docs imply that using `is_dst` will avoid the
error, but they don't specify whether that's done by shifting the wall-
clock time (as currently documented by Django) or by shifting the timezone
offset (as appears to actually be the case).
Would it be sufficient to say:
> The `pytz.NonExistentTimeError` exception is raised if you try to make
`value` aware during a DST transition such that the time never occurred
(when entering into DST). Setting `is_dst` to `True` or `False` will avoid
the exception by moving the time backwards or forwards by 1 hour
respectively.
That's really the most you can say based on pytz's documentation.
--
Ticket URL: <https://code.djangoproject.com/ticket/27921#comment:3>
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.57ff3e63306bb0de820e7395af6e2c07%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
