The time module defines timezone, altzone, tzname and daylight constants that store information about system timezone.  This information is derived  from the timezone rules that are in effect at the module loading time, but may be incorrect for the times in the past.  The documentation should warn the user about this and recommend using the tm_zone and tm_gmtoff attributes in the result of time.localtime() to obtain timezone information.  See #22799 and msg148208.

We were discussing changing the docstring on the pull request and I had additional questions, so I am moving them here for discussion:

I've been looking at pydoc math and pydoc time (and the the module.c source).

Before I go down the wrong path, I'm not sure I fully understand your comment - "(Also, markup can be improved in the time module docstring. Compare pydoc time and pydoc math.)" The time one is more vebose in the description and it lists the Variables and Functions in the text and then defines them with markup further down. Are you saying the variables and functions should be removed from being written in text within the description?

Thanks.

The time and math modules are probably the oldest Python modules, but math have seen more development recently, so it should serve as a good model for how things should be organized.  Yes, I believe re-listing module functions and constants in the module docstring is redundant and error-prone.

A question for Victor: Should we split the "Constants" section into "Clock ID constants" and "Timezone constants"? (See PR 928.)

IMHO it's worth it to have a dedicated section for CLOCK_xxx constants. It would allow to mention which functions use them.

The datetime module has a separate section for strptime and strftime.  Any interest in splitting those functions into their own section?

Also, back to the original title of saying timezone, altzone, etc are deprecated - there are examples in the datetime docs that use those constants.  Should that be updated to tm_zone and tm_gmtoff?

I think I may need to apologize.  I'm new to this and was looking through the open docs issues and saw this one.  Just now, I noticed that the 'assigned to' was filled in.  I had only been looking at tickets that didn't have a pull request and not looking at the other values.  I am so sorry if I started working on this when I shouldn't have and if I've caused more problems instead of helping.

Cheryl,

There is no need to apologize. I assigned this issue to myself when I created it because I had a few ideas about refactoring the time module documentation and thought I would get to it soon.  As often happens other priorities interfered.

Contributions are welcome regardless of the "Assigned To" status on the issue.  In fact, assigned issues may get a quicker response from the assignee than unassigned ones.

When looking for simple issues to work on, look for an "easy" keyword.  I did not mark this issue as "easy" because I planned to rearrange the module documentation in addition to adding a deprecation note.

> The datetime module ..

Yes, the datetime module documentation can be improved, but let's keep this issue focused on the time module.  Please open a new issue for the datetime module improvements.

New changeset 703ff381ffa946c23e7e25b0ae93a636a2607a40 by Berker Peksag (Cheryl Sabella) in branch 'master':
bpo-28157: Improvements for the time module documentation (GH-928)
https://github.com/python/cpython/commit/703ff381ffa946c23e7e25b0ae93a636a2607a40

New changeset 764969a4b9ed7c6d2adbc04269f9b4fa392a1eed by Berker Peksag (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-28157: Improvements for the time module documentation (GH-928)
https://github.com/python/cpython/commit/764969a4b9ed7c6d2adbc04269f9b4fa392a1eed

This issue can be closed now. Thank you, everyone!