diff --git a/Lib/pathlib.py b/Lib/pathlib.py index 73dd513b200..8431c29c1d6 100644 --- a/Lib/pathlib.py +++ b/Lib/pathlib.py @@ -584,7 +584,9 @@ class _PathParents(Sequence): 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 @@ os.PathLike.register(PurePath) 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 PureWindowsPath(PurePath): 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 Path(PurePath): 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): diff --git a/Misc/NEWS.d/next/Documentation/2018-01-25-14-23-12.bpo-31972.w1m_8r.rst b/Misc/NEWS.d/next/Documentation/2018-01-25-14-23-12.bpo-31972.w1m_8r.rst new file mode 100644 index 00000000000..e0361df578b --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-01-25-14-23-12.bpo-31972.w1m_8r.rst @@ -0,0 +1 @@ +Improve docstrings for `pathlib.PurePath` subclasses.