General properties¶

Paths are immutable and hashable. Paths of a same flavour are comparableand orderable. These properties respect the flavour’s case-foldingsemantics:

>>>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>", line1, in<module>TypeError:'<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

Operators¶

The slash operator helps create child paths, similarly toos.path.join():

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

A path object can be used anywhere an object implementingos.PathLikeis accepted:

>>>importos>>>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 canpass 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, callingbytes on a path gives the raw filesystem path as abytes object, as encoded byos.fsencode():

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

Accessing individual parts¶

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

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¶

Pure paths provide the following methods and properties:

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'

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

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

PurePath.parents¶

An immutable sequence providing access to the logical ancestors ofthe 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:/')

PurePath.parent¶

The logical parent of the path:

>>>p=PurePosixPath('/a/b/c/d')>>>p.parentPurePosixPath('/a/b/c')

You cannot go past an anchor, or empty path:

>>>p=PurePosixPath('/')>>>p.parentPurePosixPath('/')>>>p=PurePosixPath('.')>>>p.parentPurePosixPath('.')

Note

This is a purely lexical operation, hence the following behaviour:

>>>p=PurePosixPath('foo/..')>>>p.parentPurePosixPath('foo')

If you want to walk an arbitrary filesystem path upwards, it isrecommended to first callPath.resolve() so as to resolvesymlinks and eliminate“..” components.

PurePath.name¶

A string representing the final path component, excluding the drive androot, 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''

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

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

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'

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'

PurePath.as_uri()¶

Represent the path as afile URI.ValueError is raised ifthe path isn’t absolute.

>>>p=PurePosixPath('/etc/passwd')>>>p.as_uri()'file:///etc/passwd'>>>p=PureWindowsPath('c:/Windows')>>>p.as_uri()'file:///c:/Windows'

PurePath.is_absolute()¶

Return whether the path is absolute or not. A path is considered absoluteif 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

PurePath.is_relative_to(*other)¶

Return whether or not this path is relative to theother path.

>>>p=PurePath('/etc/passwd')>>>p.is_relative_to('/etc')True>>>p.is_relative_to('/usr')False

New in version 3.9.

PurePath.is_reserved()¶

WithPureWindowsPath, returnTrue if the path is consideredreserved under Windows,False otherwise. WithPurePosixPath,False is always returned.

>>>PureWindowsPath('nul').is_reserved()True>>>PurePosixPath('nul').is_reserved()False

File system calls on reserved paths can fail mysteriously or haveunintended effects.

PurePath.joinpath(*other)¶

Calling this method is equivalent to combining the path with each oftheother 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')

PurePath.match(pattern)¶

Match this path against the provided glob-style pattern. ReturnTrueif matching is successful,False otherwise.

Ifpattern 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

Ifpattern is absolute, the path must be absolute, and the whole pathmust 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

PurePath.relative_to(*other)¶

Compute a version of this path relative to the path represented byother. 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>", line1, in<module>  File"pathlib.py", line694, inrelative_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 ofPurePath and works with strings. It does not check or access the underlying file structure.

PurePath.with_name(name)¶

Return a new path with thename changed. If the original pathdoesn’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>", line1, in<module>  File"/home/antoine/cpython/default/Lib/pathlib.py", line751, inwith_nameraiseValueError("%r has an empty name"%(self,))ValueError:PureWindowsPath('c:/') has an empty name

PurePath.with_stem(stem)¶

Return a new path with thestem changed. If the original pathdoesn’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>", line1, in<module>  File"/home/antoine/cpython/default/Lib/pathlib.py", line861, inwith_stemreturnself.with_name(stem+self.suffix)  File"/home/antoine/cpython/default/Lib/pathlib.py", line851, inwith_nameraiseValueError("%r has an empty name"%(self,))ValueError:PureWindowsPath('c:/') has an empty name

New in version 3.9.

PurePath.with_suffix(suffix)¶

Return a new path with thesuffix changed. If the original pathdoesn’t have a suffix, the newsuffix is appended instead. If thesuffix 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')

