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

The implementation of theos.path module used for low-level pathparsing and joining: eitherposixpath orntpath.

Added in version 3.13.

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 last dot-separated portion of the final component, if any:

>>>PurePosixPath('my/library/setup.py').suffix'.py'>>>PurePosixPath('my/library.tar.gz').suffix'.gz'>>>PurePosixPath('my/library').suffix''

This is commonly called the file extension.

Άλλαξε στην έκδοση 3.14:A single dot (».») is considered a valid suffix.

PurePath.suffixes¶

A list of the path’s suffixes, often called file extensions:

>>>PurePosixPath('my/library.tar.gar').suffixes['.tar', '.gar']>>>PurePosixPath('my/library.tar.gz').suffixes['.tar', '.gz']>>>PurePosixPath('my/library').suffixes[]

Άλλαξε στην έκδοση 3.14:A single dot (».») is considered a valid suffix.

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

Άλλαξε στην έκδοση 3.13:Windows path names that contain a colon, or end with a dot or a space,are considered reserved. UNC paths may be reserved.

Deprecated since version 3.13, will be removed in version 3.15:This method is deprecated; useos.path.isreserved() to detectreserved paths on Windows.

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.full_match(pattern,*,case_sensitive=None)¶

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

>>>PurePath('a/b.py').full_match('a/*.py')True>>>PurePath('a/b.py').full_match('*.py')False>>>PurePath('/a/b/c.py').full_match('/a/**')True>>>PurePath('/a/b/c.py').full_match('**/*.py')True

Δείτε επίσης

Pattern language documentation.

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

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

Setcase_sensitive toTrue orFalse to override this behaviour.

Added in version 3.13.

PurePath.match(pattern,*,case_sensitive=None)¶

Match this path against the provided non-recursive glob-style pattern.ReturnTrue if matching is successful,False otherwise.

This method is similar tofull_match(), but empty patternsaren’t allowed (ValueError is raised), the recursive wildcard«**» isn’t supported (it acts like non-recursive «*»), and if arelative pattern is provided, then 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

Άλλαξε στην έκδοση 3.12:Thepattern parameter accepts apath-like object.

Άλλαξε στην έκδοση 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, 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')

Άλλαξε στην έκδοση 3.14:A single dot (».») is considered a valid suffix. In previousversions,ValueError is raised if a single dot is supplied.

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.

Parsing and generating URIs¶

Concrete path objects can be created from, and represented as, “file” URIsconforming toRFC 8089.

classmethodPath.from_uri(uri)¶

Return a new path object from parsing a “file” URI. For example:

>>>p=Path.from_uri('file:///etc/hosts')PosixPath('/etc/hosts')

On Windows, DOS device and UNC paths may be parsed from URIs:

>>>p=Path.from_uri('file:///c:/windows')WindowsPath('c:/windows')>>>p=Path.from_uri('file://server/share')WindowsPath('//server/share')

Several variant forms are supported:

>>>p=Path.from_uri('file:////server/share')WindowsPath('//server/share')>>>p=Path.from_uri('file://///server/share')WindowsPath('//server/share')>>>p=Path.from_uri('file:c:/windows')WindowsPath('c:/windows')>>>p=Path.from_uri('file:/c|/windows')WindowsPath('c:/windows')

ValueError is raised if the URI does not start withfile:, orthe parsed path isn’t absolute.

Added in version 3.13.

Άλλαξε στην έκδοση 3.14:The URL authority is discarded if it matches the local hostname.Otherwise, if the authority isn’t empty orlocalhost, then onWindows a UNC path is returned (as before), and on other platforms aValueError is raised.

Path.as_uri()¶

Represent the path as a “file” URI.ValueError is raised ifthe path isn’t absolute.

>>>p=PosixPath('/etc/passwd')>>>p.as_uri()'file:///etc/passwd'>>>p=WindowsPath('c:/Windows')>>>p.as_uri()'file:///c:/Windows'

