General properties¶

Paths are immutable andhashable. 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, likeos.path.join().If the argument is an absolute path, the previous path is ignored.On Windows, the drive is not reset when the argument is a rootedrelative path (e.g.,r'\foo'):

>>>p=PurePath('/etc')>>>pPurePosixPath('/etc')>>>p/'init.d'/'apache2'PurePosixPath('/etc/init.d/apache2')>>>q=PurePath('bin')>>>'/usr'/qPurePosixPath('/usr/bin')>>>p/'/an_absolute_path'PurePosixPath('/an_absolute_path')>>>PureWindowsPath('c:/Windows','/Program Files')PureWindowsPath('c:/Program Files')

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

If the path starts with more than two successive slashes,PurePosixPath collapses them:

>>>PurePosixPath('//etc').root'//'>>>PurePosixPath('///etc').root'/'>>>PurePosixPath('////etc').root'/'

Σημείωση

This behavior conforms toThe Open Group Base Specifications Issue 6,paragraph4.11 Pathname Resolution:

«A pathname that begins with two successive slashes may be interpreted inan implementation-defined manner, although more than two leading slashesshall be treated as a single slash.»

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

Άλλαξε στην έκδοση 3.10:The parents sequence now supportsslices and negative index values.

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

Σημείωση

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

This method is string-based; it neither accesses the filesystem nor treats«..» segments specially. The following code is equivalent:

>>>u=PurePath('/usr')>>>u==poruinp.parentsFalse

Added in version 3.9.

Deprecated since version 3.12, will be removed in version 3.14:Passing additional arguments is deprecated; if supplied, they are joinedwithother.

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(*pathsegments)¶

Calling this method is equivalent to combining the path with each ofthe givenpathsegments 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,*,case_sensitive=None)¶

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

Thepattern may be another path object; this speeds up matching the samepattern against multiple files:

>>>pattern=PurePath('*.py')>>>PurePath('a/b.py').match(pattern)True

Σημείωση

The recursive wildcard «**» isn’t supported by this method (it actslike non-recursive «*».)

Άλλαξε στην έκδοση 3.12:Accepts an object implementing theos.PathLike interface.

As with other methods, case-sensitivity follows platform defaults:

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

Setcase_sensitive toTrue orFalse to override this behaviour.

Άλλαξε στην έκδοση 3.12:Thecase_sensitive parameter was added.

PurePath.relative_to(other,walk_up=False)¶

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", line941, inrelative_toraiseValueError(error_message.format(str(self),str(formatted)))ValueError:'/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.

Whenwalk_up is false (the default), the path must start withother.When the argument is true,.. entries may be added to form therelative path. In all other cases, such as the paths referencingdifferent drives,ValueError is raised.:

>>>p.relative_to('/usr',walk_up=True)PurePosixPath('../etc/passwd')>>>p.relative_to('foo',walk_up=True)Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"pathlib.py", line941, inrelative_toraiseValueError(error_message.format(str(self),str(formatted)))ValueError:'/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.

Προειδοποίηση

This function is part ofPurePath and works with strings.It does not check or access the underlying file structure.This can impact thewalk_up option as it assumes that no symlinksare present in the path; callresolve() first ifnecessary to resolve symlinks.

Άλλαξε στην έκδοση 3.12:Thewalk_up parameter was added (old behavior is the same aswalk_up=False).

Deprecated since version 3.12, will be removed in version 3.14:Passing additional positional arguments is deprecated; if supplied,they are joined withother.

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

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

PurePath.with_segments(*pathsegments)¶

Create a new path object of the same type by combining the givenpathsegments. This method is called whenever a derivative path is created,such as fromparent andrelative_to(). Subclasses mayoverride this method to pass information to derivative paths, for example:

frompathlibimportPurePosixPathclassMyPath(PurePosixPath):def__init__(self,*pathsegments,session_id):super().__init__(*pathsegments)self.session_id=session_iddefwith_segments(self,*pathsegments):returntype(self)(*pathsegments,session_id=self.session_id)etc=MyPath('/etc',session_id=42)hosts=etc/'hosts'print(hosts.session_id)# 42

Added in version 3.12.

Expanding and resolving paths¶

classmethodPath.home()¶

Return a new path object representing the user’s home directory (asreturned byos.path.expanduser() with~ construct). If the homedirectory can’t be resolved,RuntimeError is raised.

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

Added in version 3.5.

Path.expanduser()¶

Return a new path with expanded~ and~user constructs,as returned byos.path.expanduser(). If a home directory can’t beresolved,RuntimeError is raised.

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

Added in version 3.5.

classmethodPath.cwd()¶

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

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

Path.absolute()¶