Methods¶

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

classmethodPath.cwd()¶

Return a new path object representing the current directory (as returnedbyos.getcwd()):

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

classmethodPath.home()¶

Return a new path object representing the user’s home directory (asreturned byos.path.expanduser() with~ construct):

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

Note that unlikeos.path.expanduser(), on POSIX systems aKeyError orRuntimeError will be raised, and on Windows systems aRuntimeError will be raised if home directory can’t be resolved.

New in version 3.5.

Path.stat()¶

Return aos.stat_result object containing information about this path, likeos.stat().The result is looked up at each call to this method.

>>>p=Path('setup.py')>>>p.stat().st_size956>>>p.stat().st_mtime1327883547.852554

Path.chmod(mode)¶

Change the file mode and permissions, likeos.chmod():

>>>p=Path('setup.py')>>>p.stat().st_mode33277>>>p.chmod(0o444)>>>p.stat().st_mode33060

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,exists() returns whether thesymlinkpoints to an existing file or directory.

Path.expanduser()¶

Return a new path with expanded~ and~user constructs,as returned byos.path.expanduser():

>>>p=PosixPath('~/films/Monty Python')>>>p.expanduser()PosixPath('/home/eric/films/Monty Python')

Note that unlikeos.path.expanduser(), on POSIX systems aKeyError orRuntimeError will be raised, and on Windows systems aRuntimeError will be raised if home directory can’t be resolved.

New in version 3.5.

Path.glob(pattern)¶

Glob the given relativepattern 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 consumean inordinate amount of time.

Raises anauditing eventpathlib.Path.glob with argumentsself,pattern.

Path.group()¶

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

Path.is_dir()¶

