http://hg.python.org/cpython/rev/90b56ec318b6 changeset: 87629:90b56ec318b6 parent: 87627:2b2925c08a6c user: Eli Bendersky <eliben@gmail.com> date: Thu Nov 28 06:53:05 2013 -0800 summary: Some minor clarifications in the documentation of pathlib + inheritance diagram files: Doc/library/pathlib-inheritance.png | Bin Doc/library/pathlib.rst | 170 ++++++++------- 2 files changed, 91 insertions(+), 79 deletions(-) diff --git a/Doc/library/pathlib-inheritance.png b/Doc/library/pathlib-inheritance.png new file mode 100644 index 0000000000000000000000000000000000000000..b81c3deb6049d83051337776fe5c4f3de751e1cb GIT binary patch [stripped] diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst --- 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,8 +98,57 @@ access a filesystem. There are three ways to access these classes, which we also call *flavours*: +.. class:: PurePath(*pathsegments) -.. class:: PurePosixPath + A generic class that represents the system's path flavour (instantiating + it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`):: + + >>> PurePath('setup.py') # Running on a Unix machine + PurePosixPath('setup.py') + + Each element of *pathsegments* can be either a string or bytes object + representing a path segment; it can also be another path object:: + + >>> PurePath('foo', 'some/path', 'bar') + PurePosixPath('foo/some/path/bar') + >>> PurePath(Path('foo'), Path('bar')) + PurePosixPath('foo/bar') + + When *pathsegments* is empty, the current directory is assumed:: + + >>> PurePath() + PurePosixPath('.') + + 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') + + 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') + + 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:: + + >>> PurePath('foo//bar') + PurePosixPath('foo/bar') + >>> PurePath('foo/./bar') + PurePosixPath('foo/bar') + >>> PurePath('foo/../bar') + PurePosixPath('foo/../bar') + + (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) + +.. class:: PurePosixPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents non-Windows filesystem paths:: @@ -95,7 +156,9 @@ >>> PurePosixPath('/etc') PurePosixPath('/etc') -.. class:: PureWindowsPath + *pathsegments* is specified similarly to :class:`PurePath`. + +.. class:: PureWindowsPath(*pathsegments) A subclass of :class:`PurePath`, this path flavour represents Windows filesystem paths:: @@ -103,67 +166,12 @@ >>> PureWindowsPath('c:/Program Files/') PureWindowsPath('c:/Program Files') -.. class:: PurePath - - A generic class that represents the system's path flavour (instantiating - it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`):: - - >>> PurePath('setup.py') - PurePosixPath('setup.py') - + *pathsegments* is specified similarly to :class:`PurePath`. 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. -Constructing paths -^^^^^^^^^^^^^^^^^^ - -Path constructors accept an arbitrary number of positional arguments. -When called without any argument, a path object points to the current -directory:: - - >>> PurePath() - PurePosixPath('.') - -Any argument can be a string or bytes object representing an arbitrary number -of path segments, but it can also be another path object:: - - >>> PurePath('foo', 'some/path', 'bar') - PurePosixPath('foo/some/path/bar') - >>> PurePath(Path('foo'), Path('bar')) - PurePosixPath('foo/bar') - -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') - -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') - -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:: - - >>> PurePath('foo//bar') - PurePosixPath('foo/bar') - >>> PurePath('foo/./bar') - PurePosixPath('foo/bar') - >>> PurePath('foo/../bar') - PurePosixPath('foo/../bar') - -(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) - - General properties ^^^^^^^^^^^^^^^^^^ @@ -524,24 +532,7 @@ 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:: PosixPath - - A subclass of :class:`Path` and :class:`PurePosixPath`, this class - represents concrete non-Windows filesystem paths:: - - >>> PosixPath('/etc') - PosixPath('/etc') - -.. class:: WindowsPath - - A subclass of :class:`Path` and :class:`PureWindowsPath`, this class - represents concrete Windows filesystem paths:: - - >>> WindowsPath('c:/Program Files/') - WindowsPath('c:/Program Files') - -.. class:: Path +.. class:: Path(*pathsegments) A subclass of :class:`PurePath`, this class represents concrete paths of the system's path flavour (instantiating it creates either a @@ -550,6 +541,27 @@ >>> Path('setup.py') PosixPath('setup.py') + *pathsegments* is specified similarly to :class:`PurePath`. + +.. class:: PosixPath(*pathsegments) + + A subclass of :class:`Path` and :class:`PurePosixPath`, this class + represents concrete non-Windows filesystem paths:: + + >>> PosixPath('/etc') + PosixPath('/etc') + + *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:: + + >>> WindowsPath('c:/Program Files/') + WindowsPath('c:/Program Files') + + *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 -- Repository URL: http://hg.python.org/cpython