Make the path absolute, without normalization or resolving symlinks.Returns a new path object:

>>>p=Path('tests')>>>pPosixPath('tests')>>>p.absolute()PosixPath('/home/antoine/pathlib/tests')

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.

Άλλαξε στην έκδοση 3.6:Thestrict parameter was added (pre-3.6 behavior is strict).

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

Added in version 3.9.

Querying file type and status¶

Path.stat(*,follow_symlinks=True)¶

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

This method normally follows symlinks; to stat a symlink add the argumentfollow_symlinks=False, or uselstat().

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

Άλλαξε στην έκδοση 3.10:Thefollow_symlinks parameter was added.

Path.lstat()¶

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

Path.exists(*,follow_symlinks=True)¶

ReturnTrue if the path points to an existing file or directory.

This method normally follows symlinks; to check if a symlink exists, addthe argumentfollow_symlinks=False.

>>>Path('.').exists()True>>>Path('setup.py').exists()True>>>Path('/etc').exists()True>>>Path('nonexistentfile').exists()False

Άλλαξε στην έκδοση 3.12:Thefollow_symlinks parameter was added.

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_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_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_junction()¶

ReturnTrue if the path points to a junction, andFalse for any othertype of file. Currently only Windows supports junctions.

Added in version 3.12.

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. On Windows, a mount point is considered to be a driveletter root (e.g.c:\), a UNC share (e.g.\\server\share), or amounted filesystem directory.

Added in version 3.7.

Άλλαξε στην έκδοση 3.12:Windows support was added.

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

Added in version 3.5.

Reading and writing files¶

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

Added in version 3.5.

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'

Added in version 3.5.

