datetime.utctimetuple() should not set tm_isdst flag to 0

[abalkin]

BPO	9004
Nosy	@malemburg, @abalkin, @pitrou, @merwok, @karlcow, @hobbestigrou, @pganssle
PRs	bpo-9004: Recommend against using utctimetuple in the docs. #10870 bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773
Files	timetuple_issue9004.patch

^{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 = 'https://github.com/abalkin'
closed_at = None
created_at = <Date 2010-06-16.03:36:41.910>
labels = ['easy', 'type-bug', 'docs']
title = 'datetime.utctimetuple() should not set tm_isdst flag to 0'
updated_at = <Date 2019-10-03.09:54:22.605>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2019-10-03.09:54:22.605>
actor = 'karlcow'
assignee = 'belopolsky'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2010-06-16.03:36:41.910>
creator = 'belopolsky'
dependencies = []
files = ['46050']
hgrepos = []
issue_num = 9004
keywords = ['patch', 'easy']
message_count = 8.0
messages = ['107906', '108278', '162633', '221894', '284072', '330963', '330969', '353837']
nosy_count = 8.0
nosy_names = ['lemburg', 'belopolsky', 'pitrou', 'eric.araujo', 'karlcow', 'hobbestigrou', 'p-ganssle', 'Gaurav Tatke']
pr_nums = ['10870', '15773']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue9004'
versions = ['Python 3.6']

[abalkin]

I find the following quite misleading:

>>> from datetime import datetime
>>> import time
>>> time.strftime('%c %z %Z', datetime.utcnow().utctimetuple())
'Wed Jun 16 03:26:26 2010 -0500 EST'

As far as I can tell, the only other function that uses the tm_isdst flag is time.mktime, but it expect a timetuple containing local time, not UTC time.

[abalkin]

With timezone.utc available in datetime module, users should be encouraged to use dt.astimezone(timezone.utc).timetuple() instead of dt.utctimetuple(). Note that the later will set tm_isdst to -1. This observation can be used to argue for either of two ways to resolve this issue:

1. Since utctimetuple() is no longer necessary, and the alternative works correctly, there is no need to fix it. Just recommend the astimezone use in the docs and explain the subtle difference.

2. Having two ways to do the same thing which have a subtle difference is not a good idea.

I am leaning towards #1, but would like to hear from others.

[merwok]

Just recommend the astimezone use in the docs
and recommend creating tz-aware instances in the first time (i.e. calling now(utc) instead of utcnow()), +1.

[abalkin]

Reclassifying this as a doc issue.

[GauravTatke]

Hi,
I am new to python and would like to contribute. I find this issue easy so changed the documentation of datetime module. I tested it with sphinx. Attaching a patch.

Please let me know if it is correct or needs changes.
Appreciate it!

Regards,
Gaurav

[hobbestigrou]

Please can you convert your patch to a pull request on github.

[abalkin]

I submitted Gaurav's patch as PR 10870. Please review.

[karlcow]

@gaurav The pull request
#10870
has been closed in favor of
#15773
which has already been merged.

So we can probably close here.