classification
Title: Improve doc-strings for datetime.strftime & strptime
Type: enhancement Stage: patch review
Components: Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: edison.abahurire, nanjekyejoannah, p-ganssle, python-dev
Priority: low Keywords: patch

Created on 2020-05-16 11:29 by edison.abahurire, last changed 2020-06-07 14:23 by edison.abahurire.

Pull Requests
URL Status Linked Edit
PR 20677 open python-dev, 2020-06-06 13:07
Messages (6)
msg369040 - (view) Author: Edison Abahurire (edison.abahurire) * Date: 2020-05-16 11:29
The docstring for strftime is:
    ```def strftime(self, fmt):
        "Format using strftime()."
    ```

And that of strptime:
    ````def strptime(cls, date_string, format):
        'string, format -> new datetime parsed from a string (like time.strptime()).'
    ````

I feel like both could use a better explanation for users who will access them using >>> help(datetime.strftime) and users using IDEs that provide doc-strings on-hover over a function.
msg369048 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2020-05-16 14:25
I agree, this can be improved (particularly the first one). I believe we'll need to change it in the C implementation as well as the pure python version.

That said, the most useful thing for users would be a full formatting reference, which is too much to put in the docstring (and to maintain in at least 3 different places). I'm not sure *how* much better it can get, but at least the first one reads like a terrible self-referential dictionary entry "recyclist (n). a proponent of recyclism". At the very least it should disambiguate between `datetime.strftime`, `time.strftime` and `stftime(3)`.
msg369106 - (view) Author: Edison Abahurire (edison.abahurire) * Date: 2020-05-17 08:54
Thanks for the review @p-ganssle. 
I'll request that you assign it to me, counting on your guidance while changing it in the C implementation.
msg369113 - (view) Author: Edison Abahurire (edison.abahurire) * Date: 2020-05-17 11:12
Hi, An enquiry here: 
    On the web documentation of strftime (https://docs.python.org/3/library/datetime.html?highlight=strftime#datetime.time.strftime), 

What does this mean? 
    "Format codes referring to hours, minutes or seconds will see 0 values."
msg369125 - (view) Author: Edison Abahurire (edison.abahurire) * Date: 2020-05-17 15:06
Oh! I realized that statement is there because the strftime method used is inherited from the date class.
msg370901 - (view) Author: Edison Abahurire (edison.abahurire) * Date: 2020-06-07 14:23
Update: I opened a PR for this.
History
Date User Action Args
2020-06-07 14:23:57edison.abahuriresetmessages: + msg370901
2020-06-06 13:07:28python-devsetkeywords: + patch
nosy: + python-dev

pull_requests: + pull_request19892
stage: needs patch -> patch review
2020-05-17 15:06:39edison.abahuriresetmessages: + msg369125
2020-05-17 11:12:28edison.abahuriresetmessages: + msg369113
2020-05-17 08:54:19edison.abahuriresetmessages: + msg369106
2020-05-16 14:25:04p-gansslesetpriority: normal -> low

nosy: + p-ganssle
messages: + msg369048

type: enhancement
stage: needs patch
2020-05-16 11:29:24edison.abahurirecreate