pathlib — 面向对象的文件系统路径

3.4 版中的新功能。

源代码： :source:`Lib/pathlib.py`

该模块提供表示文件系统路径的类，其语义适用于不同的操作系统。路径类分为纯路径和具体路径，它们提供没有 I/O 的纯计算操作，和具体路径，它们继承自纯路径但也提供 I/O 操作。

class=align-center|../_images/pathlib-inheritance.png 如果您以前从未使用过这个模块或者只是不确定哪个类适合您的任务，Path 很可能是您所需要的。它为代码运行的平台实例化具体路径。

纯路径在某些特殊情况下很有用；例如：

如果您想在 Unix 机器上操作 Windows 路径（反之亦然）。在 Unix 上运行时不能实例化 WindowsPath，但可以实例化 PureWindowsPath。
您想确保您的代码只操作路径而不实际访问操作系统。在这种情况下，实例化其中一个纯类可能会很有用，因为它们根本没有任何操作系统访问操作。

也可以看看

PEP 428：pathlib 模块——面向对象的文件系统路径。

也可以看看

对于字符串的低级路径操作，您还可以使用 os.path 模块。

基本使用

导入主类：

>>> from pathlib import Path

列出子目录：

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

在此目录树中列出 Python 源文件：

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

在目录树中导航：

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

查询路径属性：

>>> q.exists()
True
>>> q.is_dir()
False

打开文件：

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

纯路径

纯路径对象提供不实际访问文件系统的路径处理操作。可以通过三种方式访问这些类，我们也称之为 flavours：

class pathlib.PurePath(*pathsegments)

表示系统路径风格的通用类（实例化它会创建 PurePosixPath 或 PureWindowsPath）：

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

pathsegments 的每个元素都可以是一个表示路径段的字符串，一个实现 os.PathLike 接口的对象，返回一个字符串，或者另一个路径对象：

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

当 pathsegments 为空时，假定当前目录为：

>>> PurePath()
PurePosixPath('.')

当给出几个绝对路径时，最后一个作为锚点（模仿 os.path.join() 的行为）：

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

但是，在 Windows 路径中，更改本地根目录不会丢弃之前的驱动器设置：

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

伪斜线和单点会折叠，但双点 ('..') 不会折叠，因为这会在符号链接面前改变路径的含义：

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

（天真的方法会使 PurePosixPath('foo/../bar') 等同于 PurePosixPath('bar')，如果 foo 是到另一个目录的符号链接，这是错误的）

纯路径对象实现了 os.PathLike 接口，允许它们在接受接口的任何地方使用。

3.6 版更改：添加了对 os.PathLike 接口的支持。

class pathlib.PurePosixPath(*pathsegments)

PurePath 的子类，此路径风格代表非 Windows 文件系统路径：

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments 的指定与 PurePath 类似。

class pathlib.PureWindowsPath(*pathsegments)

PurePath 的子类，此路径风格代表 Windows 文件系统路径：

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')

pathsegments 的指定与 PurePath 类似。

无论您在哪个系统上运行，您都可以实例化所有这些类，因为它们不提供任何执行系统调用的操作。

一般属性

路径是不可变的和可散列的。相同风味的路径具有可比性和可排序性。这些属性尊重风味的 case-folding 语义：

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

笔记

仅在 Unix 下推荐调用 bytes。在 Windows 下，unicode 形式是文件系统路径的规范表示。

访问单个部件

要访问路径的各个“部分”（组件），请使用以下属性：

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

提供对路径逻辑祖先的访问的不可变序列：

>>> 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 版更改：父序列现在支持切片和负索引值。

PurePath.parent

路径的逻辑父级：

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

您不能越过锚点或空路径：

>>> 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 URI。如果路径不是绝对路径，则会引发 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_relative_to(*other)

返回此路径是否相对于 other 路径。

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

3.9 版中的新功能。

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)

将此路径与提供的 glob 样式模式匹配。匹配成功返回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

与其他方法一样，区分大小写遵循平台默认值：

