gh-97517: Improve docstrings for strptime and strftime methods in datetime module#31761
gh-97517: Improve docstrings for strptime and strftime methods in datetime module#31761MaddyGuthridge wants to merge 5 commits intopython:mainfrom
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. |
MaxwellDupre
left a comment
MaxwellDupre
left a comment
There was a problem hiding this comment.
Better. No need to apologise, everyone works on this when they have time.
|
|
||
| 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.
There was a problem hiding this comment.
Links are not done anywhere in the docs from what I can tell. Below are all instances of a link to the docs in cpython.
iOS/testbed/iOSTestbedTests/iOSTestbedTests.m: // See https://docs.python.org/3/library/os.html#python-utf-8-mode.
InternalDocs/garbage_collector.md:[`gc.get_threshold()`](https://docs.python.org/3/library/gc.html#gc.get_threshold)
InternalDocs/parser.md: [`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError) is".
InternalDocs/parser.md:[`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError)
InternalDocs/parser.md:> [`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError)
InternalDocs/changing_grammar.md: [`pyclbr`](https://docs.python.org/3/library/pyclbr.html#module-pyclbr).
Tools/c-analyzer/c_parser/preprocessor/common.py: # See: https://docs.python.org/3/library/sys.html#sys.platform
Lib/asyncio/coroutines.py: # See: https://docs.python.org/3/library/asyncio-dev.html#asyncio-debug-mode.
Lib/multiprocessing/spawn.py: section in https://docs.python.org/3/library/multiprocessing.html
grep: Lib/multiprocessing/__pycache__/spawn.cpython-314.pyc: binary file matches
Lib/importlib/_bootstrap.py: # See # https://docs.python.org/3/library/importlib.html#importlib.abc.Loader.load_module
Lib/test/test_unittest/test_discovery.py: # https://docs.python.org/3/library/unittest.html#load-tests-protocol
Lib/idlelib/run.py: "https://docs.python.org/3/library/idle.html#startup-failure",
Lib/idlelib/pyshell.py: "https://docs.python.org/3/library/idle.html#startup-failure",
Lib/venv/__init__.py: 'see https://docs.python.org/3/library/venv.html\n')
There was a problem hiding this comment.
Right, we're generally not including URLs to the specific version of the docs that's hosted on docs.python.org.
I think this should use a sentence like “See the documentation for a list of format codes”.
We can't include a full list, since that's platform-specific and there's no portable API to get such a list.
We could include the portable codes, but as said already, repeating them 3 times isn't very maintainable.
MaddyGuthridge
changed the title
encukou
changed the title
|
Thanks for your contribution, however, this has been superseded by #138559. |
10 participants
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.