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?
There was a problem hiding this comment.
Are there any examples of functions (preferably in datetime) that contain pointers to their documentation? Or is it just assumed that people know how to look it up?
I'm not crazy about trying to decide what common codes would be.
You should probably reach out to the module maintainer for more input on this. I'm just an interested bystander. @pganssle @abalkin: Any thoughts?
There was a problem hiding this comment.
Having the full documentation be available inline would be the optimal solution, but I'd settle for a quick link - as long as there's something to help avoid the frustrating web search and scroll through the massive amount of online documentation. It could be interesting to look into generating documentation from docstrings and the like (using a tool like pdoc) so that there would be as much difficulty in terms of keeping documentation up-to-date in multiple places, but I'd say that's well beyond the scope of this particular PR.
MaddyGuthridge
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.