Improve doc-strings for datetime.strftime & strptime

[simicode]

BPO	40643
Nosy	@pganssle, @nanjekyejoannah, @SimiCode
PRs	gh-84823: Improve doctrings for datetime parsing methods #20677 bpo-40643: Update documentations of strftime function for date, time and datetime. #22477

^{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 = None
closed_at = None
created_at = <Date 2020-05-16.11:29:24.103>
labels = ['type-feature']
title = 'Improve doc-strings for datetime.strftime & strptime'
updated_at = <Date 2020-10-02.12:49:08.249>
user = 'https://github.com/simicode'

bugs.python.org fields:

activity = <Date 2020-10-02.12:49:08.249>
actor = 'python-dev'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2020-05-16.11:29:24.103>
creator = 'edison.abahurire'
dependencies = []
files = []
hgrepos = []
issue_num = 40643
keywords = ['patch']
message_count = 6.0
messages = ['369040', '369048', '369106', '369113', '369125', '370901']
nosy_count = 4.0
nosy_names = ['python-dev', 'p-ganssle', 'nanjekyejoannah', 'edison.abahurire']
pr_nums = ['20677', '22477']
priority = 'low'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue40643'
versions = []

[simicode]

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.

[pganssle]

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

[simicode]

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.

[simicode]

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

[simicode]

Oh! I realized that statement is there because the strftime method used is inherited from the date class.

[simicode]

Update: I opened a PR for this.