11.1. — Object-oriented filesystem paths¶

11.1.2.1. 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: unorderable types: PureWindowsPath() < PurePosixPath()

11.1.2.2. Operators¶

The slash operator helps create child paths, similarly to :

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

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 on a path gives the raw filesystem path as a bytes object, as encoded by :

>>> bytes(p)
b'/etc'

11.1.2.3. Accessing individual parts¶

To access the individual “parts” (components) of a path, use the following property:

¶

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)

11.1.2.4. Methods and properties¶

Pure paths provide the following methods and properties:

¶

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'

¶

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
'\\'

¶

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\\'

¶

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:/')

¶

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 so as to resolve symlinks and eliminate ”..” components.

¶

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
''

¶

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
''

¶

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
[]

¶

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'

¶

Return a string representation of the path with forward slashes ():

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

¶

Represent the path as a URI. 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'

¶

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

¶

With , return if the path is considered reserved under Windows, otherwise. With , 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.

*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')

pattern¶

Match this path against the provided glob-style pattern. Return if matching is successful, 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 is observed:

>>> PureWindowsPath('b.py').match('*.PY')
True

*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' does not start with '/usr'

name¶

Return a new path with the 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

suffix¶

Return a new path with the changed. If the original path doesn’t have a suffix, the new suffix is appended instead:

>>> 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')

11.1.3.1. Methods¶

Concrete paths provide the following methods in addition to pure paths methods. Many of these methods can raise an if a system call fails (for example because the path doesn’t exist):

classmethod ¶

Return a new path object representing the current directory (as returned by ):

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

¶

Return information about this path (similarly to ). 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

mode¶

Change the file mode and permissions, like :

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

¶

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, returns whether the symlink points to an existing file or directory.

pattern¶

Glob the given 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.

¶

Return the name of the group owning the file. is raised if the file’s gid isn’t found in the system database.

¶

Return if the path points to a directory (or a symbolic link pointing to a directory), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

Return if the path points to a regular file (or a symbolic link pointing to a regular file), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

Return if the path points to a symbolic link, otherwise.

is also returned if the path doesn’t exist; other errors (such as permission errors) are propagated.

¶

Return if the path points to a Unix socket (or a symbolic link pointing to a Unix socket), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

Return if the path points to a FIFO (or a symbolic link pointing to a FIFO), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

Return if the path points to a block device (or a symbolic link pointing to a block device), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

Return if the path points to a character device (or a symbolic link pointing to a character device), if it points to another kind of file.

is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

¶

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')

mode¶

Like but, if the path points to a symbolic link, the symbolic link’s mode is changed rather than its target’s.

¶

Like but, if the path points to a symbolic link, return the symbolic link’s information rather than its target’s.

mode=0o777, parents=False¶

Create a new directory at this given path. If mode is given, it is combined with the process’ value to determine the file mode and access flags. If the path already exists, 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 command).

If parents is false (the default), a missing parent raises .

mode='r', buffering=-1, encoding=None, errors=None, newline=None¶

Open the file pointed to by the path, like the built-in function does:

>>> p = Path('setup.py')
>>> with p.open() as f:
...  f.readline()
...
'#!/usr/bin/env python3\n'

¶

Return the name of the user owning the file. is raised if the file’s uid isn’t found in the system database.

target¶

Rename this file or directory to the given target. 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)
>>> target.open().read()
'some text'

target¶

Rename this file or directory to the given target. If target points to an existing file or directory, it will be unconditionally replaced.

¶

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, is raised. If an infinite loop is encountered along the resolution path, is raised.

pattern¶

This is like calling with “” added in front of the given pattern:

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

¶

Remove this directory. The directory must be empty.

target, target_is_directory=False¶

Make this path a symbolic link to target. Under Windows, target_is_directory must be true (default ) 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 ‘s.

mode=0o777, exist_ok=True¶

Create a file at this given path. If mode is given, it is combined with the process’ 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 is raised.

¶

Remove this file or symbolic link. If the path points to a directory, use instead.