Some minor clarifications in the documentation of pathlib + inheritance diagram

1 files changed, 80 insertions, 68 deletions

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index d4e0862..a8c1dc9 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -9,15 +9,27 @@
 
 .. versionadded:: 3.4
 
-
 This module offers classes representing filesystem paths with semantics
 appropriate for different operating systems.  Path classes are divided
 between :ref:`pure paths <pure-paths>`, which provide purely computational
 operations without I/O, and :ref:`concrete paths <concrete-paths>`, which
 inherit from pure paths but also provide I/O operations.
 
-The main point of entry is the :class:`Path` class, which will instantiate
-a :ref:`concrete path <concrete-paths>` for the current platform.
+.. image:: pathlib-inheritance.png
+   :align: center
+
+If you've never used this module before or just aren't sure which class is
+right for your task, :class:`Path` is most likely what you need. It instantiates
+a :ref:`concrete path <concrete-paths>` for the platform the code is running on.
+
+Pure paths are useful in some special cases; for example:
+
+#. If you want to manipulate Windows paths on a Unix machine (or vice versa).
+   You cannot instantiate a :class:`WindowsPath` when running on Unix, but you
+   can instantiate :class:`PureWindowsPath`.
+#. You want to make sure that your code only manipulates paths without actually
+   accessing the OS. In this case, instantiating one of the pure classes may be
+   useful since those simply don't have any OS-accessing operations.
 
 .. note::
    This module has been included in the standard library on a
@@ -86,82 +98,78 @@ Pure path objects provide path-handling operations which don't actually
 access a filesystem.  There are three ways to access these classes, which
 we also call *flavours*:
 
+.. class:: PurePath(*pathsegments)
 
-.. class:: PurePosixPath
-
-   A subclass of :class:`PurePath`, this path flavour represents non-Windows
-   filesystem paths::
-
-      >>> PurePosixPath('/etc')
-      PurePosixPath('/etc')
+   A generic class that represents the system's path flavour (instantiating
+   it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
 
-.. class:: PureWindowsPath
+      >>> PurePath('setup.py')      # Running on a Unix machine
+      PurePosixPath('setup.py')
 
-   A subclass of :class:`PurePath`, this path flavour represents Windows
-   filesystem paths::
+   Each element of *pathsegments* can be either a string or bytes object
+   representing a path segment; it can also be another path object::
 
-      >>> PureWindowsPath('c:/Program Files/')
-      PureWindowsPath('c:/Program Files')
+      >>> PurePath('foo', 'some/path', 'bar')
+      PurePosixPath('foo/some/path/bar')
+      >>> PurePath(Path('foo'), Path('bar'))
+      PurePosixPath('foo/bar')
 
-.. class:: PurePath
+   When *pathsegments* is empty, the current directory is assumed::
 
-   A generic class that represents the system's path flavour (instantiating
-   it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
+      >>> PurePath()
+      PurePosixPath('.')
 
