Title: Document time module constants (timezone, tzname, etc.) as deprecated.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: belopolsky Nosy List: belopolsky, berker.peksag, cheryl.sabella, mark.dickinson, vstinner
Priority: normal Keywords: patch

Created on 2016-09-14 19:17 by belopolsky, last changed 2017-10-11 13:51 by berker.peksag. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 928 merged cheryl.sabella, 2017-03-31 15:39
PR 915 cheryl.sabella, 2017-04-01 20:00
PR 3953 merged python-dev, 2017-10-11 13:30
Messages (13)
msg276478 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2016-09-14 19:17
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.
msg290945 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-03-31 22:53
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?

msg290946 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-03-31 22:59
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.
msg290947 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-03-31 23:11
A question for Victor: Should we split the "Constants" section into "Clock ID constants" and "Timezone constants"? (See PR 928.)
msg290950 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-03-31 23:30
IMHO it's worth it to have a dedicated section for CLOCK_xxx constants. It would allow to mention which functions use them.
msg290974 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-04-01 09:37
The datetime module has a separate section for strptime and strftime.  Any interest in splitting those functions into their own section?
msg290975 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-04-01 09:41
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?
msg290983 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-04-01 12:31
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.
msg290999 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-04-01 17:28

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.
msg291000 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-04-01 17:32
> 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.
msg304133 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-11 13:29
New changeset 703ff381ffa946c23e7e25b0ae93a636a2607a40 by Berker Peksag (Cheryl Sabella) in branch 'master':
bpo-28157: Improvements for the time module documentation (GH-928)
msg304137 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-11 13:50
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)
msg304138 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-11 13:51
This issue can be closed now. Thank you, everyone!
Date User Action Args
2017-10-11 13:51:47berker.peksagsetstatus: open -> closed
type: enhancement
messages: + msg304138

resolution: fixed
stage: patch review -> resolved
2017-10-11 13:50:24berker.peksagsetmessages: + msg304137
2017-10-11 13:30:34python-devsetkeywords: + patch
pull_requests: + pull_request3928
2017-10-11 13:29:16berker.peksagsetnosy: + berker.peksag
messages: + msg304133
2017-04-01 20:00:38cheryl.sabellasetpull_requests: + pull_request1134
2017-04-01 17:34:38belopolskysetkeywords: - 3.2regression
2017-04-01 17:32:41belopolskysetmessages: + msg291000
2017-04-01 17:28:27belopolskysetkeywords: + 3.2regression

messages: + msg290999
2017-04-01 12:31:19cheryl.sabellasetmessages: + msg290983
2017-04-01 09:41:17cheryl.sabellasetmessages: + msg290975
2017-04-01 09:37:30cheryl.sabellasetmessages: + msg290974
2017-03-31 23:30:56vstinnersetmessages: + msg290950
2017-03-31 23:11:11belopolskysetmessages: + msg290947
2017-03-31 22:59:13belopolskysetnosy: + mark.dickinson, vstinner
messages: + msg290946
2017-03-31 22:53:42cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg290945
2017-03-31 17:02:48Mariattasetstage: needs patch -> patch review
versions: + Python 3.7
2017-03-31 15:39:01cheryl.sabellasetpull_requests: + pull_request825
2016-09-15 22:58:42belopolskylinkissue15941 superseder
2016-09-14 19:17:21belopolskylinkissue22799 superseder
2016-09-14 19:17:06belopolskycreate