>>> PurePosixPath('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' is not in the subpath of '/usr' OR one path is relative and the other absolute.

注意：此函数是 PurePath 的一部分，适用于字符串。它不检查或访问底层文件结构。

PurePath.with_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_stem(stem)

返回一条更改了词干的新路径。如果原始路径没有名称，则会引发 ValueError：

>>> 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>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

3.9 版中的新功能。

PurePath.with_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')

混凝土路径

具体路径是纯路径类的子类。除了后者提供的操作外，它们还提供了对路径对象进行系统调用的方法。实例化具体路径有以下三种方式：

class pathlib.Path(*pathsegments)

PurePath 的子类，此类代表系统路径风格的具体路径（实例化它会创建 PosixPath 或 WindowsPath）：

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments 的指定与 PurePath 类似。

class pathlib.PosixPath(*pathsegments)

Path 和 PurePosixPath 的子类，该类表示具体的非 Windows 文件系统路径：

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments 的指定与 PurePath 类似。

class pathlib.WindowsPath(*pathsegments)

Path 和 PureWindowsPath 的子类，该类表示具体的 Windows 文件系统路径：

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments 的指定与 PurePath 类似。

您只能实例化与您的系统相对应的类风格（允许系统调用不兼容的路径风格可能会导致应用程序中的错误或故障）：

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

方法

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

3.8 版更改： exists()、is_dir()、is_file()、is_mount() , is_symlink(), is_block_device(), is_char_device(), is_fifo(), [[#pathlib.Path.is_socket|]]Xis2socket现在返回 False 而不是对包含在操作系统级别无法表示的字符的路径引发异常。

classmethod Path.cwd()

返回一个表示当前目录的新路径对象（由 os.getcwd() 返回）：

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

classmethod Path.home()

返回一个表示用户主目录的新路径对象（由 os.path.expanduser() 和 ~ 构造返回）。如果无法解析主目录，则会引发 RuntimeError。

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

3.5 版中的新功能。

Path.stat(*, follow_symlinks=True)

返回包含有关此路径的信息的 os.stat_result 对象，例如 os.stat()。每次调用此方法时都会查找结果。

此方法通常遵循符号链接；要统计符号链接，请添加参数 follow_symlinks=False，或使用 lstat()。

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

3.10 版更改：添加了 follow_symlinks 参数。

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

更改文件模式和权限，例如 os.chmod()。

此方法通常遵循符号链接。一些 Unix 风格支持更改符号链接本身的权限；在这些平台上，您可以添加参数 follow_symlinks=False，或使用 lchmod()。

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

3.10 版更改：添加了 follow_symlinks 参数。

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() 返回的那样。如果无法解析主目录，则会引发 RuntimeError。

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

3.5 版中的新功能。

Path.glob(pattern)

在此路径表示的目录中对给定的相对模式进行全局搜索，生成所有匹配的文件（任何类型的）：

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

模式与 fnmatch 相同，增加了“**”，意思是“这个目录和所有子目录，递归地”。换句话说，它启用递归通配符：

>>> 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(): 如果路径是 挂载点 ：文件系统中已挂载不同文件系统的点，则返回 True。在 POSIX 上，该函数检查 path 的父节点 path/.. 是否在与 path 不同的设备上，或者 path/.. 和 ]path 指向同一设备上的同一个 i-node——这应该检测所有 Unix 和 POSIX 变体的挂载点。未在 Windows 上实现。

3.7 版中的新功能。

Path.is_symlink()

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

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

Path.is_socket()

如果路径指向 Unix 套接字（或指向 Unix 套接字的符号链接），则返回 True，如果指向另一种文件，则返回 False。

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

Path.is_fifo()

如果路径指向 FIFO（或指向 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 为真，则根据需要创建此路径的任何缺失父项；它们是使用默认权限创建的，没有考虑 mode（模仿 POSIX mkdir -p 命令）。

如果 parents 为 false（默认值），则缺少父项会引发 FileNotFoundError。

如果 exist_ok 为 false（默认值），如果目标目录已存在，则会引发 FileExistsError。

如果 exist_ok 为真，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.readlink()

返回符号链接指向的路径（由 os.readlink() 返回）：

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

3.9 版中的新功能。

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'

目标路径可以是绝对的或相对的。相对路径是相对于当前工作目录解释的，不是 Path 对象的目录。

3.8 更改：增加返回值，返回新的Path 实例。

Path.replace(target)

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

目标路径可以是绝对的或相对的。相对路径是相对于当前工作目录解释的，不是 Path 对象的目录。

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 之前的行为是严格的）。

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 相同的文件，可以是 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 必须为真（默认为 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

笔记

参数（链接，目标）的顺序与 os.symlink() 的顺序相反。

Path.hardlink_to(target): 将此路径设为与 target 相同文件的硬链接。

笔记

参数 (link, target) 的顺序与 os.link() 的顺序相反。

3.10 版中的新功能。

Path.link_to(target): 使 target 成为该路径的硬链接。

警告

尽管函数和参数名称有所暗示，但该函数不会使该路径成为到 target 的硬链接。参数顺序 (target, link) 与 Path.symlink_to() 和 Path.hardlink_to() 相反，但与 os.link() 的顺序相反]。

3.8 版中的新功能。

Deprecated since version 3.10: 此方法被弃用，支持 Path.hardlink_to()，因为 Path.link_to() 的参数顺序不匹配Path.symlink_to()。

Path.touch(mode=0o666, exist_ok=True): 在此给定路径创建一个文件。如果给出了 mode，它会与进程的 umask 值结合来确定文件模式和访问标志。如果文件已经存在，如果 exist_ok 为真（并且其修改时间更新为当前时间），则该函数成功，否则引发 FileExistsError。

Path.unlink(missing_ok=False)

删除此文件或符号链接。如果路径指向目录，请改用 Path.rmdir()。

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

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

3.8 版更改：添加了 missing_ok 参数。

Path.write_bytes(data)

以bytes方式打开指向的文件，写入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, newline=None)