ReturnTrue if the path points to a directory (or a symbolic linkpointing 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.

Path.is_file()¶

ReturnTrue if the path points to a regular file (or a symbolic linkpointing 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.

Path.is_mount()¶

ReturnTrue if the path is amount point: a point in afile system where a different file system has been mounted. On POSIX, thefunction checks whetherpath’s parent,path/.., is on a differentdevice thanpath, or whetherpath/.. andpath point to the samei-node on the same device — this should detect mount points for all Unixand POSIX variants. Not implemented on Windows.

New in version 3.7.

Path.is_symlink()¶

ReturnTrue if the path points to a symbolic link,False otherwise.

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

Path.is_socket()¶

ReturnTrue if the path points to a Unix socket (or a symbolic linkpointing 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.

Path.is_fifo()¶

ReturnTrue if the path points to a FIFO (or a symbolic linkpointing 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.

Path.is_block_device()¶

ReturnTrue if the path points to a block device (or a symbolic linkpointing 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.

Path.is_char_device()¶

ReturnTrue if the path points to a character device (or a symbolic linkpointing 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.

Path.iterdir()¶

When the path points to a directory, yield path objects of the directorycontents:

>>>p=Path('docs')>>>forchildinp.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 addedto the directory after creating the iterator, whether a path object forthat file be included is unspecified.

Path.lchmod(mode)¶

LikePath.chmod() but, if the path points to a symbolic link, thesymbolic link’s mode is changed rather than its target’s.

Path.lstat()¶

LikePath.stat() but, if the path points to a symbolic link, returnthe symbolic link’s information rather than its target’s.

Path.mkdir(mode=0o777,parents=False,exist_ok=False)¶

Create a new directory at this given path. Ifmode is given, it iscombined with the process’umask value to determine the file modeand access flags. If the path already exists,FileExistsErroris raised.

Ifparents is true, any missing parents of this path are createdas needed; they are created with the default permissions without takingmode into account (mimicking the POSIXmkdir-p command).

Ifparents is false (the default), a missing parent raisesFileNotFoundError.

Ifexist_ok is false (the default),FileExistsError israised if the target directory already exists.

Ifexist_ok is true,FileExistsError exceptions will beignored (same behavior as the POSIXmkdir-p command), but only if thelast path component is not an existing non-directory file.

Changed in version 3.5:Theexist_ok parameter was added.

Path.open(mode='r',buffering=-1,encoding=None,errors=None,newline=None)¶

Open the file pointed to by the path, like the built-inopen()function does:

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

Path.owner()¶

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

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'

New in version 3.5.

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 samemeaning as inopen().

New in version 3.5.

Path.readlink()¶

Return the path to which the symbolic link points (as returned byos.readlink()):

>>>p=Path('mylink')>>>p.symlink_to('setup.py')>>>p.readlink()PosixPath('setup.py')

New in version 3.9.

Path.rename(target)¶

Rename this file or directory to the giventarget, and return a new Pathinstance pointing totarget. On Unix, iftarget exists and is a file,it will be replaced silently if the user has permission.target can beeither 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 interpretedrelative to the current working directory,not the directory of the Pathobject.

Changed in version 3.8:Added return value, return the new Path instance.

Path.replace(target)¶

Rename this file or directory to the giventarget, and return a new Pathinstance pointing totarget. Iftarget points to an existing file orempty directory, it will be unconditionally replaced.

The target path may be absolute or relative. Relative paths are interpretedrelative to the current working directory,not the directory of the Pathobject.

Changed in version 3.8:Added return value, return the new Path instance.

Path.resolve(strict=False)¶

Make the path absolute, resolving any symlinks. A new path object isreturned:

>>>p=Path()>>>pPosixPath('.')>>>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 andstrict isTrue,FileNotFoundErroris raised. Ifstrict isFalse, the path is resolved as far as possibleand any remainder is appended without checking whether it exists. If aninfinite loop is encountered along the resolution path,RuntimeErroris raised.

New in version 3.6:Thestrict argument (pre-3.6 behavior is strict).

Path.rglob(pattern)¶

This is like callingPath.glob() with “**/” added in front of thegiven relativepattern:

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

Raises anauditing eventpathlib.Path.rglob with argumentsself,pattern.

Path.rmdir()¶

Remove this directory. The directory must be empty.

Path.samefile(other_path)¶

Return whether this path points to the same file asother_path, whichcan be either a Path object, or a string. The semantics are similartoos.path.samefile() andos.path.samestat().

AnOSError can be raised if either file cannot be accessed for somereason.

>>>p=Path('spam')>>>q=Path('eggs')>>>p.samefile(q)False>>>p.samefile('spam')True

New in version 3.5.

Path.symlink_to(target,target_is_directory=False)¶

Make this path a symbolic link totarget. Under Windows,target_is_directory must be true (defaultFalse) if the link’s targetis 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_size956>>>p.lstat().st_size8

Note

The order of arguments (link, target) is the reverseofos.symlink()’s.

Path.link_to(target)¶

Maketarget a hard link to this path.

Warning

This function does not make this path a hard link totarget, despitethe implication of the function and argument names. The argument order(target, link) is the reverse ofPath.symlink_to(), but matchesthat ofos.link().

New in version 3.8.

Path.touch(mode=0o666,exist_ok=True)¶

Create a file at this given path. Ifmode is given, it is combinedwith the process’umask value to determine the file mode and accessflags. If the file already exists, the function succeeds ifexist_okis true (and its modification time is updated to the current time),otherwiseFileExistsError is raised.

Path.unlink(missing_ok=False)¶

Remove this file or symbolic link. If the path points to a directory,usePath.rmdir() instead.

Ifmissing_ok is false (the default),FileNotFoundError israised if the path does not exist.

Ifmissing_ok is true,FileNotFoundError exceptions will beignored (same behavior as the POSIXrm-f command).

Changed in version 3.8:Themissing_ok parameter was added.

Path.write_bytes(data)¶

Open the file pointed to in bytes mode, writedata to it, and close thefile:

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

New in version 3.5.

Path.write_text(data,encoding=None,errors=None)¶

Open the file pointed to in text mode, writedata to it, and close thefile:

>>>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 parametershave the same meaning as inopen().

New in version 3.5.