homepage

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.

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.

> 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.

Reclassifying this as a doc issue.

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

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

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

@gaurav The pull request 
https://github.com/python/cpython/pull/10870
has been closed in favor of 
https://github.com/python/cpython/pull/15773
which has already been merged.
So we can probably close here.