Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b6e66eb

Browse files
elibeneliben
committed
Some minor clarifications in the documentation of pathlib + inheritance diagram
1 parent 8148164 commit b6e66eb

2 files changed

Lines changed: 80 additions & 68 deletions

File tree

‎Doc/library/pathlib-inheritance.png‎

11 KB
Loading

‎Doc/library/pathlib.rst‎

Lines changed: 80 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,27 @@
99

1010
.. versionadded:: 3.4
1111

12-
1312
This module offers classes representing filesystem paths with semantics
1413
appropriate for different operating systems. Path classes are divided
1514
between :ref:`pure paths <pure-paths>`, which provide purely computational
1615
operations without I/O, and :ref:`concrete paths <concrete-paths>`, which
1716
inherit from pure paths but also provide I/O operations.
1817

19-
The main point of entry is the :class:`Path` class, which will instantiate
20-
a :ref:`concrete path <concrete-paths>` for the current platform.
18+
.. image:: pathlib-inheritance.png
19+
:align: center
20+
21+
If you've never used this module before or just aren't sure which class is
22+
right for your task, :class:`Path` is most likely what you need. It instantiates
23+
a :ref:`concrete path <concrete-paths>` for the platform the code is running on.
24+
25+
Pure paths are useful in some special cases; for example:
26+
27+
#. If you want to manipulate Windows paths on a Unix machine (or vice versa).
28+
You cannot instantiate a :class:`WindowsPath` when running on Unix, but you
29+
can instantiate :class:`PureWindowsPath`.
30+
#. You want to make sure that your code only manipulates paths without actually
31+
accessing the OS. In this case, instantiating one of the pure classes may be
32+
useful since those simply don't have any OS-accessing operations.
2133

2234
.. note::
2335
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
8698
access a filesystem. There are three ways to access these classes, which
8799
we also call *flavours*:
88100

101+
.. class:: PurePath(*pathsegments)
89102

90-
.. class:: PurePosixPath
91-
92-
A subclass of :class:`PurePath`, this path flavour represents non-Windows
93-
filesystem paths::
94-
95-
>>> PurePosixPath('/etc')
96-
PurePosixPath('/etc')
103+
A generic class that represents the system's path flavour (instantiating
104+
it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
97105

98-
.. class:: PureWindowsPath
106+
>>> PurePath('setup.py') # Running on a Unix machine
107+
PurePosixPath('setup.py')
99108

100-
A subclass of :class:`PurePath`, this path flavour represents Windows
101-
filesystem paths::
109+
Each element of *pathsegments* can be either a string or bytes object
110+
representing a path segment; it can also be another path object::
102111

103-
>>> PureWindowsPath('c:/Program Files/')
104-
PureWindowsPath('c:/Program Files')
112+
>>> PurePath('foo', 'some/path', 'bar')
113+
PurePosixPath('foo/some/path/bar')
114+
>>> PurePath(Path('foo'), Path('bar'))
115+
PurePosixPath('foo/bar')
105116

106-
.. class:: PurePath
117+
When *pathsegments* is empty, the current directory is assumed::
107118

108-
A generic class that represents the system's path flavour (instantiating
109-
it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
119+
>>> PurePath()
120+
PurePosixPath('.')
110121

