classification
Title: Inherited docstrings for pathlib classes are confusing
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: chason.chaffin, docs@python, eric.araujo, miss-islington, pitrou
Priority: normal Keywords: easy, patch

Created on 2017-11-07 19:05 by eric.araujo, last changed 2018-02-19 01:01 by eric.araujo. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 5310 merged chason.chaffin, 2018-01-25 05:14
PR 5749 merged miss-islington, 2018-02-18 23:37
PR 5750 merged miss-islington, 2018-02-18 23:40
Messages (5)
msg305788 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-11-07 19:05
pydoc pathlib.Path shows the docstring of PurePath:

 |  PurePath represents a filesystem path and offers operations which
 |  don't imply any actual filesystem I/O.

But immediately after we see methods like chmod, exists and co which obviously aren’t pure.  Looking at the reST docs or the source code, the reader can deduce that this is the docstring of PurePath inherited by Path, but I find it confusing.

Solution: adding docstrings to all pathlib classes.  PurePath and Path can have all the info, Posix/Windows* subclasses only one line with a reference.
msg312332 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2018-02-18 23:36
New changeset dfa015cf77a148d229ddc0a5b063562c9f9664f2 by Éric Araujo (chason) in branch 'master':
bpo-31972: Improve docstrings for pathlib classes (#5310)
https://github.com/python/cpython/commit/dfa015cf77a148d229ddc0a5b063562c9f9664f2
msg312334 - (view) Author: miss-islington (miss-islington) Date: 2018-02-19 00:37
New changeset 5c81ed49412e41a671283cdb4c297dab52f5b7c5 by Miss Islington (bot) in branch '3.6':
bpo-31972: Improve docstrings for pathlib classes (GH-5310)
https://github.com/python/cpython/commit/5c81ed49412e41a671283cdb4c297dab52f5b7c5
msg312335 - (view) Author: miss-islington (miss-islington) Date: 2018-02-19 00:48
New changeset 19b7f6694af56a1c9fdc0f1f9fc09ae48439ab4c by Miss Islington (bot) in branch '3.7':
bpo-31972: Improve docstrings for pathlib classes (GH-5310)
https://github.com/python/cpython/commit/19b7f6694af56a1c9fdc0f1f9fc09ae48439ab4c
msg312336 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2018-02-19 01:01
Thanks for the patch!
History
Date User Action Args
2018-02-19 01:01:16eric.araujosetmessages: + msg312336
2018-02-19 01:00:42eric.araujosetstatus: open -> closed
assignee: docs@python -> eric.araujo
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.8
2018-02-19 00:48:09miss-islingtonsetmessages: + msg312335
2018-02-19 00:37:02miss-islingtonsetnosy: + miss-islington
messages: + msg312334
2018-02-18 23:40:26miss-islingtonsetpull_requests: + pull_request5524
2018-02-18 23:37:39miss-islingtonsetpull_requests: + pull_request5523
2018-02-18 23:36:34eric.araujosetmessages: + msg312332
2018-01-26 02:01:36chason.chaffinsetnosy: + chason.chaffin
2018-01-25 05:14:55chason.chaffinsetpull_requests: + pull_request5157
2017-12-07 08:18:39serhiy.storchakasetpull_requests: - pull_request4645
2017-12-07 02:40:30pablogsalsetpull_requests: + pull_request4645
2017-12-07 02:37:30eric.araujosetpull_requests: - pull_request4644
2017-12-07 02:05:36pablogsalsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request4644
2017-11-08 09:32:03serhiy.storchakasetnosy: + docs@python, pitrou

components: + Documentation
assignee: docs@python
2017-11-07 19:05:43eric.araujocreate