Improve docstrings for strptime and strftime methods in datetime module #31761
Conversation
|
Bumping this, would love some feedback on it |
|
It would be better if they were in alphabetical order similar to the man page, to give a comparison, since checking all is not efficient. |
|
All commit authors signed the Contributor License Agreement. |
Now they're in ascending order of duration
|
@MaxwellDupre apologies for the delay. I've made changes similar to the requested ones now. I think it's more logical to order them by duration ascending rather than alphabetically, however, as most people will be looking for the escape sequence from the value rather than the other way round. As such, it's now roughly seconds, minutes, hours, days, months, years. Also added a basic example for the ctime method too, since its documentation wasn't very helpful either. |
| weekday = self.toordinal() % 7 or 7 | ||
| return "%s %s %2d 00:00:00 %04d" % ( | ||
| _DAYNAMES[weekday], | ||
| _MONTHNAMES[self._month], | ||
| self._day, self._year) | ||
|
|
||
| def strftime(self, fmt): | ||
| "Format using strftime()." | ||
| """Format date or datetime given the format string `fmt` |
There was a problem hiding this comment.
I think these changes are overkill for docstrings, and they impose a maintenance burden to keep them up to date. How about just containing a reference to the actual documentation?
There was a problem hiding this comment.
Perhaps a good compromise could be including the most common ones, and then having a link to the remaining ones?
MiguelGuthridge
changed the title
Resolves #97517
I noticed that while using datetime's
strptimeandstrftimemethods that the docstrings were lacking in the sense that I had to refer to the documentation website in order to find the format codes I wanted to use. I've added a list of format codes to all functions in thedatetimemodule where this problem was present, so that they will appear in the inline documentation of IDEs such as VS Code. I believe that this would hugely improve the experience of those writing code using the datetime library, especially if they are unable to remember all 27 format codes.This is my first PR to a major project, so I'd really appreciate any feedback for how I can improve the changes.