You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1229 lines
36 KiB
1229 lines
36 KiB
|
|
:mod:`pathlib` --- Object-oriented filesystem paths
|
|
===================================================
|
|
|
|
.. module:: pathlib
|
|
:synopsis: Object-oriented filesystem paths
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
**Source code:** :source:`Lib/pathlib.py`
|
|
|
|
.. index:: single: path; operations
|
|
|
|
--------------
|
|
|
|
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.
|
|
|
|
.. 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.
|
|
|
|
.. seealso::
|
|
:pep:`428`: The pathlib module -- object-oriented filesystem paths.
|
|
|
|
.. seealso::
|
|
For low-level path manipulation on strings, you can also use the
|
|
:mod:`os.path` module.
|
|
|
|
|
|
Basic use
|
|
---------
|
|
|
|
Importing the main class::
|
|
|
|
>>> from pathlib import Path
|
|
|
|
Listing subdirectories::
|
|
|
|
>>> p = Path('.')
|
|
>>> [x for x in p.iterdir() if x.is_dir()]
|
|
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
|
|
PosixPath('__pycache__'), PosixPath('build')]
|
|
|
|
Listing Python source files in this directory tree::
|
|
|
|
>>> list(p.glob('**/*.py'))
|
|
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
|
|
PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
|
|
PosixPath('build/lib/pathlib.py')]
|
|
|
|
Navigating inside a directory tree::
|
|
|
|
>>> p = Path('/etc')
|
|
>>> q = p / 'init.d' / 'reboot'
|
|
>>> q
|
|
PosixPath('/etc/init.d/reboot')
|
|
>>> q.resolve()
|
|
PosixPath('/etc/rc.d/init.d/halt')
|
|
|
|
Querying path properties::
|
|
|
|
>>> q.exists()
|
|
True
|
|
>>> q.is_dir()
|
|
False
|
|
|
|
Opening a file::
|
|
|
|
>>> with q.open() as f: f.readline()
|
|
...
|
|
'#!/bin/bash\n'
|
|
|
|
|
|
.. _pure-paths:
|
|
|
|
Pure paths
|
|
----------
|
|
|
|
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)
|
|
|
|
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 representing a
|
|
path segment, an object implementing the :class:`os.PathLike` interface
|
|
which returns a string, or 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)
|
|
|
|
Pure path objects implement the :class:`os.PathLike` interface, allowing them
|
|
to be used anywhere the interface is accepted.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added support for the :class:`os.PathLike` interface.
|
|
|
|
.. class:: PurePosixPath(*pathsegments)
|
|
|
|
A subclass of :class:`PurePath`, this path flavour represents non-Windows
|
|
filesystem paths::
|
|
|
|
>>> PurePosixPath('/etc')
|
|
PurePosixPath('/etc')
|
|
|
|
*pathsegments* is specified similarly to :class:`PurePath`.
|
|
|
|
.. class:: PureWindowsPath(*pathsegments)
|
|
|
|
A subclass of :class:`PurePath`, this path flavour represents Windows
|
|
filesystem paths::
|
|
|
|
>>> PureWindowsPath('c:/Program Files/')
|
|
PureWindowsPath('c:/Program Files')
|
|
|
|
*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.
|
|
|
|
|
|
General properties
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Paths are immutable and hashable. Paths of a same flavour are comparable
|
|
and orderable. These properties respect the flavour's case-folding
|
|
semantics::
|
|
|
|
>>> PurePosixPath('foo') == PurePosixPath('FOO')
|
|
False
|
|
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
|
|
True
|
|
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
|
|
True
|
|
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
|
|
True
|
|
|
|
Paths of a different flavour compare unequal and cannot be ordered::
|
|
|
|
>>> PureWindowsPath('foo') == PurePosixPath('foo')
|
|
False
|
|
>>> PureWindowsPath('foo') < PurePosixPath('foo')
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'
|
|
|
|
|
|
Operators
|
|
^^^^^^^^^
|
|
|
|
The slash operator helps create child paths, similarly to :func:`os.path.join`::
|
|
|
|
>>> p = PurePath('/etc')
|
|
>>> p
|
|
PurePosixPath('/etc')
|
|
>>> p / 'init.d' / 'apache2'
|
|
PurePosixPath('/etc/init.d/apache2')
|
|
>>> q = PurePath('bin')
|
|
>>> '/usr' / q
|
|
PurePosixPath('/usr/bin')
|
|
|
|
A path object can be used anywhere an object implementing :class:`os.PathLike`
|
|
is accepted::
|
|
|
|
>>> import os
|
|
>>> p = PurePath('/etc')
|
|
>>> os.fspath(p)
|
|
'/etc'
|
|
|
|
The string representation of a path is the raw filesystem path itself
|
|
(in native form, e.g. with backslashes under Windows), which you can
|
|
pass to any function taking a file path as a string::
|
|
|
|
>>> p = PurePath('/etc')
|
|
>>> str(p)
|
|
'/etc'
|
|
>>> p = PureWindowsPath('c:/Program Files')
|
|
>>> str(p)
|
|
'c:\\Program Files'
|
|
|
|
Similarly, calling :class:`bytes` on a path gives the raw filesystem path as a
|
|
bytes object, as encoded by :func:`os.fsencode`::
|
|
|
|
>>> bytes(p)
|
|
b'/etc'
|
|
|
|
.. note::
|
|
Calling :class:`bytes` is only recommended under Unix. Under Windows,
|
|
the unicode form is the canonical representation of filesystem paths.
|
|
|
|
|
|
Accessing individual parts
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To access the individual "parts" (components) of a path, use the following
|
|
property:
|
|
|
|
.. data:: PurePath.parts
|
|
|
|
A tuple giving access to the path's various components::
|
|
|
|
>>> p = PurePath('/usr/bin/python3')
|
|
>>> p.parts
|
|
('/', 'usr', 'bin', 'python3')
|
|
|
|
>>> p = PureWindowsPath('c:/Program Files/PSF')
|
|
>>> p.parts
|
|
('c:\\', 'Program Files', 'PSF')
|
|
|
|
(note how the drive and local root are regrouped in a single part)
|
|
|
|
|
|
Methods and properties
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. testsetup::
|
|
|
|
from pathlib import PurePath, PurePosixPath, PureWindowsPath
|
|
|
|
Pure paths provide the following methods and properties:
|
|
|
|
.. data:: PurePath.drive
|
|
|
|
A string representing the drive letter or name, if any::
|
|
|
|
>>> PureWindowsPath('c:/Program Files/').drive
|
|
'c:'
|
|
>>> PureWindowsPath('/Program Files/').drive
|
|
''
|
|
>>> PurePosixPath('/etc').drive
|
|
''
|
|
|
|
UNC shares are also considered drives::
|
|
|
|
>>> PureWindowsPath('//host/share/foo.txt').drive
|
|
'\\\\host\\share'
|
|
|
|
.. data:: PurePath.root
|
|
|
|
A string representing the (local or global) root, if any::
|
|
|
|
>>> PureWindowsPath('c:/Program Files/').root
|
|
'\\'
|
|
>>> PureWindowsPath('c:Program Files/').root
|
|
''
|
|
>>> PurePosixPath('/etc').root
|
|
'/'
|
|
|
|
UNC shares always have a root::
|
|
|
|
>>> PureWindowsPath('//host/share').root
|
|
'\\'
|
|
|
|
.. data:: PurePath.anchor
|
|
|
|
The concatenation of the drive and root::
|
|
|
|
>>> PureWindowsPath('c:/Program Files/').anchor
|
|
'c:\\'
|
|
>>> PureWindowsPath('c:Program Files/').anchor
|
|
'c:'
|
|
>>> PurePosixPath('/etc').anchor
|
|
'/'
|
|
>>> PureWindowsPath('//host/share').anchor
|
|
'\\\\host\\share\\'
|
|
|
|
|
|
.. data:: PurePath.parents
|
|
|
|
An immutable sequence providing access to the logical ancestors of
|
|
the path::
|
|
|
|
>>> p = PureWindowsPath('c:/foo/bar/setup.py')
|
|
>>> p.parents[0]
|
|
PureWindowsPath('c:/foo/bar')
|
|
>>> p.parents[1]
|
|
PureWindowsPath('c:/foo')
|
|
>>> p.parents[2]
|
|
PureWindowsPath('c:/')
|
|
|
|
|
|
.. data:: PurePath.parent
|
|
|
|
The logical parent of the path::
|
|
|
|
>>> p = PurePosixPath('/a/b/c/d')
|
|
>>> p.parent
|
|
PurePosixPath('/a/b/c')
|
|
|
|
You cannot go past an anchor, or empty path::
|
|
|
|
>>> p = PurePosixPath('/')
|
|
>>> p.parent
|
|
PurePosixPath('/')
|
|
>>> p = PurePosixPath('.')
|
|
>>> p.parent
|
|
PurePosixPath('.')
|
|
|
|
.. note::
|
|
This is a purely lexical operation, hence the following behaviour::
|
|
|
|
>>> p = PurePosixPath('foo/..')
|
|
>>> p.parent
|
|
PurePosixPath('foo')
|
|
|
|
If you want to walk an arbitrary filesystem path upwards, it is
|
|
recommended to first call :meth:`Path.resolve` so as to resolve
|
|
symlinks and eliminate `".."` components.
|
|
|
|
|
|
.. data:: PurePath.name
|
|
|
|
A string representing the final path component, excluding the drive and
|
|
root, if any::
|
|
|
|
>>> PurePosixPath('my/library/setup.py').name
|
|
'setup.py'
|
|
|
|
UNC drive names are not considered::
|
|
|
|
>>> PureWindowsPath('//some/share/setup.py').name
|
|
'setup.py'
|
|
>>> PureWindowsPath('//some/share').name
|
|
''
|
|
|
|
|
|
.. data:: PurePath.suffix
|
|
|
|
The file extension of the final component, if any::
|
|
|
|
>>> PurePosixPath('my/library/setup.py').suffix
|
|
'.py'
|
|
>>> PurePosixPath('my/library.tar.gz').suffix
|
|
'.gz'
|
|
>>> PurePosixPath('my/library').suffix
|
|
''
|
|
|
|
|
|
.. data:: PurePath.suffixes
|
|
|
|
A list of the path's file extensions::
|
|
|
|
>>> PurePosixPath('my/library.tar.gar').suffixes
|
|
['.tar', '.gar']
|
|
>>> PurePosixPath('my/library.tar.gz').suffixes
|
|
['.tar', '.gz']
|
|
>>> PurePosixPath('my/library').suffixes
|
|
[]
|
|
|
|
|
|
.. data:: PurePath.stem
|
|
|
|
The final path component, without its suffix::
|
|
|
|
>>> PurePosixPath('my/library.tar.gz').stem
|
|
'library.tar'
|
|
>>> PurePosixPath('my/library.tar').stem
|
|
'library'
|
|
>>> PurePosixPath('my/library').stem
|
|
'library'
|
|
|
|
|
|
.. method:: PurePath.as_posix()
|
|
|
|
Return a string representation of the path with forward slashes (``/``)::
|
|
|
|
>>> p = PureWindowsPath('c:\\windows')
|
|
>>> str(p)
|
|
'c:\\windows'
|
|
>>> p.as_posix()
|
|
'c:/windows'
|
|
|
|
|
|
.. method:: PurePath.as_uri()
|
|
|
|
Represent the path as a ``file`` URI. :exc:`ValueError` is raised if
|
|
the path isn't absolute.
|
|
|
|
>>> p = PurePosixPath('/etc/passwd')
|
|
>>> p.as_uri()
|
|
'file:///etc/passwd'
|
|
>>> p = PureWindowsPath('c:/Windows')
|
|
>>> p.as_uri()
|
|
'file:///c:/Windows'
|
|
|
|
|
|
.. method:: PurePath.is_absolute()
|
|
|
|
Return whether the path is absolute or not. A path is considered absolute
|
|
if it has both a root and (if the flavour allows) a drive::
|
|
|
|
>>> PurePosixPath('/a/b').is_absolute()
|
|
True
|
|
>>> PurePosixPath('a/b').is_absolute()
|
|
False
|
|
|
|
>>> PureWindowsPath('c:/a/b').is_absolute()
|
|
True
|
|
>>> PureWindowsPath('/a/b').is_absolute()
|
|
False
|
|
>>> PureWindowsPath('c:').is_absolute()
|
|
False
|
|
>>> PureWindowsPath('//some/share').is_absolute()
|
|
True
|
|
|
|
|
|
.. method:: PurePath.is_relative_to(*other)
|
|
|
|
Return whether or not this path is relative to the *other* path.
|
|
|
|
>>> p = PurePath('/etc/passwd')
|
|
>>> p.is_relative_to('/etc')
|
|
True
|
|
>>> p.is_relative_to('/usr')
|
|
False
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
|
|
.. method:: PurePath.is_reserved()
|
|
|
|
With :class:`PureWindowsPath`, return ``True`` if the path is considered
|
|
reserved under Windows, ``False`` otherwise. With :class:`PurePosixPath`,
|
|
``False`` is always returned.
|
|
|
|
>>> PureWindowsPath('nul').is_reserved()
|
|
True
|
|
>>> PurePosixPath('nul').is_reserved()
|
|
False
|
|
|
|
File system calls on reserved paths can fail mysteriously or have
|
|
unintended effects.
|
|
|
|
|
|
.. method:: PurePath.joinpath(*other)
|
|
|
|
Calling this method is equivalent to combining the path with each of
|
|
the *other* arguments in turn::
|
|
|
|
>>> PurePosixPath('/etc').joinpath('passwd')
|
|
PurePosixPath('/etc/passwd')
|
|
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
|
|
PurePosixPath('/etc/passwd')
|
|
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
|
|
PurePosixPath('/etc/init.d/apache2')
|
|
>>> PureWindowsPath('c:').joinpath('/Program Files')
|
|
PureWindowsPath('c:/Program Files')
|
|
|
|
|
|
.. method:: PurePath.match(pattern)
|
|
|
|
Match this path against the provided glob-style pattern. Return ``True``
|
|
if matching is successful, ``False`` otherwise.
|
|
|
|
If *pattern* is relative, the path can be either relative or absolute,
|
|
and matching is done from the right::
|
|
|
|
>>> PurePath('a/b.py').match('*.py')
|
|
True
|
|
>>> PurePath('/a/b/c.py').match('b/*.py')
|
|
True
|
|
>>> PurePath('/a/b/c.py').match('a/*.py')
|
|
False
|
|
|
|
If *pattern* is absolute, the path must be absolute, and the whole path
|
|
must match::
|
|
|
|
>>> PurePath('/a.py').match('/*.py')
|
|
True
|
|
>>> PurePath('a/b.py').match('/*.py')
|
|
False
|
|
|
|
As with other methods, case-sensitivity follows platform defaults::
|
|
|
|
>>> PurePosixPath('b.py').match('*.PY')
|
|
False
|
|
>>> PureWindowsPath('b.py').match('*.PY')
|
|
True
|
|
|
|
|
|
.. method:: PurePath.relative_to(*other)
|
|
|
|
Compute a version of this path relative to the path represented by
|
|
*other*. If it's impossible, ValueError is raised::
|
|
|
|
>>> p = PurePosixPath('/etc/passwd')
|
|
>>> p.relative_to('/')
|
|
PurePosixPath('etc/passwd')
|
|
>>> p.relative_to('/etc')
|
|
PurePosixPath('passwd')
|
|
>>> p.relative_to('/usr')
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
File "pathlib.py", line 694, in relative_to
|
|
.format(str(self), str(formatted)))
|
|
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other absolute.
|
|
|
|
NOTE: This function is part of :class:`PurePath` and works with strings. It does not check or access the underlying file structure.
|
|
|
|
|
|
.. method:: PurePath.with_name(name)
|
|
|
|
Return a new path with the :attr:`name` changed. If the original path
|
|
doesn't have a name, ValueError is raised::
|
|
|
|
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
|
|
>>> p.with_name('setup.py')
|
|
PureWindowsPath('c:/Downloads/setup.py')
|
|
>>> p = PureWindowsPath('c:/')
|
|
>>> p.with_name('setup.py')
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
|
|
raise ValueError("%r has an empty name" % (self,))
|
|
ValueError: PureWindowsPath('c:/') has an empty name
|
|
|
|
|
|
.. method:: PurePath.with_stem(stem)
|
|
|
|
Return a new path with the :attr:`stem` changed. If the original path
|
|
doesn't have a name, ValueError is raised::
|
|
|
|
>>> p = PureWindowsPath('c:/Downloads/draft.txt')
|
|
>>> p.with_stem('final')
|
|
PureWindowsPath('c:/Downloads/final.txt')
|
|
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
|
|
>>> p.with_stem('lib')
|
|
PureWindowsPath('c:/Downloads/lib.gz')
|
|
>>> p = PureWindowsPath('c:/')
|
|
>>> p.with_stem('')
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
|
|
return self.with_name(stem + self.suffix)
|
|
File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
|
|
raise ValueError("%r has an empty name" % (self,))
|
|
ValueError: PureWindowsPath('c:/') has an empty name
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
|
|
.. method:: PurePath.with_suffix(suffix)
|
|
|
|
Return a new path with the :attr:`suffix` changed. If the original path
|
|
doesn't have a suffix, the new *suffix* is appended instead. If the
|
|
*suffix* is an empty string, the original suffix is removed::
|
|
|
|
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
|
|
>>> p.with_suffix('.bz2')
|
|
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
|
|
>>> p = PureWindowsPath('README')
|
|
>>> p.with_suffix('.txt')
|
|
PureWindowsPath('README.txt')
|
|
>>> p = PureWindowsPath('README.txt')
|
|
>>> p.with_suffix('')
|
|
PureWindowsPath('README')
|
|
|
|
|
|
.. _concrete-paths:
|
|
|
|
|
|
Concrete paths
|
|
--------------
|
|
|
|
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(*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
|
|
bugs or failures in your application)::
|
|
|
|
>>> import os
|
|
>>> os.name
|
|
'posix'
|
|
>>> Path('setup.py')
|
|
PosixPath('setup.py')
|
|
>>> PosixPath('setup.py')
|
|
PosixPath('setup.py')
|
|
>>> WindowsPath('setup.py')
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
File "pathlib.py", line 798, in __new__
|
|
% (cls.__name__,))
|
|
NotImplementedError: cannot instantiate 'WindowsPath' on your system
|
|
|
|
|
|
Methods
|
|
^^^^^^^
|
|
|
|
Concrete paths provide the following methods in addition to pure paths
|
|
methods. Many of these methods can raise an :exc:`OSError` if a system
|
|
call fails (for example because the path doesn't exist).
|
|
|
|
.. versionchanged:: 3.8
|
|
|
|
:meth:`~Path.exists()`, :meth:`~Path.is_dir()`, :meth:`~Path.is_file()`,
|
|
:meth:`~Path.is_mount()`, :meth:`~Path.is_symlink()`,
|
|
:meth:`~Path.is_block_device()`, :meth:`~Path.is_char_device()`,
|
|
:meth:`~Path.is_fifo()`, :meth:`~Path.is_socket()` now return ``False``
|
|
instead of raising an exception for paths that contain characters
|
|
unrepresentable at the OS level.
|
|
|
|
|
|
.. classmethod:: Path.cwd()
|
|
|
|
Return a new path object representing the current directory (as returned
|
|
by :func:`os.getcwd`)::
|
|
|
|
>>> Path.cwd()
|
|
PosixPath('/home/antoine/pathlib')
|
|
|
|
|
|
.. classmethod:: Path.home()
|
|
|
|
Return a new path object representing the user's home directory (as
|
|
returned by :func:`os.path.expanduser` with ``~`` construct)::
|
|
|
|
>>> Path.home()
|
|
PosixPath('/home/antoine')
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.stat()
|
|
|
|
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.
|
|
The result is looked up at each call to this method.
|
|
|
|
::
|
|
|
|
>>> p = Path('setup.py')
|
|
>>> p.stat().st_size
|
|
956
|
|
>>> p.stat().st_mtime
|
|
1327883547.852554
|
|
|
|
|
|
.. method:: Path.chmod(mode)
|
|
|
|
Change the file mode and permissions, like :func:`os.chmod`::
|
|
|
|
>>> p = Path('setup.py')
|
|
>>> p.stat().st_mode
|
|
33277
|
|
>>> p.chmod(0o444)
|
|
>>> p.stat().st_mode
|
|
33060
|
|
|
|
|
|
.. method:: Path.exists()
|
|
|
|
Whether the path points to an existing file or directory::
|
|
|
|
>>> Path('.').exists()
|
|
True
|
|
>>> Path('setup.py').exists()
|
|
True
|
|
>>> Path('/etc').exists()
|
|
True
|
|
>>> Path('nonexistentfile').exists()
|
|
False
|
|
|
|
.. note::
|
|
If the path points to a symlink, :meth:`exists` returns whether the
|
|
symlink *points to* an existing file or directory.
|
|
|
|
|
|
.. method:: Path.expanduser()
|
|
|
|
Return a new path with expanded ``~`` and ``~user`` constructs,
|
|
as returned by :meth:`os.path.expanduser`::
|
|
|
|
>>> p = PosixPath('~/films/Monty Python')
|
|
>>> p.expanduser()
|
|
PosixPath('/home/eric/films/Monty Python')
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.glob(pattern)
|
|
|
|
Glob the given relative *pattern* in the directory represented by this path,
|
|
yielding all matching files (of any kind)::
|
|
|
|
>>> sorted(Path('.').glob('*.py'))
|
|
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
|
|
>>> sorted(Path('.').glob('*/*.py'))
|
|
[PosixPath('docs/conf.py')]
|
|
|
|
The "``**``" pattern means "this directory and all subdirectories,
|
|
recursively". In other words, it enables recursive globbing::
|
|
|
|
>>> sorted(Path('.').glob('**/*.py'))
|
|
[PosixPath('build/lib/pathlib.py'),
|
|
PosixPath('docs/conf.py'),
|
|
PosixPath('pathlib.py'),
|
|
PosixPath('setup.py'),
|
|
PosixPath('test_pathlib.py')]
|
|
|
|
.. note::
|
|
Using the "``**``" pattern in large directory trees may consume
|
|
an inordinate amount of time.
|
|
|
|
.. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
|
|
|
|
|
|
.. method:: Path.group()
|
|
|
|
Return the name of the group owning the file. :exc:`KeyError` is raised
|
|
if the file's gid isn't found in the system database.
|
|
|
|
|
|
.. method:: Path.is_dir()
|
|
|
|
Return ``True`` if the path points to a directory (or a symbolic link
|
|
pointing to a directory), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_file()
|
|
|
|
Return ``True`` if the path points to a regular file (or a symbolic link
|
|
pointing to a regular file), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_mount()
|
|
|
|
Return ``True`` if the path is a :dfn:`mount point`: a point in a
|
|
file system where a different file system has been mounted. On POSIX, the
|
|
function checks whether *path*'s parent, :file:`path/..`, is on a different
|
|
device than *path*, or whether :file:`path/..` and *path* point to the same
|
|
i-node on the same device --- this should detect mount points for all Unix
|
|
and POSIX variants. Not implemented on Windows.
|
|
|
|
.. versionadded:: 3.7
|
|
|
|
|
|
.. method:: Path.is_symlink()
|
|
|
|
Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
|
|
|
|
``False`` is also returned if the path doesn't exist; other errors (such
|
|
as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_socket()
|
|
|
|
Return ``True`` if the path points to a Unix socket (or a symbolic link
|
|
pointing to a Unix socket), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_fifo()
|
|
|
|
Return ``True`` if the path points to a FIFO (or a symbolic link
|
|
pointing to a FIFO), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_block_device()
|
|
|
|
Return ``True`` if the path points to a block device (or a symbolic link
|
|
pointing to a block device), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.is_char_device()
|
|
|
|
Return ``True`` if the path points to a character device (or a symbolic link
|
|
pointing to a character device), ``False`` if it points to another kind of file.
|
|
|
|
``False`` is also returned if the path doesn't exist or is a broken symlink;
|
|
other errors (such as permission errors) are propagated.
|
|
|
|
|
|
.. method:: Path.iterdir()
|
|
|
|
When the path points to a directory, yield path objects of the directory
|
|
contents::
|
|
|
|
>>> p = Path('docs')
|
|
>>> for child in p.iterdir(): child
|
|
...
|
|
PosixPath('docs/conf.py')
|
|
PosixPath('docs/_templates')
|
|
PosixPath('docs/make.bat')
|
|
PosixPath('docs/index.rst')
|
|
PosixPath('docs/_build')
|
|
PosixPath('docs/_static')
|
|
PosixPath('docs/Makefile')
|
|
|
|
The children are yielded in arbitrary order, and the special entries
|
|
``'.'`` and ``'..'`` are not included. If a file is removed from or added
|
|
to the directory after creating the iterator, whether an path object for
|
|
that file be included is unspecified.
|
|
|
|
.. method:: Path.lchmod(mode)
|
|
|
|
Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
|
|
symbolic link's mode is changed rather than its target's.
|
|
|
|
|
|
.. method:: Path.lstat()
|
|
|
|
Like :meth:`Path.stat` but, if the path points to a symbolic link, return
|
|
the symbolic link's information rather than its target's.
|
|
|
|
|
|
.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False)
|
|
|
|
Create a new directory at this given path. If *mode* is given, it is
|
|
combined with the process' ``umask`` value to determine the file mode
|
|
and access flags. If the path already exists, :exc:`FileExistsError`
|
|
is raised.
|
|
|
|
If *parents* is true, any missing parents of this path are created
|
|
as needed; they are created with the default permissions without taking
|
|
*mode* into account (mimicking the POSIX ``mkdir -p`` command).
|
|
|
|
If *parents* is false (the default), a missing parent raises
|
|
:exc:`FileNotFoundError`.
|
|
|
|
If *exist_ok* is false (the default), :exc:`FileExistsError` is
|
|
raised if the target directory already exists.
|
|
|
|
If *exist_ok* is true, :exc:`FileExistsError` exceptions will be
|
|
ignored (same behavior as the POSIX ``mkdir -p`` command), but only if the
|
|
last path component is not an existing non-directory file.
|
|
|
|
.. versionchanged:: 3.5
|
|
The *exist_ok* parameter was added.
|
|
|
|
|
|
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
|
|
|
|
Open the file pointed to by the path, like the built-in :func:`open`
|
|
function does::
|
|
|
|
>>> p = Path('setup.py')
|
|
>>> with p.open() as f:
|
|
... f.readline()
|
|
...
|
|
'#!/usr/bin/env python3\n'
|
|
|
|
|
|
.. method:: Path.owner()
|
|
|
|
Return the name of the user owning the file. :exc:`KeyError` is raised
|
|
if the file's uid isn't found in the system database.
|
|
|
|
|
|
.. method:: Path.read_bytes()
|
|
|
|
Return the binary contents of the pointed-to file as a bytes object::
|
|
|
|
>>> p = Path('my_binary_file')
|
|
>>> p.write_bytes(b'Binary file contents')
|
|
20
|
|
>>> p.read_bytes()
|
|
b'Binary file contents'
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.read_text(encoding=None, errors=None)
|
|
|
|
Return the decoded contents of the pointed-to file as a string::
|
|
|
|
>>> p = Path('my_text_file')
|
|
>>> p.write_text('Text file contents')
|
|
18
|
|
>>> p.read_text()
|
|
'Text file contents'
|
|
|
|
The file is opened and then closed. The optional parameters have the same
|
|
meaning as in :func:`open`.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.readlink()
|
|
|
|
Return the path to which the symbolic link points (as returned by
|
|
:func:`os.readlink`)::
|
|
|
|
>>> p = Path('mylink')
|
|
>>> p.symlink_to('setup.py')
|
|
>>> p.readlink()
|
|
PosixPath('setup.py')
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
|
|
.. method:: Path.rename(target)
|
|
|
|
Rename this file or directory to the given *target*, and return a new Path
|
|
instance pointing to *target*. On Unix, if *target* exists and is a file,
|
|
it will be replaced silently if the user has permission. *target* can be
|
|
either a string or another path object::
|
|
|
|
>>> p = Path('foo')
|
|
>>> p.open('w').write('some text')
|
|
9
|
|
>>> target = Path('bar')
|
|
>>> p.rename(target)
|
|
PosixPath('bar')
|
|
>>> target.open().read()
|
|
'some text'
|
|
|
|
The target path may be absolute or relative. Relative paths are interpreted
|
|
relative to the current working directory, *not* the directory of the Path
|
|
object.
|
|
|
|
.. versionchanged:: 3.8
|
|
Added return value, return the new Path instance.
|
|
|
|
|
|
.. method:: Path.replace(target)
|
|
|
|
Rename this file or directory to the given *target*, and return a new Path
|
|
instance pointing to *target*. If *target* points to an existing file or
|
|
directory, it will be unconditionally replaced.
|
|
|
|
The target path may be absolute or relative. Relative paths are interpreted
|
|
relative to the current working directory, *not* the directory of the Path
|
|
object.
|
|
|
|
.. versionchanged:: 3.8
|
|
Added return value, return the new Path instance.
|
|
|
|
|
|
.. method:: Path.resolve(strict=False)
|
|
|
|
Make the path absolute, resolving any symlinks. A new path object is
|
|
returned::
|
|
|
|
>>> p = Path()
|
|
>>> p
|
|
PosixPath('.')
|
|
>>> p.resolve()
|
|
PosixPath('/home/antoine/pathlib')
|
|
|
|
"``..``" components are also eliminated (this is the only method to do so)::
|
|
|
|
>>> p = Path('docs/../setup.py')
|
|
>>> p.resolve()
|
|
PosixPath('/home/antoine/pathlib/setup.py')
|
|
|
|
If the path doesn't exist and *strict* is ``True``, :exc:`FileNotFoundError`
|
|
is raised. If *strict* is ``False``, the path is resolved as far as possible
|
|
and any remainder is appended without checking whether it exists. If an
|
|
infinite loop is encountered along the resolution path, :exc:`RuntimeError`
|
|
is raised.
|
|
|
|
.. versionadded:: 3.6
|
|
The *strict* argument (pre-3.6 behavior is strict).
|
|
|
|
.. method:: Path.rglob(pattern)
|
|
|
|
This is like calling :func:`Path.glob` with "``**/``" added in front of the
|
|
given relative *pattern*::
|
|
|
|
>>> sorted(Path().rglob("*.py"))
|
|
[PosixPath('build/lib/pathlib.py'),
|
|
PosixPath('docs/conf.py'),
|
|
PosixPath('pathlib.py'),
|
|
PosixPath('setup.py'),
|
|
PosixPath('test_pathlib.py')]
|
|
|
|
.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob
|
|
|
|
|
|
.. method:: Path.rmdir()
|
|
|
|
Remove this directory. The directory must be empty.
|
|
|
|
|
|
.. method:: Path.samefile(other_path)
|
|
|
|
Return whether this path points to the same file as *other_path*, which
|
|
can be either a Path object, or a string. The semantics are similar
|
|
to :func:`os.path.samefile` and :func:`os.path.samestat`.
|
|
|
|
An :exc:`OSError` can be raised if either file cannot be accessed for some
|
|
reason.
|
|
|
|
::
|
|
|
|
>>> p = Path('spam')
|
|
>>> q = Path('eggs')
|
|
>>> p.samefile(q)
|
|
False
|
|
>>> p.samefile('spam')
|
|
True
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.symlink_to(target, target_is_directory=False)
|
|
|
|
Make this path a symbolic link to *target*. Under Windows,
|
|
*target_is_directory* must be true (default ``False``) if the link's target
|
|
is a directory. Under POSIX, *target_is_directory*'s value is ignored.
|
|
|
|
::
|
|
|
|
>>> p = Path('mylink')
|
|
>>> p.symlink_to('setup.py')
|
|
>>> p.resolve()
|
|
PosixPath('/home/antoine/pathlib/setup.py')
|
|
>>> p.stat().st_size
|
|
956
|
|
>>> p.lstat().st_size
|
|
8
|
|
|
|
.. note::
|
|
The order of arguments (link, target) is the reverse
|
|
of :func:`os.symlink`'s.
|
|
|
|
|
|
.. method:: Path.touch(mode=0o666, exist_ok=True)
|
|
|
|
Create a file at this given path. If *mode* is given, it is combined
|
|
with the process' ``umask`` value to determine the file mode and access
|
|
flags. If the file already exists, the function succeeds if *exist_ok*
|
|
is true (and its modification time is updated to the current time),
|
|
otherwise :exc:`FileExistsError` is raised.
|
|
|
|
|
|
.. method:: Path.unlink(missing_ok=False)
|
|
|
|
Remove this file or symbolic link. If the path points to a directory,
|
|
use :func:`Path.rmdir` instead.
|
|
|
|
If *missing_ok* is false (the default), :exc:`FileNotFoundError` is
|
|
raised if the path does not exist.
|
|
|
|
If *missing_ok* is true, :exc:`FileNotFoundError` exceptions will be
|
|
ignored (same behavior as the POSIX ``rm -f`` command).
|
|
|
|
.. versionchanged:: 3.8
|
|
The *missing_ok* parameter was added.
|
|
|
|
|
|
.. method:: Path.link_to(target)
|
|
|
|
Create a hard link pointing to a path named *target*.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
|
|
.. method:: Path.write_bytes(data)
|
|
|
|
Open the file pointed to in bytes mode, write *data* to it, and close the
|
|
file::
|
|
|
|
>>> p = Path('my_binary_file')
|
|
>>> p.write_bytes(b'Binary file contents')
|
|
20
|
|
>>> p.read_bytes()
|
|
b'Binary file contents'
|
|
|
|
An existing file of the same name is overwritten.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. method:: Path.write_text(data, encoding=None, errors=None)
|
|
|
|
Open the file pointed to in text mode, write *data* to it, and close the
|
|
file::
|
|
|
|
>>> p = Path('my_text_file')
|
|
>>> p.write_text('Text file contents')
|
|
18
|
|
>>> p.read_text()
|
|
'Text file contents'
|
|
|
|
An existing file of the same name is overwritten. The optional parameters
|
|
have the same meaning as in :func:`open`.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
Correspondence to tools in the :mod:`os` module
|
|
-----------------------------------------------
|
|
|
|
Below is a table mapping various :mod:`os` functions to their corresponding
|
|
:class:`PurePath`/:class:`Path` equivalent.
|
|
|
|
.. note::
|
|
|
|
Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some
|
|
overlapping use-cases, their semantics differ enough to warrant not
|
|
considering them equivalent.
|
|
|
|
==================================== ==============================
|
|
os and os.path pathlib
|
|
==================================== ==============================
|
|
:func:`os.path.abspath` :meth:`Path.resolve`
|
|
:func:`os.chmod` :meth:`Path.chmod`
|
|
:func:`os.mkdir` :meth:`Path.mkdir`
|
|
:func:`os.makedirs` :meth:`Path.mkdir`
|
|
:func:`os.rename` :meth:`Path.rename`
|
|
:func:`os.replace` :meth:`Path.replace`
|
|
:func:`os.rmdir` :meth:`Path.rmdir`
|
|
:func:`os.remove`, :func:`os.unlink` :meth:`Path.unlink`
|
|
:func:`os.getcwd` :func:`Path.cwd`
|
|
:func:`os.path.exists` :meth:`Path.exists`
|
|
:func:`os.path.expanduser` :meth:`Path.expanduser` and
|
|
:meth:`Path.home`
|
|
:func:`os.listdir` :meth:`Path.iterdir`
|
|
:func:`os.path.isdir` :meth:`Path.is_dir`
|
|
:func:`os.path.isfile` :meth:`Path.is_file`
|
|
:func:`os.path.islink` :meth:`Path.is_symlink`
|
|
:func:`os.link` :meth:`Path.link_to`
|
|
:func:`os.symlink` :meth:`Path.symlink_to`
|
|
:func:`os.readlink` :meth:`Path.readlink`
|
|
:func:`os.stat` :meth:`Path.stat`,
|
|
:meth:`Path.owner`,
|
|
:meth:`Path.group`
|
|
:func:`os.path.isabs` :meth:`PurePath.is_absolute`
|
|
:func:`os.path.join` :func:`PurePath.joinpath`
|
|
:func:`os.path.basename` :data:`PurePath.name`
|
|
:func:`os.path.dirname` :data:`PurePath.parent`
|
|
:func:`os.path.samefile` :meth:`Path.samefile`
|
|
:func:`os.path.splitext` :data:`PurePath.suffix`
|
|
==================================== ==============================
|