#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 Josh Smeaton):
I don't think we should be too concerned about the wording of the `pytz`
documentation. We should aim to provide our own docs that makes the most
sense for our users. In that regard, perhaps it is worth clarifying the
documentation in some way. I'm not exactly sure what that should be
though. When I implemented this change, I was also confused about how pytz
was representing time during ambiguous and non-existent periods, so I'm
not surprised that users are also somewhat confused.
Just quickly, the currently implemented behaviour is correct. Either side
of the transition round trips through the database and via UTC to the
correct moment in time. But it doesn't sound like that bit is in question.
I'd also readily admit that the use case for `is_dst=True` for non
existent times is probably very little - I can't think of one.
Even in the ambiguous case, pytz represents the time as a shift in the
timezone.
{{{
In [65]: CET = pytz.timezone("Europe/Paris")
In [66]: ambiguous = datetime.datetime(2015, 10, 25, 2, 30)
In [67]: std = timezone.make_aware(ambiguous, timezone=CET, is_dst=False)
...: dst = timezone.make_aware(ambiguous, timezone=CET, is_dst=True)
...:
In [68]: std
Out[68]: datetime.datetime(2015, 10, 25, 2, 30, tzinfo=<DstTzInfo
'Europe/Paris' CET+1:00:00 STD>)
In [69]: dst
Out[69]: datetime.datetime(2015, 10, 25, 2, 30, tzinfo=<DstTzInfo
'Europe/Paris' CEST+2:00:00 DST>)
}}}
The representation is an adjustment in the timezone, but the logical
result is a shift 1 hour backwards or 1 hour forwards in the *moment* of
time. Neither Ambiguous or NonExistent modify the hour or minute
accessible on the datetime instance. But if you save the result and fetch
it, or round trip it through UTC, then the hour on the returned datetime
object *does* change.
Is it important to tell users that the time change is *represented* by a
timezone shift? Conceptually, adjusting the hour is an easier concept to
grasp even if the timezone offset is actually the thing changing in the
current representation.
To further complicate things:
{{{
# Equivalences
In [32]: tz = pytz.timezone('America/Sao_Paulo')
...: dt = datetime.datetime(2017, 10, 15, 0)
...: dt_plus_one = datetime.datetime(2017, 10, 15, 1)
...: dt_minus_one = datetime.datetime(2017, 10, 14, 23)
...:
In [33]: std = timezone.make_aware(dt, timezone=tz, is_dst=False)
In [34]: dst = timezone.make_aware(dt, timezone=tz, is_dst=True)
In [35]: after = timezone.make_aware(dt_plus_one, timezone=tz)
In [36]: before = timezone.make_aware(dt_minus_one, timezone=tz)
In [52]: dt_plus_one_aware = timezone.make_aware(dt_plus_one, timezone=tz)
In [53]: dt_plus_one_aware
Out[53]: datetime.datetime(2017, 10, 15, 1, 0, tzinfo=<DstTzInfo
'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>)
In [54]: aware_minus = dt_plus_one_aware - timedelta(hours=1)
Out[54]: datetime.datetime(2017, 10, 15, 0, 0, tzinfo=<DstTzInfo
'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>)
In [60]: dst
Out[60]: datetime.datetime(2017, 10, 15, 0, 0, tzinfo=<DstTzInfo
'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>)
In [61]: before
Out[61]: datetime.datetime(2017, 10, 14, 23, 0, tzinfo=<DstTzInfo
'America/Sao_Paulo' BRT-1 day, 21:00:00 STD>)
In [62]: aware_minus
Out[62]: datetime.datetime(2017, 10, 15, 0, 0, tzinfo=<DstTzInfo
'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>)
In [63]: dst == before == aware_minus
Out[63]: True
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27921#comment:4>
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.a3e6f9923fbb76236c89a3a63b003873%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
