pathlib --- 面向对象的文件系统路径-Python教程

通用性质

路径是不可变并可哈希的。相同风格的路径可以排序与比较。这些性质尊重对应风格的大小写转换语义:

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

不同风格的路径比较得到不等的结果并且无法被排序:

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

运算符

斜杠 / 操作符有助于创建子路径，就像 os.path.join() 一样:

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

文件对象可用于任何接受 os.PathLike 接口实现的地方。

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

路径的字符串表示法为它自己原始的文件系统路径（以原生形式，例如在 Windows 下使用反斜杠）。你可以传递给任何需要字符串形式路径的函数。

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

类似地，在路径上调用 bytes 将原始文件系统路径作为字节对象给出，就像被 os.fsencode() 编码一样:

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

访问个别部分

为了访问路径独立的部分 （组件），使用以下特征属性：

PurePath. parts

一个元组，可以访问路径的多个组件:

>>>

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

（注意盘符和本地根目录是如何重组的）

方法和特征属性

纯路径提供以下方法和特征属性：

PurePath. drive

一个表示驱动器盘符或命名的字符串，如果存在:

>>>

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

UNC 分享也被认作驱动器:

>>>

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath. root

一个表示（本地或全局）根的字符串，如果存在:

>>>

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

UNC 分享一样拥有根:

>>>

>>> PureWindowsPath('//host/share').root
'\\'

PurePath. anchor

驱动器和根的联合:

>>>

>>> 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 of the path:

>>>

>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')

PurePath. parent

此路径的逻辑父路径:

>>>

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

你不能超过一个 anchor 或空路径:

>>>

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

注解

这是一个单纯的词法操作，因此有以下行为:

>>>

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

如果你想要向上移动任意文件系统路径，推荐先使用 Path.resolve() 来解析符号链接以及消除 ".." 组件。

PurePath. name

一个表示最后路径组件的字符串，排除了驱动器与根目录，如果存在的话:

>>>

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

UNC 驱动器名不被考虑:

>>>

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath. suffix

最后一个组件的文件扩展名，如果存在:

>>>

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

PurePath. suffixes

路径的文件扩展名列表:

>>>

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

PurePath. stem

最后一个路径组件，除去后缀:

>>>

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

PurePath. as_posix ( )

返回使用正斜杠（ / ）的路径字符串:

>>>

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

PurePath. as_uri ( )

将路径表示为 file URL。如果并非绝对路径，抛出 ValueError 。

>>>

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

PurePath. is_absolute ( )

返回此路径是否为绝对路径。如果路径同时拥有驱动器符与根路径（如果风格允许）则将被认作绝对路径。

>>>

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

在 PureWindowsPath ，如果路径是被 Windows 保留的则返回 True ，否则 False 。在 PurePosixPath ，总是返回 False 。

>>>

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

当保留路径上的文件系统被调用，则可能出现玄学失败或者意料之外的效应。

PurePath. joinpath ( *other )

调用此方法等同于将每个 other 参数中的项目连接在一起:

>>>

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

将此路径与提供的通配符风格的模式匹配。如果匹配成功则返回 True ，否则返回 False 。

如果 pattern 是相对的，则路径可以是相对路径或绝对路径，并且匹配是从右侧完成的：

>>>

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

如果 pattern 是绝对的，则路径必须是绝对的，并且路径必须完全匹配:

>>>

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

与其他方法一样，可以观察到大小写区分:

>>>

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

PurePath. relative_to ( *other )

计算此路径相对 other 表示路径的版本。如果不可计算，则抛出 ValueError:

>>>

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'

PurePath. with_name ( name )

返回一个新的路径并修改 name 。如果原本路径没有 name，ValueError 被抛出:

>>>

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath. with_suffix ( suffix )

返回一个新的路径并修改 suffix 。如果原本的路径没有后缀，新的 suffix 则被追加以代替。如果 suffix 是空字符串，则原本的后缀被移除:

>>>

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

方法

