bpo-31972: Improve docstrings for pathlib classes #5310
Conversation
The classes that inherit from PurePath do not have docstrings, and therefore inherit the docstrings from PurePath. This is confusing because a developer may assume that Path works similarly to PurePath, which of course it doesn't. This adds a docstring to Path as well as to the other PurePath children that is more indicative of their role.
|
Hello, and thanks for your contribution! I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA). Unfortunately our records indicate you have not signed the CLA. For legal reasons we need you to sign this before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue. Thanks again to your contribution and we look forward to looking at it! |
|
Not sure why this says my CLA is not signed, I have signed it. |
| class PurePosixPath(PurePath): | ||
| """On a POSIX system, instantiating a PurePath should return this object. | ||
| However, you can also instantiate it directly on any system. | ||
| """ |
There was a problem hiding this comment.
Thanks for the patch!
In the stdlib we try to follow the guidelines laid out in PEP 257. Mainly, the first line of a docstring should be a very short description that stands alone, and more information follows after a blank line (this is very similar to the recommendations for git commit messages).
Taking inspiration from the rst docs, here the first line could be something like PurePath subclass for non-Windows systems., followed by a blank line then your original text.
|
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 |
|
Did you put your github username in your bugs.python.org profile? I think that’s what the bot needs to check your CLA status. |
|
I have made the requested changes; please review again |
|
Thanks for making the requested changes! @merwok: please review the changes made to this pull request. |
|
Yes, I added my github username but it was just yesterday that I signed the CLA so I think it just hasn't been updated yet. As for the changes you requested, I've made them. I also updated the existing docstring for class PurePath as it seemed to be within the purview of this bug as well. Let me know if I should leave it the way it was. |
|
@merwok: Please replace |
(cherry picked from commit dfa015c) Co-authored-by: chason <chason@gmail.com>
|
GH-5749 is a backport of this pull request to the 3.6 branch. |
(cherry picked from commit dfa015c) Co-authored-by: chason <chason@gmail.com>
|
GH-5750 is a backport of this pull request to the 3.7 branch. |
5 participants
The classes that inherit from PurePath do not have docstrings,
and therefore inherit the docstrings from PurePath. This is confusing
because a developer may assume that Path works similarly to PurePath,
which of course it doesn't. This adds a docstring to Path as well as
to the other PurePath children that is more indicative of their role.
https://bugs.python.org/issue31972