-      >>> PurePath('setup.py')
-      PurePosixPath('setup.py')
+   When several absolute paths are given, the last is taken as an anchor
+   (mimicking :func:`os.path.join`'s behaviour)::
 
+      >>> PurePath('/etc', '/usr', 'lib64')
+      PurePosixPath('/usr/lib64')
+      >>> PureWindowsPath('c:/Windows', 'd:bar')
+      PureWindowsPath('d:bar')
 
-Regardless of the system you're running on, you can instantiate all of
-these classes, since they don't provide any operation that does system calls.
+   However, in a Windows path, changing the local root doesn't discard the
+   previous drive setting::
 
+      >>> PureWindowsPath('c:/Windows', '/Program Files')
+      PureWindowsPath('c:/Program Files')
 
-Constructing paths
-^^^^^^^^^^^^^^^^^^
+   Spurious slashes and single dots are collapsed, but double dots (``'..'``)
+   are not, since this would change the meaning of a path in the face of
+   symbolic links::
 
-Path constructors accept an arbitrary number of positional arguments.
-When called without any argument, a path object points to the current
-directory::
+      >>> PurePath('foo//bar')
+      PurePosixPath('foo/bar')
+      >>> PurePath('foo/./bar')
+      PurePosixPath('foo/bar')
+      >>> PurePath('foo/../bar')
+      PurePosixPath('foo/../bar')
 
-   >>> PurePath()
-   PurePosixPath('.')
+   (a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent
+   to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
+   to another directory)
 
-Any argument can be a string or bytes object representing an arbitrary number
-of path segments, but it can also be another path object::
+.. class:: PurePosixPath(*pathsegments)
 
-   >>> PurePath('foo', 'some/path', 'bar')
-   PurePosixPath('foo/some/path/bar')
-   >>> PurePath(Path('foo'), Path('bar'))
-   PurePosixPath('foo/bar')
+   A subclass of :class:`PurePath`, this path flavour represents non-Windows
+   filesystem paths::
 
-When several absolute paths are given, the last is taken as an anchor
-(mimicking :func:`os.path.join`'s behaviour)::
+      >>> PurePosixPath('/etc')
+      PurePosixPath('/etc')
 
-   >>> PurePath('/etc', '/usr', 'lib64')
-   PurePosixPath('/usr/lib64')
-   >>> PureWindowsPath('c:/Windows', 'd:bar')
-   PureWindowsPath('d:bar')
+   *pathsegments* is specified similarly to :class:`PurePath`.
 
-However, in a Windows path, changing the local root doesn't discard the
-previous drive setting::
+.. class:: PureWindowsPath(*pathsegments)
 
-   >>> PureWindowsPath('c:/Windows', '/Program Files')
-   PureWindowsPath('c:/Program Files')
+   A subclass of :class:`PurePath`, this path flavour represents Windows
+   filesystem paths::
 
-Spurious slashes and single dots are collapsed, but double dots (``'..'``)
-are not, since this would change the meaning of a path in the face of
-symbolic links::
+      >>> PureWindowsPath('c:/Program Files/')
+      PureWindowsPath('c:/Program Files')
 
-   >>> PurePath('foo//bar')
-   PurePosixPath('foo/bar')
-   >>> PurePath('foo/./bar')
-   PurePosixPath('foo/bar')
-   >>> PurePath('foo/../bar')
-   PurePosixPath('foo/../bar')
+   *pathsegments* is specified similarly to :class:`PurePath`.
 
-(a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent
-to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
-to another directory)
+Regardless of the system you're running on, you can instantiate all of
+these classes, since they don't provide any operation that does system calls.
 
 
 General properties
@@ -524,8 +532,18 @@ Concrete paths are subclasses of the pure path classes.  In addition to
 operations provided by the latter, they also provide methods to do system
 calls on path objects.  There are three ways to instantiate concrete paths:
 
+.. class:: Path(*pathsegments)
+
+   A subclass of :class:`PurePath`, this class represents concrete paths of
+   the system's path flavour (instantiating it creates either a
+   :class:`PosixPath` or a :class:`WindowsPath`)::
+
+      >>> Path('setup.py')
+      PosixPath('setup.py')
+
+   *pathsegments* is specified similarly to :class:`PurePath`.
 
-.. class:: PosixPath
+.. class:: PosixPath(*pathsegments)
 
    A subclass of :class:`Path` and :class:`PurePosixPath`, this class
    represents concrete non-Windows filesystem paths::
@@ -533,7 +551,9 @@ calls on path objects.  There are three ways to instantiate concrete paths:
       >>> PosixPath('/etc')
       PosixPath('/etc')
 
-.. class:: WindowsPath
+   *pathsegments* is specified similarly to :class:`PurePath`.
+
+.. class:: WindowsPath(*pathsegments)
 
    A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
    represents concrete Windows filesystem paths::
@@ -541,15 +561,7 @@ calls on path objects.  There are three ways to instantiate concrete paths:
       >>> WindowsPath('c:/Program Files/')
       WindowsPath('c:/Program Files')
 
-.. class:: Path
-
-   A subclass of :class:`PurePath`, this class represents concrete paths of
-   the system's path flavour (instantiating it creates either a
-   :class:`PosixPath` or a :class:`WindowsPath`)::
-
-      >>> Path('setup.py')
-      PosixPath('setup.py')
-
+   *pathsegments* is specified similarly to :class:`PurePath`.
 
 You can only instantiate the class flavour that corresponds to your system
 (allowing system calls on non-compatible path flavours could lead to