gh-84823: Improve doctrings for datetime parsing methods #20677

edison12a · 2020-06-06T13:07:27Z

Issue: Improve doc-strings for datetime.strftime & strptime #84823

taleinat

I have a few comments, but the main thing missing here is also updating the doc-strings of the C versions of these methods.

taleinat · 2020-09-25T19:32:53Z

Lib/datetime.py

@@ -925,7 +925,33 @@ def ctime(self):
            self._day, self._year)

    def strftime(self, fmt):
-        "Format using strftime()."
+        """strftime(fmt) -> date_string


The "input -> output" style of doc-strings is only used in functions and class-methods in this module, but not for normal (instance) methods. I don't see that it adds anything in this case (and the others changed by this PR).

taleinat · 2020-09-25T19:41:21Z

Lib/datetime.py

+        Format codes referring to hours, minutes or seconds will see 0 values.
+
+        Args:
+            format: representation of date_string using format codes.


The argument is named "fmt".

The "Args:" style is different from that currently used in these classes, and adds little in this case with just one argument.

I'm not sure "representation of date_string using format codes" would be clear to someone who hadn't seen this before. It seems to me that an example would be very helpful here.

taleinat · 2020-09-25T19:42:16Z

Lib/datetime.py

+        Returns:
+            date_string: String representation of the date


IMHO these final two lines don't actually add any information.

taleinat · 2020-09-25T19:48:41Z

Lib/datetime.py

+            Commonly used format codes:
+                %Y  Year with century as a decimal number.
+                %m  Month as a decimal number [01,12].
+                %d  Day of the month as a decimal number [01,31].
+                %H  Hour (24-hour clock) as a decimal number [00,23].
+                %M  Minute as a decimal number [00,59].
+                %S  Second as a decimal number [00,61].
+                %z  Time zone offset from UTC.
+                %a  Locale's abbreviated weekday name.
+                %A  Locale's full weekday name.
+                %b  Locale's abbreviated month name.
+                %B  Locale's full month name.
+                %c  Locale's appropriate date and time representation.
+                %I  Hour (12-hour clock) as a decimal number [01,12].
+                %p  Locale's equivalent of either AM or PM.


Copied from time.strftime(), I see. This is very nice!

Perhaps here we should omit the codes referring to hours, minutes and seconds?

Also, where would one find more detailed info and the full list of format codes available? Perhaps consider a reference as to where more detailed information may be found, though I'm not sure what that should be. For time.strftime() we have: "Other codes may be available on your platform. See documentation for the C library strftime function."

bedevere-bot · 2020-09-25T19:49:47Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

taleinat · 2020-09-25T20:02:31Z

Also, since the datetime class currently inherits the strftime() method from the date class, it might be worth adding datetime.strftime() which simply calls the parent class's method, just to override the misleading doc-string.

And I forgot to mention, thanks for working on this, it certainly would have been helpful to me many times, and I'm sure for millions of others as well!

pganssle · 2020-10-20T20:45:17Z

Also, since the datetime class currently inherits the strftime() method from the date class, it might be worth adding datetime.strftime() which simply calls the parent class's method, just to override the misleading doc-string.

I wish there were a way to do this without the additional unnecessary stack frame, but I can't find a good one. ☹

taleinat · 2020-10-21T09:36:52Z

Also, since the datetime class currently inherits the strftime() method from the date class, it might be worth adding datetime.strftime() which simply calls the parent class's method, just to override the misleading doc-string.

I wish there were a way to do this without the additional unnecessary stack frame, but I can't find a good one. frowning_face

I was thinking the exact same thing! But I can't think of a way that wouldn't be a messy hack.

Maybe making __doc__ a property/descriptor?

taleinat · 2020-10-22T09:04:39Z

Maybe making __doc__ a property/descriptor?

Ack, that doesn't seem to be supported on functions/methods :(

taleinat · 2020-10-22T09:06:13Z

I wish there were a way to do this without the additional unnecessary stack frame, but I can't find a good one. frowning_face

Looking at this again, the .strftime() implementation is far from optimized, and the overhead of another method call would be negligible. I'm +1 for wrapping it for better doc-strings.

taleinat · 2020-10-22T09:15:56Z

However, for the datetime class from the _datetime module, which is rather optimized and most often the one used, the doc-string can be overridden without adding an extra function call, by explicitly adding the function to datetime_methods[] with a custom doc-string.

taleinat · 2020-10-22T09:17:12Z

@SimiCode, I realize that several months have passed since you created this PR. Would you be interested and able to follow this up?

…etimemodule Signed-off-by: Tal Einat <[email protected]>

taleinat · 2022-01-20T22:04:36Z

Since it's been over a year and @SimiCode hasn't responded, I've gone ahead and made the changes myself.

I even found a simple way to to get a nice doc-string for datetime.strftime() without an extra stack frame :)

@pganssle, it would be great to get your 👀 on this!

MaxwellDupre

Ran 960 tests in 10.773s
OK (skipped=28)
Looks ok.

ghost · 2022-05-19T01:24:16Z

All commit authors signed the Contributor License Agreement.

pganssle · 2023-04-24T21:05:31Z

Lib/datetime.py

-        Format using strftime().
-
-        Example: "%d/%m/%Y, %H:%M:%S"
+        """Convert to a string in the given format via time.strftime().