除纯路径方法外，实体路径还提供以下方法。 如果系统调用失败（例如因为路径不存在）这些方法中许多都会引发 OSError 。

classmethod Path. cwd ( )

返回一个新的表示当前目录的路径对象（和 os.getcwd() 返回的相同）:

>>>

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

classmethod Path. home ( )

返回一个表示当前用户家目录的新路径对象（和 os.path.expanduser() 构造含 ~ 路径返回的相同）:

>>>

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

3.5 新版功能.

Path. stat ( )

返回此路径的信息（类似于 os.stat() ）。结果在每次调用此方法时都重新产生。

>>>

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

Path. chmod ( mode )

改变文件的模式和权限，和 os.chmod() 一样:

>>>

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

Path. exists ( )

此路径是否指向一个已存在的文件或目录:

>>>

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

注解

如果路径指向一个符号链接， exists() 返回此符号链接是否指向存在的文件或目录。

Path. expanduser ( )

返回展开了包含 ~ 和 ~user 的构造，就和 os.path.expanduser() 一样:

>>>

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

3.5 新版功能.

Path. glob ( pattern )

解析相对于此路径的通配符 pattern ，产生所有匹配的文件:

>>>

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

注解

在一个较大的目录树中使用 " ** " 模式可能会消耗非常多的时间。

Path. group ( )

返回拥有此文件的用户组。如果文件的 GID 无法在系统数据库中找到，将抛出 KeyError 。

Path. is_dir ( )

如果路径指向一个目录（或者一个指向目录的符号链接）则返回 True ，如果指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. is_file ( )

如果路径指向一个正常的文件（或者一个指向正常文件的符号链接）则返回 True ，如果指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. is_mount ( )

如果路径是一个 挂载点 <mount point> ：在文件系统中被其他不同的文件系统挂载的地点。在 POSIX 系统，此函数检查 path 的父级 —— path/.. 是否处于一个和 path 不同的设备中，或者 file: path/.. 和 path 是否指向相同设备的相同 i-node —— 这能检测所有 Unix 以及 POSIX 变种上的挂载点。 Windows 上未实现。

3.7 新版功能.

Path. is_symlink ( )

如果路径指向符号链接则返回 True ， 否则 False 。

如果路径不存在也返回 False ；其他错误（例如权限错误）被传播。

Path. is_socket ( )

如果路径指向一个 Unix socket 文件（或者指向 Unix socket 文件的符号链接）则返回 True ，如果指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. is_fifo ( )

如果路径指向一个先进先出存储（或者指向先进先出存储的符号链接）则返回 True ，指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. is_block_device ( )

如果文件指向一个块设备（或者指向块设备的符号链接）则返回 True ，指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. is_char_device ( )

如果路径指向一个字符设备（或指向字符设备的符号链接）则返回 True ，指向其他类型的文件则返回 False 。

当路径不存在或者是一个破损的符号链接时也会返回 False ；其他错误（例如权限错误）被传播。

Path. iterdir ( )

当路径指向一个目录时，产生该路径下的对象的路径:

>>>

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

Path. lchmod ( mode )

就像 Path.chmod() 但是如果路径指向符号链接则是修改符号链接的模式，而不是修改符号链接的目标。

Path. lstat ( )

就和 Path.stat() 一样，但是如果路径指向符号链接，则是返回符号链接而不是目标的信息。

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

新建给定路径的目录。如果给出了 mode ，它将与当前进程的 umask 值合并来决定文件模式和访问标志。如果路径已经存在，则抛出 FileExistsError 。

如果 parents 为 true，任何找不到的父目录都会伴随着此路径被创建；它们会以默认权限被创建，而不考虑 mode 设置（模仿 POSIX 的 mkdir -p 命令）。

如果 parents 为 false（默认），则找不到的父级目录会导致 FileNotFoundError 被抛出。

如果 exist_ok 为 false（默认），则在目标已存在的情况下抛出 FileExistsError 。

如果 exist_ok 为 true， 则 FileExistsError 异常将被忽略（和 POSIX mkdir -p 命令行为相同），但是只有在最后一个路径组件不是现存的非目录文件时才生效。