以文本模式打开指向的文件，将data写入其中，然后关闭文件：

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

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

3.5 版中的新功能。

3.10 版更改：添加了 newline 参数。

os模块中工具的对应关系

下表将各种 os 函数映射到它们对应的 PurePath/Path 等效项。

笔记

并非下面的所有函数/方法对都是等效的。尽管有一些重叠的用例，但其中一些具有不同的语义。它们包括 os.path.abspath() 和 Path.resolve()、os.path.relpath() 和 PurePath.relative_to() 。

os 和 os.path	`pathlib`
`os.path.abspath()`	`Path.resolve()` 1
`os.chmod()`	`Path.chmod()`
`os.mkdir()`	`Path.mkdir()`
`os.makedirs()`	`Path.mkdir()`
`os.rename()`	`Path.rename()`
`os.replace()`	`Path.replace()`
`os.rmdir()`	`Path.rmdir()`
os.remove(), os.unlink()	`Path.unlink()`
`os.getcwd()`	`Path.cwd()`
`os.path.exists()`	`Path.exists()`
`os.path.expanduser()`	Path.expanduser() 和 Path.home()
`os.listdir()`	`Path.iterdir()`
`os.path.isdir()`	`Path.is_dir()`
`os.path.isfile()`	`Path.is_file()`
`os.path.islink()`	`Path.is_symlink()`
`os.link()`	`Path.hardlink_to()`
`os.symlink()`	`Path.symlink_to()`
`os.readlink()`	`Path.readlink()`
`os.path.relpath()`	`Path.relative_to()` 2
`os.stat()`	Path.stat(), Path.owner(), Path.group()
`os.path.isabs()`	`PurePath.is_absolute()`
`os.path.join()`	`PurePath.joinpath()`
`os.path.basename()`	`PurePath.name`
`os.path.dirname()`	`PurePath.parent`
`os.path.samefile()`	`Path.samefile()`
`os.path.splitext()`	`PurePath.suffix`

脚注

1: os.path.abspath() 不解析符号链接，而 Path.resolve() 解析符号链接。
2: Path.relative_to() 要求 self 作为参数的子路径，但 os.path.relpath() 不需要。

pathlib — 面向对象的文件系统路径 — Python 文档

pathlib — 面向对象的文件系统路径

基本使用

纯路径

一般属性

运营商

访问单个部件

方法和属性

混凝土路径

方法

os模块中工具的对应关系