Path.write_text(data,encoding=None,errors=None,newline=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().

Added in version 3.5.

Άλλαξε στην έκδοση 3.10:Thenewline 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.

Added in version 3.5.

Reading directories¶

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, it is unspecified whethera path object for that file is included.

If the path is not a directory or otherwise inaccessible,OSError israised.

Path.glob(pattern,*,case_sensitive=None)¶

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

Patterns are the same as forfnmatch, with the addition of «**»which means «this directory and all subdirectories, recursively». In otherwords, 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')]

This method callsPath.is_dir() on the top-level directory andpropagates anyOSError exception that is raised. SubsequentOSError exceptions from scanning directories are suppressed.

By default, or when thecase_sensitive keyword-only argument is set toNone, this method matches paths using platform-specific casing rules:typically, case-sensitive on POSIX, and case-insensitive on Windows.Setcase_sensitive toTrue orFalse to override this behaviour.

Σημείωση

Using the «**» pattern in large directory trees may consumean inordinate amount of time.

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

Άλλαξε στην έκδοση 3.11:Return only directories ifpattern ends with a pathname componentsseparator (sep oraltsep).

Άλλαξε στην έκδοση 3.12:Thecase_sensitive parameter was added.

Path.rglob(pattern,*,case_sensitive=None)¶

Glob the given relativepattern recursively. This is like callingPath.glob() with «**/» added in front of thepattern, wherepatterns are the same as forfnmatch:

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

By default, or when thecase_sensitive keyword-only argument is set toNone, this method matches paths using platform-specific casing rules:typically, case-sensitive on POSIX, and case-insensitive on Windows.Setcase_sensitive toTrue orFalse to override this behaviour.

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

Άλλαξε στην έκδοση 3.11:Return only directories ifpattern ends with a pathname componentsseparator (sep oraltsep).

Άλλαξε στην έκδοση 3.12:Thecase_sensitive parameter was added.

Path.walk(top_down=True,on_error=None,follow_symlinks=False)¶

Generate the file names in a directory tree by walking the treeeither top-down or bottom-up.

For each directory in the directory tree rooted atself (includingself but excluding “.” and “..”), the method yields a 3-tuple of(dirpath,dirnames,filenames).

dirpath is aPath to the directory currently being walked,dirnames is a list of strings for the names of subdirectories indirpath(excluding'.' and'..'), andfilenames is a list of strings forthe names of the non-directory files indirpath. To get a full path(which begins withself) to a file or directory indirpath, dodirpath/name. Whether or not the lists are sorted is filesystem-dependent.

If the optional argumenttop_down is true (which is the default), the triple for adirectory is generated before the triples for any of its subdirectories(directories are walked top-down). Iftop_down is false, the triplefor a directory is generated after the triples for all of its subdirectories(directories are walked bottom-up). No matter the value oftop_down, thelist of subdirectories is retrieved before the triples for the directory andits subdirectories are walked.

Whentop_down is true, the caller can modify thedirnames list in-place(for example, usingdel or slice assignment), andPath.walk()will only recurse into the subdirectories whose names remain indirnames.This can be used to prune the search, or to impose a specific order of visiting,or even to informPath.walk() about directories the caller creates orrenames before it resumesPath.walk() again. Modifyingdirnames whentop_down is false has no effect on the behavior ofPath.walk() since thedirectories indirnames have already been generated by the timedirnamesis yielded to the caller.

By default, errors fromos.scandir() are ignored. If the optionalargumenton_error is specified, it should be a callable; it will becalled with one argument, anOSError instance. The callable can handle theerror to continue the walk or re-raise it to stop the walk. Note that thefilename is available as thefilename attribute of the exception object.

By default,Path.walk() does not follow symbolic links, and instead adds themto thefilenames list. Setfollow_symlinks to true to resolve symlinksand place them indirnames andfilenames as appropriate for their targets, andconsequently visit directories pointed to by symlinks (where supported).

Σημείωση

Be aware that settingfollow_symlinks to true can lead to infiniterecursion if a link points to a parent directory of itself.Path.walk()does not keep track of the directories it has already visited.

Σημείωση

Path.walk() assumes the directories it walks are not modified duringexecution. For example, if a directory fromdirnames has been replacedwith a symlink andfollow_symlinks is false,Path.walk() willstill try to descend into it. To prevent such behavior, remove directoriesfromdirnames as appropriate.

Σημείωση

Unlikeos.walk(),Path.walk() lists symlinks to directories infilenames iffollow_symlinks is false.

This example displays the number of bytes used by all files in each directory,while ignoring__pycache__ directories:

frompathlibimportPathforroot,dirs,filesinPath("cpython/Lib/concurrent").walk(on_error=print):print(root,"consumes",sum((root/file).stat().st_sizeforfileinfiles),"bytes in",len(files),"non-directory files")if'__pycache__'indirs:dirs.remove('__pycache__')

This next example is a simple implementation ofshutil.rmtree().Walking the tree bottom-up is essential asrmdir() doesn’t allowdeleting a directory before it is empty:

# Delete everything reachable from the directory "top".# CAUTION:  This is dangerous! For example, if top == Path('/'),# it could delete all of your files.forroot,dirs,filesintop.walk(top_down=False):fornameinfiles:(root/name).unlink()fornameindirs:(root/name).rmdir()

Added in version 3.12.

Creating files and directories¶

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

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

Δείτε επίσης

Theopen(),write_text() andwrite_bytes() methods are often used to create files.

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’sumask 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 will not be raised unless the givenpath already exists in the file system and is not a directory (samebehavior as the POSIXmkdir-p command).

Άλλαξε στην έκδοση 3.5:Theexist_ok parameter was added.

Path.symlink_to(target,target_is_directory=False)¶

Make this path a symbolic link pointing totarget.

On Windows, a symlink represents either a file or a directory, and does notmorph to the target dynamically. If the target is present, the type of thesymlink will be created to match. Otherwise, the symlink will be createdas a directory iftarget_is_directory is true or a file symlink (thedefault) otherwise. On non-Windows platforms,target_is_directory 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

Σημείωση

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

Path.hardlink_to(target)¶

Make this path a hard link to the same file astarget.

Σημείωση

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

Added in version 3.10.

Renaming and deleting¶

Path.rename(target)¶

Rename this file or directory to the giventarget, and return a newPath instance pointing totarget. On Unix, iftarget existsand is a file, it will be replaced silently if the user has permission.On Windows, iftarget exists,FileExistsError will be raised.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 interpretedrelative to the current working directory,not the directory of thePath object.

It is implemented in terms ofos.rename() and gives the same guarantees.

Άλλαξε στην έκδοση 3.8:Added return value, return the newPath instance.

Path.replace(target)¶

Rename this file or directory to the giventarget, and return a newPath instance pointing totarget. Iftarget points to anexisting file or empty 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 thePath object.

Άλλαξε στην έκδοση 3.8:Added return value, return the newPath instance.

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

Άλλαξε στην έκδοση 3.8:Themissing_ok parameter was added.

Path.rmdir()¶

Remove this directory. The directory must be empty.

Permissions and ownership¶

Path.owner()¶

Return the name of the user owning the file.KeyError is raisedif the file’s user identifier (UID) isn’t found in the system database.

Path.group()¶

Return the name of the group owning the file.KeyError is raisedif the file’s group identifier (GID) isn’t found in the system database.

Path.chmod(mode,*,follow_symlinks=True)¶

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

This method normally follows symlinks. Some Unix flavours support changingpermissions on the symlink itself; on these platforms you may add theargumentfollow_symlinks=False, or uselchmod().

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

Άλλαξε στην έκδοση 3.10:Thefollow_symlinks parameter was added.

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.