在 3.5 版更改: exist_ok 形参被加入。

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

打开路径指向的文件，就像内置的 open() 函数所做的一样:

>>>

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

Path. owner ( )

返回拥有此文件的用户名。如果文件的 UID 无法在系统数据库中找到，则抛出 KeyError 。

Path. read_bytes ( )

以字节对象的形式返回路径指向的文件的二进制内容:

>>>

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

3.5 新版功能.

Path. read_text ( encoding=None , errors=None )

以字符串形式返回路径指向的文件的解码后文本内容。

>>>

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

文件先被打开然后关闭。有和 open() 一样的可选形参。

3.5 新版功能.

Path. rename ( target )

将文件或目录重命名为给定的 target ，并返回一个新的指向 target 的 Path 实例。 在 Unix 上，如果 target 存在且为一个文件，如果用户有足够权限，则它将被静默地替换。 target 可以是一个字符串或者另一个路径对象:

>>>

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

在 3.8 版更改: 添加了返回值，返回新的 Path 实例。

Path. replace ( target )

将文件名目录重命名为给定的 target ，并返回一个新的指向 target 的 Path 实例。 如果 target 指向一个现有文件或目录，则它将被无条件地替换。

在 3.8 版更改: 添加了返回值，返回新的 Path 实例。

Path. resolve ( strict=False )

将路径绝对化，解析任何符号链接。返回新的路径对象:

>>>

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

" .. " 组件也将被消除（只有这一种方法这么做）:

>>>

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

如果路径不存在并且 strict 设为 True ，则抛出 FileNotFoundError 。如果 strict 为 False ，则路径将被尽可能地解析并且任何剩余部分都会被不检查是否存在地追加。如果在解析路径上发生无限循环，则抛出 RuntimeError 。

3.6 新版功能: 加入*strict* 参数（3.6之前的版本相当于strict值为True）

Path. rglob ( pattern )

这就像调用 Path.glob`时在给定的相对 *pattern* 前面添加了"``**/`() "

>>>

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

Path. rmdir ( )

移除此目录。此目录必须为空的。

Path. samefile ( other_path )

返回此目录是否指向与可能是字符串或者另一个路径对象的 other_path 相同的文件。语义类似于 os.path.samefile() 与 os.path.samestat() 。

如果两者都以同一原因无法访问，则抛出 OSError 。

>>>

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

3.5 新版功能.

Path. symlink_to ( target , target_is_directory=False )

将此路径创建为指向 target 的符号链接。在 Windows 下，如果链接的目标是一个目录则 target_is_directory 必须为 true （默认为 False ）。在 POSIX 下， target_is_directory 的值将被忽略。

>>>

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8

注解

参数的顺序（link, target) 和 os.symlink() 是相反的。

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

将给定的路径创建为文件。如果给出了 mode 它将与当前进程的 umask 值合并以确定文件的模式和访问标志。如果文件已经存在，则当 exist_ok 为 true 则函数仍会成功（并且将它的修改事件更新为当前事件），否则抛出 FileExistsError 。

Path. unlink ( missing_ok=False )

移除此文件或符号链接。如果路径指向目录，则用 Path.rmdir() 代替。

如果 missing_ok 为假值（默认），则如果路径不存在将会引发 FileNotFoundError 。

如果 missing_ok 为真值，则 FileNotFoundError 异常将被忽略（和 POSIX rm -f 命令的行为相同）。

在 3.8 版更改: 增加了 missing_ok 形参。

Path. link_to ( target )

创建一个指向名为 target 的路径的硬链接。

在 3.8 版更改.

Path. write_bytes ( data )

将文件以二进制模式打开，写入 data 并关闭:

>>>

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

一个同名的现存文件将被覆盖。

3.5 新版功能.

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

将文件以文本模式打开，写入 data 并关闭:

>>>

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

同名的现有文件会被覆盖。 可选形参的含义与 open() 的相同。

3.5 新版功能.