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

3.4 版新增。

源代码： Lib/pathlib.py

此模块提供了一些类，它们表示文件系统路径，其语义适用于不同的操作系统。路径类分为纯路径和具体路径，前者提供纯粹的计算操作，不涉及 I/O，而后者继承自纯路径，但也提供 I/O 操作。

Inheritance diagram showing the classes available in pathlib. The most basic class is PurePath, which has three direct subclasses: PurePosixPath, PureWindowsPath, and Path. Further to these four classes, there are two classes that use multiple inheritance: PosixPath subclasses PurePosixPath and Path, and WindowsPath subclasses PureWindowsPath and Path.

如果你以前从未使用过此模块，或者不确定哪个类适合你的任务，那么 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'

纯路径¶

纯路径对象提供路径处理操作，这些操作实际上并不访问文件系统。有三种方法可以访问这些类，我们也称之为 *风格*

class pathlib.PurePath(*pathsegments)¶

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

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

pathsegments 的每个元素可以是表示路径段的字符串，也可以是实现 os.PathLike 接口的对象，其中 __fspath__() 方法返回一个字符串，例如另一个路径对象

>>> 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 上，当遇到带根的相对路径段（例如 r'\foo'）时，不会重置驱动器

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

虚假斜杠和单个点会被折叠，但双点 ('..') 和前导双斜杠 ('//') 不会，因为这会出于各种原因（例如符号链接、UNC 路径）改变路径的含义

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> 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 文件系统路径，包括 UNC 路径

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments 的指定方式类似于 PurePath。

无论你运行的是什么系统，你都可以实例化所有这些类，因为它们不提供任何执行系统调用的操作。

通用属性¶

路径是不可变的，并且是可哈希的。相同风格的路径是可比较和可排序的。这些属性尊重风格的字母折叠语义

>>> 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()。如果参数是绝对路径，则忽略之前的路径。在 Windows 上，当参数是带根的相对路径（例如 r'\foo'）时，不会重置驱动器

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

路径对象可以在任何接受实现 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
'\\'

如果路径以两个以上连续的斜杠开头，则 PurePosixPath 会将其折叠。

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

注意

此行为符合 *The Open Group Base Specifications Issue 6*，第 4.11 Pathname Resolution 段。

“以两个连续斜杠开头的路径名可以以实现定义的方式解释，但两个以上的前导斜杠应视为单个斜杠。”

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

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

此方法是基于字符串的；它既不访问文件系统，也不特殊处理“..”段。以下代码是等效的：

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

3.9 版新增。

3.12 版后已弃用，将在 3.14 版中删除: 不推荐传递其他参数；如果提供，它们将与 *other* 连接。

PurePath.is_reserved()¶

使用 PureWindowsPath 时，如果该路径在 Windows 下被视为保留路径，则返回 True，否则返回 False。使用 PurePosixPath 时，始终返回 False。

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

对保留路径的文件系统调用可能会神秘地失败或产生意外的影响。

PurePath.joinpath(*pathsegments)¶

调用此方法等效于将路径与给定的每个 *pathsegments* 依次组合。

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

将此路径与提供的 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

如果模式是绝对路径，则路径必须是绝对路径，并且整个路径必须匹配

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

模式可以是另一个路径对象；这可以加快对多个文件匹配相同模式的速度

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

注意

此方法不支持递归通配符“**”（它的作用类似于非递归的“*”）。

版本 3.12 中的变化：接受实现 os.PathLike 接口的对象。

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

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

将case_sensitive设置为True或False可覆盖此行为。

版本 3.12 中的变化：添加了case_sensitive参数。

PurePath.relative_to(other, walk_up=False)¶