Deprecated since version 3.14, will be removed in version 3.19:Calling this method fromPurePath rather thanPath ispossible but deprecated. The method’s use ofos.fsencode() makesit strictly impure.

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 a path doesn’t exist or a symlink loop is encountered, andstrict isTrue,OSError is raised. Ifstrict isFalse, the path isresolved as far as possible and any remainder is appended without checkingwhether it exists.

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

Άλλαξε στην έκδοση 3.13:Symlink loops are treated like other errors:OSError is raised instrict mode, and no exception is raised in non-strict mode. In previousversions,RuntimeError is raised no matter the value ofstrict.

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.

Άλλαξε στην έκδοση 3.13:RaisesUnsupportedOperation ifos.readlink() is notavailable. In previous versions,NotImplementedError was raised.

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.False will be returned if the path is invalid, inaccessible or missing.UsePath.stat() to distinguish between these cases.

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(*,follow_symlinks=True)¶

ReturnTrue if the path points to a regular file.False will bereturned if the path is invalid, inaccessible or missing, or if it pointsto something other than a regular file. UsePath.stat() todistinguish between these cases.

This method normally follows symlinks; to exclude symlinks, add theargumentfollow_symlinks=False.

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

Path.is_dir(*,follow_symlinks=True)¶

ReturnTrue if the path points to a directory.False will bereturned if the path is invalid, inaccessible or missing, or if it pointsto something other than a directory. UsePath.stat() to distinguishbetween these cases.

This method normally follows symlinks; to exclude symlinks to directories,add the argumentfollow_symlinks=False.

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

Path.is_symlink()¶

ReturnTrue if the path points to a symbolic link, even if that symlinkis broken.False will be returned if the path is invalid, inaccessibleor missing, or if it points to something other than a symbolic link. UsePath.stat() to distinguish between these cases.

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.False will bereturned if the path is invalid, inaccessible or missing, or if it pointsto something other than a Unix socket. UsePath.stat() todistinguish between these cases.

Path.is_fifo()¶

ReturnTrue if the path points to a FIFO.False will be returned ifthe path is invalid, inaccessible or missing, or if it points to somethingother than a FIFO. UsePath.stat() to distinguish between thesecases.

Path.is_block_device()¶

ReturnTrue if the path points to a block device.False will bereturned if the path is invalid, inaccessible or missing, or if it pointsto something other than a block device. UsePath.stat() todistinguish between these cases.

Path.is_char_device()¶

ReturnTrue if the path points to a character device.False will bereturned if the path is invalid, inaccessible or missing, or if it pointsto something other than a character device. UsePath.stat() todistinguish between these cases.

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.

Path.info¶

APathInfo object that supports querying file typeinformation. The object exposes methods that cache their results, which canhelp reduce the number of system calls needed when switching on file type.For example:

>>>p=Path('src')>>>ifp.info.is_symlink():...print('symlink')...elifp.info.is_dir():...print('directory')...elifp.info.exists():...print('something else')...else:...print('not found')...directory

If the path was generated fromPath.iterdir() then this attribute isinitialized with some information about the file type gleaned from scanningthe parent directory. Merely accessingPath.info does not performany filesystem queries.

To fetch up-to-date information, it’s best to callPath.is_dir(),is_file() andis_symlink() rather than methods ofthis attribute. There is no way to reset the cache; instead you can createa new path object with an empty info cache viap=Path(p).

Added in version 3.14.

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,newline=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.

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

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,recurse_symlinks=False)¶

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')]>>>sorted(Path('.').glob('**/*.py'))[PosixPath('build/lib/pathlib.py'), PosixPath('docs/conf.py'), PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]

Δείτε επίσης

Pattern language documentation.

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.

By default, or when therecurse_symlinks keyword-only argument is set toFalse, this method follows symlinks except when expanding «**»wildcards. Setrecurse_symlinks toTrue to always follow symlinks.

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

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

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

Άλλαξε στην έκδοση 3.13:Thepattern parameter accepts apath-like object.

Άλλαξε στην έκδοση 3.13:AnyOSError exceptions raised from scanning the filesystem aresuppressed. In previous versions, such exceptions are suppressed in manycases, but not all.

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

Glob the given relativepattern recursively. This is like callingPath.glob() with «**/» added in front of thepattern.

