bpo-31972: Improve docstrings for pathlib classes (GH-5310)
(cherry picked from commit dfa015cf77a148d229ddc0a5b063562c9f9664f2)
Co-authored-by: chason <chason@gmail.com>
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 73dd513..8431c29 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -584,7 +584,9 @@
class PurePath(object):
- """PurePath represents a filesystem path and offers operations which
+ """Base class for manipulating paths without I/O.
+
+ PurePath represents a filesystem path and offers operations which
don't imply any actual filesystem I/O. Depending on your system,
instantiating a PurePath will return either a PurePosixPath or a
PureWindowsPath object. You can also instantiate either of these classes
@@ -939,11 +941,21 @@
class PurePosixPath(PurePath):
+ """PurePath subclass for non-Windows systems.
+
+ On a POSIX system, instantiating a PurePath should return this object.
+ However, you can also instantiate it directly on any system.
+ """
_flavour = _posix_flavour
__slots__ = ()
class PureWindowsPath(PurePath):
+ """PurePath subclass for Windows systems.
+
+ On a Windows system, instantiating a PurePath should return this object.
+ However, you can also instantiate it directly on any system.
+ """
_flavour = _windows_flavour
__slots__ = ()
@@ -952,6 +964,14 @@
class Path(PurePath):
+ """PurePath subclass that can make system calls.
+
+ Path represents a filesystem path but unlike PurePath, also offers
+ methods to do system calls on path objects. Depending on your system,
+ instantiating a Path will return either a PosixPath or a WindowsPath
+ object. You can also instantiate a PosixPath or WindowsPath directly,
+ but cannot instantiate a WindowsPath on a POSIX system or vice versa.
+ """
__slots__ = (
'_accessor',
'_closed',
@@ -1427,9 +1447,17 @@
class PosixPath(Path, PurePosixPath):
+ """Path subclass for non-Windows systems.
+
+ On a POSIX system, instantiating a Path should return this object.
+ """
__slots__ = ()
class WindowsPath(Path, PureWindowsPath):
+ """Path subclass for Windows systems.
+
+ On a Windows system, instantiating a Path should return this object.
+ """
__slots__ = ()
def owner(self):