计算此路径相对于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 941, in relative_to
    raise ValueError(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.

当walk_up为 false（默认值）时，路径必须以other开头。当参数为 true 时，可以添加..条目以形成相对路径。在所有其他情况下，例如引用不同驱动器的路径，都会引发ValueError。

>>> p.relative_to('/usr', walk_up=True)
PurePosixPath('../etc/passwd')
>>> p.relative_to('foo', walk_up=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(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.

警告

此函数是PurePath的一部分，并且可以使用字符串。它不检查或访问底层文件结构。这可能会影响walk_up选项，因为它假设路径中不存在符号链接；如果需要解析符号链接，请先调用resolve()。

版本 3.12 中的变化：添加了walk_up参数（旧行为与walk_up=False相同）。

自版本 3.12 起弃用，将在版本 3.14 中移除：不建议传递额外的 positional 参数；如果提供，它们将与other连接。

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

返回一个新路径，其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')

PurePath.with_segments(*pathsegments)¶

通过组合给定的pathsegments来创建相同类型的新路径对象。每当创建派生路径时，例如从parent和relative_to()创建派生路径时，都会调用此方法。子类可以覆盖此方法以将信息传递给派生路径，例如

from pathlib import PurePosixPath

class MyPath(PurePosixPath):
    def __init__(self, *pathsegments, session_id):
        super().__init__(*pathsegments)
        self.session_id = session_id

    def with_segments(self, *pathsegments):
        return type(self)(*pathsegments, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id)  # 42

版本 3.12 中的新功能。

具体路径¶

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

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。

扩展和解析路径¶

classmethod Path.home()¶

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

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

版本 3.5 中的新功能。

Path.expanduser()¶

返回一个新路径，其中 ~ 和 ~user 结构已扩展，如 os.path.expanduser() 返回的那样。如果无法解析主目录，则会引发 RuntimeError。

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

版本 3.5 中的新功能。

classmethod Path.cwd()¶

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

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

Path.absolute()¶

使路径成为绝对路径，不进行规范化或解析符号链接。返回一个新的路径对象

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

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

返回符号链接指向的路径（如 os.readlink() 返回的那样）

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

3.9 版新增。

查询文件类型和状态¶

在 3.8 版更改: exists()、is_dir()、is_file()、is_mount()、is_symlink()、is_block_device()、is_char_device()、is_fifo()、is_socket() 现在对于包含在操作系统级别不可表示的字符的路径返回 False，而不是引发异常。

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.lstat()¶: 与 Path.stat() 类似，但如果路径指向符号链接，则返回符号链接的信息而不是其目标的信息。

Path.exists(*, follow_symlinks=True)¶

如果路径指向现有文件或目录，则返回 True。

此方法通常会跟随符号链接；要检查符号链接是否存在，请添加参数 follow_symlinks=False。

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

在 3.12 版更改: 添加了 follow_symlinks 参数。

Path.is_file()¶

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

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

Path.is_dir()¶

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

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

Path.is_symlink()¶

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

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

Path.is_junction()¶: 如果路径指向连接点，则返回 True，对于任何其他类型的文件，则返回 False。目前只有 Windows 支持连接点。

版本 3.12 中的新功能。

Path.is_mount()¶: 如果路径是挂载点（文件系统中已挂载不同文件系统的点），则返回 True。在 POSIX 上，该函数检查路径的父级 path/.. 是否与路径位于不同的设备上，或者 path/.. 和路径是否指向同一设备上的同一 i-node——这应该可以检测所有 Unix 和 POSIX 变体的挂载点。在 Windows 上，挂载点被认为是驱动器号根目录（例如 c:\）、UNC 共享（例如 \\server\share）或已挂载文件系统的目录。

3.7 版新增。

在 3.12 版更改: 添加了 Windows 支持。

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.samefile(other_path)¶

返回此路径是否与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.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.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.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.write_text(data, encoding=None, errors=None, newline=None)¶

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

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

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

版本 3.5 中的新功能。

在 3.10 版更改: 添加了newline参数。

Path.write_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.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')

子级以任意顺序生成，并且不包括特殊条目 '.' 和 '..'。如果在创建迭代器后从目录中删除或添加文件，则不指定是否包含该文件的路径对象。

如果路径不是目录或无法访问，则会引发 OSError。

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

在此路径表示的目录中，使用给定的相对 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.is_dir()，并传播引发的任何 OSError 异常。来自扫描目录的后续 OSError 异常将被抑制。

默认情况下，或者当仅限关键字的参数 case_sensitive 设置为 None 时，此方法使用平台特定的区分大小写规则匹配路径：通常，在 POSIX 上区分大小写，在 Windows 上不区分大小写。将 case_sensitive 设置为 True 或 False 可以覆盖此行为。

注意

在大型目录树中使用 “**” 模式可能会消耗大量时间。

使用参数 self、pattern 引发审计事件 pathlib.Path.glob。

在 3.11 版更改: 如果 pattern 以路径名组件分隔符（sep 或 altsep）结尾，则仅返回目录。

版本 3.12 中的变化：添加了case_sensitive参数。

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

递归地对给定的相对 pattern 进行全局匹配。这类似于在 pattern 前面加上 “**/” 来调用 Path.glob()，其中 patterns 与 fnmatch 中的相同

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

默认情况下，或者当仅限关键字的参数 case_sensitive 设置为 None 时，此方法使用平台特定的区分大小写规则匹配路径：通常，在 POSIX 上区分大小写，在 Windows 上不区分大小写。将 case_sensitive 设置为 True 或 False 可以覆盖此行为。

使用参数 self、pattern 引发审计事件 pathlib.Path.rglob。

在 3.11 版更改: 如果 pattern 以路径名组件分隔符（sep 或 altsep）结尾，则仅返回目录。

版本 3.12 中的变化：添加了case_sensitive参数。

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

通过自顶向下或自底向上遍历目录树，生成目录树中的文件名。

对于以 self 为根的目录树中的每个目录（包括 self 但不包括“.”和“..”），该方法都会生成一个 3 元组 (dirpath, dirnames, filenames)。

dirpath 是当前正在遍历的目录的 Path，dirnames 是 dirpath 中子目录名称的字符串列表（不包括 '.' 和 '..'），filenames 是 dirpath 中非目录文件名称的字符串列表。要获取 dirpath 中文件或目录的完整路径（以 self 开头），请执行 dirpath / name。列表是否排序取决于文件系统。

如果可选参数 top_down 为 true（默认值），则会在生成任何子目录的三元组之前生成目录的三元组（自顶向下遍历目录）。如果 top_down 为 false，则会在生成所有子目录的三元组之后生成目录的三元组（自底向上遍历目录）。无论 top_down 的值是多少，都会在遍历目录及其子目录的三元组之前检索子目录列表。

当 top_down 为 true 时，调用者可以原地修改 dirnames 列表（例如，使用 del 或切片赋值），并且 Path.walk() 将仅递归到名称保留在 dirnames 中的子目录。这可用于修剪搜索、强制执行特定的访问顺序，甚至在 Path.walk() 恢复之前通知 Path.walk() 调用者创建或重命名的目录。当 top_down 为 false 时修改 dirnames 对 Path.walk() 的行为没有影响，因为在将 dirnames 中的目录生成给调用者时，已经生成了 dirnames 中的目录。

默认情况下，os.scandir() 中的错误将被忽略。如果指定了可选参数 on_error，则它应该是一个可调用对象；它将使用一个参数（OSError 实例）进行调用。可调用对象可以处理错误以继续遍历，也可以重新引发错误以停止遍历。请注意，文件名可作为异常对象的 filename 属性使用。

默认情况下，Path.walk() 不跟随符号链接，而是将它们添加到 filenames 列表中。将 follow_symlinks 设置为 true 可以解析符号链接并根据其目标将它们分别放置在 dirnames 和 filenames 中，从而访问符号链接指向的目录（如果支持）。

注意

请注意，如果链接指向自身的父目录，则将 follow_symlinks 设置为 true 可能会导致无限递归。 Path.walk() 不会跟踪它已访问过的目录。

注意

Path.walk() 假定它遍历的目录在执行期间不会被修改。例如，如果 dirnames 中的目录已被符号链接替换，并且 follow_symlinks 为 false，Path.walk() 仍会尝试进入该目录。要防止此类行为，请根据需要从 dirnames 中删除目录。

注意

与 os.walk() 不同，如果 follow_symlinks 为 false，Path.walk() 会在 filenames 中列出指向目录的符号链接。

此示例显示每个目录中所有文件使用的字节数，同时忽略 __pycache__ 目录

from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')

下一个示例是 shutil.rmtree() 的简单实现。自底向上遍历树至关重要，因为 rmdir() 不允许在目录为空之前删除它

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

版本 3.12 中的新功能。

创建文件和目录¶

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

参见

open()、write_text() 和 write_bytes() 方法通常用于创建文件。

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，则除非给定路径已存在于文件系统中并且不是目录（与 POSIX mkdir -p 命令的行为相同），否则不会引发 FileExistsError。

在 3.5 版更改: 添加了 exist_ok 参数。

Path.symlink_to(target, target_is_directory=False)¶

使此路径成为指向 target 的符号链接。

在 Windows 上，符号链接表示文件或目录，并且不会动态地转换为目标。如果目标存在，则将创建与之匹配的符号链接类型。否则，如果 target_is_directory 为 true，则将符号链接创建为目录，否则创建为文件符号链接（默认值）。在非 Windows 平台上，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 相同文件的硬链接。

注意

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

在 3.10 版中添加。

重命名和删除¶

Path.rename(target)¶

将此文件或目录重命名为给定的 target，并返回一个指向 target 的新 Path 实例。在 Unix 上，如果 target 存在并且是文件，则如果用户有权限，它将被静默替换。在 Windows 上，如果 target 存在，则会引发 FileExistsError。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 对象的目录。

它是根据 os.rename() 实现的，并提供相同的保证。

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

Path.replace(target)¶

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

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

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

Path.unlink(missing_ok=False)¶

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

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

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

版本 3.8 中的变化：添加了 missing_ok 参数。

Path.rmdir()¶: 删除此目录。该目录必须为空。

权限和所有权¶

Path.owner()¶: 返回拥有该文件用户的名称。如果在系统数据库中找不到该文件的用户标识符 (UID)，则会引发 KeyError。

Path.group()¶: 返回拥有该文件用户组的名称。如果在系统数据库中找不到该文件的组标识符 (GID)，则会引发 KeyError。

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.lchmod(mode)¶: 类似于 Path.chmod()，但如果路径指向符号链接，则会更改符号链接的模式而不是其目标的模式。

与 `os` 模块中的工具的对应关系¶

下表列出了各种 os 函数及其对应的 PurePath/Path 等效项。

注意

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

`os` 和 `os.path`	`pathlib`
`os.path.abspath()`	`Path.absolute()` [1]
`os.path.realpath()`	`Path.resolve()`
`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.walk()`	`Path.walk()`
`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()`	`PurePath.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.stem` 和 `PurePath.suffix`

脚注

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

基本用法¶

纯路径¶

通用属性¶

运算符¶

访问各个部分¶

方法和属性¶

具体路径¶

扩展和解析路径¶

查询文件类型和状态¶

读取和写入文件¶

读取目录¶

创建文件和目录¶

重命名和删除¶

权限和所有权¶

与 `os` 模块中的工具的对应关系¶

目录

上一主题

下一主题

本页

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

基本用法¶

纯路径¶

通用属性¶

运算符¶

访问各个部分¶

方法和属性¶

具体路径¶

扩展和解析路径¶

查询文件类型和状态¶

读取和写入文件¶

读取目录¶

创建文件和目录¶

重命名和删除¶

权限和所有权¶

与 os 模块中的工具的对应关系¶

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

与 `os` 模块中的工具的对应关系¶