[Python-checkins] bpo-31972: Improve docstrings for pathlib classes (#5310)

[Éric Araujo]

https://github.com/python/cpython/commit/dfa015cf77a148d229ddc0a5b063562c9f9664f2
commit: dfa015cf77a148d229ddc0a5b063562c9f9664f2
branch: master
author: chason <chason at gmail.com>
committer: Éric Araujo <merwok at netwok.org>
date: 2018-02-18T18:36:32-05:00
summary:

bpo-31972: Improve docstrings for pathlib classes (#5310)

files:
A Misc/NEWS.d/next/Documentation/2018-01-25-14-23-12.bpo-31972.w1m_8r.rst
M Lib/pathlib.py

diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 73dd513b200e..8431c29c1d65 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -584,7 +584,9 @@ def __repr__(self):
 
 
 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 @@ def match(self, path_pattern):
 
 
 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 @@ def expanduser(self):
 
 
 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 000000000000..e0361df578b3
--- /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.