Δείτε επίσης

Pattern language andPath.glob() documentation.

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

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

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

Άλλαξε στην έκδοση 3.13:Thepattern parameter accepts apath-like object.

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.

Άλλαξε στην έκδοση 3.13:RaisesUnsupportedOperation ifos.symlink() is notavailable. In previous versions,NotImplementedError was raised.

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.

Άλλαξε στην έκδοση 3.13:RaisesUnsupportedOperation ifos.link() is notavailable. In previous versions,NotImplementedError was raised.

Copying, moving and deleting¶

Path.copy(target,*,follow_symlinks=True,preserve_metadata=False)¶

Copy this file or directory tree to the giventarget, and return a newPath instance pointing totarget.

If the source is a file, the target will be replaced if it is an existingfile. If the source is a symlink andfollow_symlinks is true (thedefault), the symlink’s target is copied. Otherwise, the symlink isrecreated at the destination.

Ifpreserve_metadata is false (the default), only directory structuresand file data are guaranteed to be copied. Setpreserve_metadata to trueto ensure that file and directory permissions, flags, last access andmodification times, and extended attributes are copied where supported.This argument has no effect when copying files on Windows (wheremetadata is always preserved).

Σημείωση

Where supported by the operating system and file system, this methodperforms a lightweight copy, where data blocks are only copied whenmodified. This is known as copy-on-write.

Added in version 3.14.

Path.copy_into(target_dir,*,follow_symlinks=True,preserve_metadata=False)¶

Copy this file or directory tree into the giventarget_dir, which shouldbe an existing directory. Other arguments are handled identically toPath.copy(). Returns a newPath instance pointing to thecopy.

Added in version 3.14.

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.move(target)¶

Move this file or directory tree to the giventarget, and return a newPath instance pointing totarget.

If thetarget doesn’t exist it will be created. If both this path and thetarget are existing files, then the target is overwritten. If both pathspoint to the same file or directory, or thetarget is a non-emptydirectory, thenOSError is raised.

If both paths are on the same filesystem, the move is performed withos.replace(). Otherwise, this path is copied (preserving metadata andsymlinks) and then deleted.

Added in version 3.14.

Path.move_into(target_dir)¶

Move this file or directory tree into the giventarget_dir, which shouldbe an existing directory. Returns a newPath instance pointing tothe moved path.

Added in version 3.14.

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(*,follow_symlinks=True)¶

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.

This method normally follows symlinks; to get the owner of the symlink, addthe argumentfollow_symlinks=False.

Άλλαξε στην έκδοση 3.13:RaisesUnsupportedOperation if thepwd module is notavailable. In earlier versions,NotImplementedError was raised.

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

Path.group(*,follow_symlinks=True)¶

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.

This method normally follows symlinks; to get the group of the symlink, addthe argumentfollow_symlinks=False.

Άλλαξε στην έκδοση 3.13:RaisesUnsupportedOperation if thegrp module is notavailable. In earlier versions,NotImplementedError was raised.

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

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.

Corresponding tools¶

Below is a table mapping variousos functions to their correspondingPurePath/Path equivalent.

Footnotes

os.path.relpath() callsabspath() to make pathsabsolute and remove «..» parts, whereasPurePath.relative_to()is a lexical operation that raisesValueError when its inputs”anchors differ (e.g. if one path is absolute and the other relative.)

os.path.expanduser() returns the path unchanged if the homedirectory can’t be resolved, whereasPath.expanduser() raisesRuntimeError.

os.path.abspath() removes «..» components without resolvingsymlinks, which may change the meaning of the path, whereasPath.absolute() leaves any «..» components in the path.

os.walk() always follows symlinks when categorizing paths intodirnames andfilenames, whereasPath.walk() categorizes allsymlinks intofilenames whenfollow_symlinks is false (the default.)