111-
>>> PurePath('setup.py')
112-
PurePosixPath('setup.py')
122+
When several absolute paths are given, the last is taken as an anchor
123+
(mimicking :func:`os.path.join`'s behaviour)::
113124

125+
>>> PurePath('/etc', '/usr', 'lib64')
126+
PurePosixPath('/usr/lib64')
127+
>>> PureWindowsPath('c:/Windows', 'd:bar')
128+
PureWindowsPath('d:bar')
114129

115-
Regardless of the system you're running on, you can instantiate all of
116-
these classes, since they don't provide any operation that does system calls.
130+
However, in a Windows path, changing the local root doesn't discard the
131+
previous drive setting::
117132

133+
>>> PureWindowsPath('c:/Windows', '/Program Files')
134+
PureWindowsPath('c:/Program Files')
118135

119-
Constructing paths
120-
^^^^^^^^^^^^^^^^^^
136+
Spurious slashes and single dots are collapsed, but double dots (``'..'``)
137+
are not, since this would change the meaning of a path in the face of
138+
symbolic links::
121139

122-
Path constructors accept an arbitrary number of positional arguments.
123-
When called without any argument, a path object points to the current
124-
directory::
140+
>>> PurePath('foo//bar')
141+
PurePosixPath('foo/bar')
142+
>>> PurePath('foo/./bar')
143+
PurePosixPath('foo/bar')
144+
>>> PurePath('foo/../bar')
145+
PurePosixPath('foo/../bar')
125146

126-
>>> PurePath()
127-
PurePosixPath('.')
147+
(a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent
148+
to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
149+
to another directory)
128150

129-
Any argument can be a string or bytes object representing an arbitrary number
130-
of path segments, but it can also be another path object::
151+
.. class:: PurePosixPath(*pathsegments)
131152

132-
>>> PurePath('foo', 'some/path', 'bar')
133-
PurePosixPath('foo/some/path/bar')
134-
>>> PurePath(Path('foo'), Path('bar'))
135-
PurePosixPath('foo/bar')
153+
A subclass of :class:`PurePath`, this path flavour represents non-Windows
154+
filesystem paths::
136155

137-
When several absolute paths are given, the last is taken as an anchor
138-
(mimicking :func:`os.path.join`'s behaviour)::
156+
>>> PurePosixPath('/etc')
157+
PurePosixPath('/etc')
139158

140-
>>> PurePath('/etc', '/usr', 'lib64')
141-
PurePosixPath('/usr/lib64')
142-
>>> PureWindowsPath('c:/Windows', 'd:bar')
143-
PureWindowsPath('d:bar')
159+
*pathsegments* is specified similarly to :class:`PurePath`.
144160

145-
However, in a Windows path, changing the local root doesn't discard the
146-
previous drive setting::
161+
.. class:: PureWindowsPath(*pathsegments)
147162

148-
>>> PureWindowsPath('c:/Windows', '/Program Files')
149-
PureWindowsPath('c:/Program Files')
163+
A subclass of :class:`PurePath`, this path flavour represents Windows
164+
filesystem paths::
150165

151-
Spurious slashes and single dots are collapsed, but double dots (``'..'``)
152-
are not, since this would change the meaning of a path in the face of
153-
symbolic links::
166+
>>> PureWindowsPath('c:/Program Files/')
167+
PureWindowsPath('c:/Program Files')
154168

155-
>>> PurePath('foo//bar')
156-
PurePosixPath('foo/bar')
157-
>>> PurePath('foo/./bar')
158-
PurePosixPath('foo/bar')
159-
>>> PurePath('foo/../bar')
160-
PurePosixPath('foo/../bar')
169+
*pathsegments* is specified similarly to :class:`PurePath`.
161170

162-
(a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent
163-
to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
164-
to another directory)
171+
Regardless of the system you're running on, you can instantiate all of
172+
these classes, since they don't provide any operation that does system calls.
165173

166174

167175
General properties
@@ -524,32 +532,36 @@ Concrete paths are subclasses of the pure path classes. In addition to
524532
operations provided by the latter, they also provide methods to do system
525533
calls on path objects. There are three ways to instantiate concrete paths:
526534

535+
.. class:: Path(*pathsegments)
536+
537+
A subclass of :class:`PurePath`, this class represents concrete paths of
538+
the system's path flavour (instantiating it creates either a
539+
:class:`PosixPath` or a :class:`WindowsPath`)::
540+
541+
>>> Path('setup.py')
542+
PosixPath('setup.py')
543+
544+
*pathsegments* is specified similarly to :class:`PurePath`.
527545

528-
.. class:: PosixPath
546+
.. class:: PosixPath(*pathsegments)
529547

530548
A subclass of :class:`Path` and :class:`PurePosixPath`, this class
531549
represents concrete non-Windows filesystem paths::
532550

533551
>>> PosixPath('/etc')
534552
PosixPath('/etc')
535553

536-
.. class:: WindowsPath
554+
*pathsegments* is specified similarly to :class:`PurePath`.
555+
556+
.. class:: WindowsPath(*pathsegments)
537557

538558
A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
539559
represents concrete Windows filesystem paths::
540560

541561
>>> WindowsPath('c:/Program Files/')
542562
WindowsPath('c:/Program Files')
543563

544-
.. class:: Path
545-
546-
A subclass of :class:`PurePath`, this class represents concrete paths of
547-
the system's path flavour (instantiating it creates either a
548-
:class:`PosixPath` or a :class:`WindowsPath`)::
549-
550-
>>> Path('setup.py')
551-
PosixPath('setup.py')
552-
564+
*pathsegments* is specified similarly to :class:`PurePath`.
553565

554566
You can only instantiate the class flavour that corresponds to your system
555567
(allowing system calls on non-compatible path flavours could lead to

0 commit comments

Comments
 (0)