[New-bugs-announce] [issue31972] Inherited docstrings for pathlib classes are confusing

[Éric Araujo]

New submission from Éric Araujo <merwok at netwok.org>:

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.

----------
components: Library (Lib)
keywords: easy
messages: 305788
nosy: eric.araujo
priority: normal
severity: normal
stage: needs patch
status: open
title: Inherited docstrings for pathlib classes are confusing
type: enhancement
versions: Python 3.6, Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue31972>
_______________________________________