Improve documentation about tzinfo.dst(None)

[dmoisset]

BPO	28386
Nosy	@abalkin, @dmoisset

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-10-07.16:50:32.456>
labels = ['docs']
title = 'Improve documentation about tzinfo.dst(None)'
updated_at = <Date 2016-10-07.17:55:11.099>
user = 'https://github.com/dmoisset'

bugs.python.org fields:

activity = <Date 2016-10-07.17:55:11.099>
actor = 'belopolsky'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-10-07.16:50:32.456>
creator = 'Daniel Moisset'
dependencies = []
files = []
hgrepos = []
issue_num = 28386
keywords = []
message_count = 2.0
messages = ['278256', '278258']
nosy_count = 3.0
nosy_names = ['belopolsky', 'docs@python', 'Daniel Moisset']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue28386'
versions = []

[dmoisset]

The datetime module documentation[1] describes the tzinfo.dst method with a single "dt" argument without being too explicit about possible values for it. The implication is that dt should be a datetime object, but the implementation of time.dst() [2] actually calls tz.dst(None) (where tz is an instance of some tzinfo subclass), so this should clarify that None is an allowed value.

Also, some of the examples given below in the same document (like LocalTimezone, GMT1, GMT2) actually have a related bug (it doesn't handle a None value correctly). So running

>> ... # copy the example from the documentation
>> t = time(tzinfo=LocalTimeZone())
>> t.dst()

crashes with an AttributeError: 'NoneType' object has no attribute 'year'. This kind of bugs have propagated to some other projects already [2]. Some of the other examples (like USTimeZone) seem to be OK

What I think would be desirable here is:

• A clarification on https://docs.python.org/3.5/library/datetime.html#datetime.tzinfo.dst indicating that dt is either a datetime or a None, in which situations it can be None, and what is the method supposed to return in this case.
• Fixes in the code examples that reflect this

I would offer a patch, but I'm not quite sure of what the desired behaviour is so I wouldn't know what to document :)

[1] https://docs.python.org/3.5/library/datetime.html
[2] https://github.com/python/cpython/blob/master/Modules/_datetimemodule.c#L3623
[3] https://github.com/django/django/blob/1.10.2/django/utils/timezone.py#L111

[abalkin]

None is passed to tzinfo.dst() when it is called from time.dst() method. This is documented in the relevant section: <https://docs.python.org/3.5/library/datetime.html#datetime.time.dst\>.

I am not sure whether if it is worth repeating in the abstract tzinfo class documentation, but if we do, the same should be done for the utcoffset() and tzname() methods which also get None when called from namesake time methods.

While we are at it, we should also do something about "If utcoffset() does not return None, dst() should not return None either." mandate in the tzinfo.utcoffset() documentation. See <https://docs.python.org/3.5/library/datetime.html#datetime.tzinfo.utcoffset\>. This mandate is violated by the datetime.timezone class.

[pganssle]

While we are at it, we should also do something about "If utcoffset() does not return None, dst() should not return None either." mandate in the tzinfo.utcoffset() documentation. See <https://docs.python.org/3.5/library/datetime.html#datetime.tzinfo.utcoffset>. This mandate is violated by the datetime.timezone class.

I feel like maybe we should fix the datetime.timezone class, rather than changing the mandate, no?