I think these aren't supposed to be time.strftime(), I think we want to directly reference :manpage:`strftime(3)`. Or at least strftime(3) (I guess these docstrings aren't destined for Sphinx, so probably just strftime(3) is most appropriate)

pganssle · 2023-04-24T21:06:08Z

Modules/_datetimemodule.c

@@ -3591,7 +3591,21 @@ static PyMethodDef date_methods[] = {
     PyDoc_STR("Return ctime() style string.")},

    {"strftime",        _PyCFunction_CAST(date_strftime),     METH_VARARGS | METH_KEYWORDS,
-     PyDoc_STR("format -> strftime() style string.")},
+     PyDoc_STR(
+         "Convert to a string in the given format via time.strftime().\n\n"


Same here as well.

bedevere-bot · 2023-04-24T21:07:04Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

python-cla-bot · 2025-04-18T09:51:07Z

All commit authors signed the Contributor License Agreement.

improve doctrings for datetime parsing methods

91ebaba

edison12a requested review from abalkin and pganssle as code owners June 6, 2020 13:07

the-knights-who-say-ni added the CLA signed label Jun 6, 2020

bedevere-bot added the awaiting review label Jun 6, 2020

taleinat requested changes Sep 25, 2020

View reviewed changes

bedevere-bot removed the awaiting review label Sep 25, 2020

bedevere-bot added the awaiting changes label Sep 25, 2020

taleinat added docs Documentation in the Doc dir skip news labels Sep 25, 2020

taleinat mentioned this pull request Oct 2, 2020

bpo-40643: Update documentations of strftime function for date, time and datetime. #22477

Closed

eiffel-fl mentioned this pull request Oct 5, 2020

Update documentations of strftime function for date, time and datetime. edison12a/cpython#1

Open

TomAugspurger mentioned this pull request Dec 30, 2020

DOC: TimeStamp.strftime() missing argument description pandas-dev/pandas#36745

Closed

taleinat added 2 commits January 20, 2022 22:03

Merge branch 'main' into bpo-40643

ab411af

further improve doc-strings, add to datetime.datetime and add to _dat…

27f5a98

…etimemodule Signed-off-by: Tal Einat <[email protected]>

taleinat added awaiting review and removed awaiting changes labels Jan 20, 2022

MaxwellDupre approved these changes May 18, 2022

View reviewed changes

Merge branch 'main' into bpo-40643

ad4a503

simicode mannequin mentioned this pull request Apr 10, 2022

Improve doc-strings for datetime.strftime & strptime #84823

Open

ezio-melotti removed the CLA signed label Jul 13, 2022

Merge branch 'main' into bpo-40643

601f012

AlexWaygood changed the title ~~bpo-40643: Improve doctrings for datetime parsing methods~~ gh-84823: Improve doctrings for datetime parsing methods Oct 30, 2022

AlexWaygood removed the docs Documentation in the Doc dir label Oct 30, 2022

pganssle requested changes Apr 24, 2023

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Apr 24, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-84823: Improve doctrings for datetime parsing methods #20677

gh-84823: Improve doctrings for datetime parsing methods #20677

edison12a commented Jun 6, 2020 •

edited by AlexWaygood

Loading

taleinat left a comment

taleinat Sep 25, 2020

taleinat Sep 25, 2020

taleinat Sep 25, 2020

taleinat Sep 25, 2020

bedevere-bot commented Sep 25, 2020

taleinat commented Sep 25, 2020

pganssle commented Oct 20, 2020

taleinat commented Oct 21, 2020 •

edited

Loading

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Jan 20, 2022 •

edited

Loading

MaxwellDupre left a comment

ghost commented May 19, 2022 •

edited by ghost

Loading

pganssle Apr 24, 2023

pganssle Apr 24, 2023

bedevere-bot commented Apr 24, 2023

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading

gh-84823: Improve doctrings for datetime parsing methods #20677

Are you sure you want to change the base?

gh-84823: Improve doctrings for datetime parsing methods #20677

Conversation

edison12a commented Jun 6, 2020 • edited by AlexWaygood Loading

taleinat left a comment

Choose a reason for hiding this comment

taleinat Sep 25, 2020

Choose a reason for hiding this comment

taleinat Sep 25, 2020

Choose a reason for hiding this comment

taleinat Sep 25, 2020

Choose a reason for hiding this comment

taleinat Sep 25, 2020

Choose a reason for hiding this comment

bedevere-bot commented Sep 25, 2020

taleinat commented Sep 25, 2020

pganssle commented Oct 20, 2020

taleinat commented Oct 21, 2020 • edited Loading

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Oct 22, 2020

taleinat commented Jan 20, 2022 • edited Loading

MaxwellDupre left a comment

Choose a reason for hiding this comment

ghost commented May 19, 2022 • edited by ghost Loading

pganssle Apr 24, 2023

Choose a reason for hiding this comment

pganssle Apr 24, 2023

Choose a reason for hiding this comment

bedevere-bot commented Apr 24, 2023

python-cla-bot bot commented Apr 18, 2025 • edited Loading

edison12a commented Jun 6, 2020 •

edited by AlexWaygood

Loading

taleinat commented Oct 21, 2020 •

edited

Loading

taleinat commented Jan 20, 2022 •

edited

Loading

ghost commented May 19, 2022 •

edited by ghost

Loading

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading