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

在 3.4 版本加入。

源代码: Lib/pathlib/

---

此模块提供表示文件系统路径的类，其语义适用于不同的操作系统。路径类分为 纯路径（提供纯计算操作而无需 I/O）和 具体路径（继承自纯路径但也提供 I/O 操作）。

如果您以前从未使用过此模块，或者不确定哪个类适合您的任务，那么 Path 很可能是您需要的。它会为代码运行的平台实例化一个 具体路径。

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

1. 如果您想在 Unix 机器上操作 Windows 路径（反之亦然）。在 Unix 上运行时，您无法实例化 WindowsPath，但可以实例化 PureWindowsPath。

2. 您希望确保您的代码只操作路径，而无需实际访问操作系统。在这种情况下，实例化其中一个纯类可能很有用，因为这些类根本没有任何访问操作系统的操作。

参见

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'

异常

exception pathlib.UnsupportedOperation

当对路径对象调用不支持的操作时引发的异常，继承自 NotImplementedError。

在 3.13 版本加入。

纯路径

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

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/hosts')
PurePosixPath('/etc/hosts')

pathsegments 的指定方式与 PurePath 类似。

class pathlib.PureWindowsPath(*pathsegments)

PurePath 的子类，此路径风格表示 Windows 文件系统路径，包括 UNC 路径

>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> 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.parser

用于底层路径解析和连接的 os.path 模块的实现：可以是 posixpath 或 ntpath。

在 3.13 版本加入。

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

这通常被称为文件扩展名。

3.14 版本发生变更: 单个点（”.”）被视为有效后缀。

PurePath.suffixes

路径后缀的列表，通常称为文件扩展名

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

3.14 版本发生变更: 单个点（”.”）被视为有效后缀。

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

3.13 版本发生变更: 包含冒号或以点或空格结尾的 Windows 路径名被视为保留。UNC 路径可能被保留。

从 3.13 版本开始弃用，将在 3.15 版本中移除: 此方法已弃用；请使用 os.path.isreserved() 来检测 Windows 上的保留路径。

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

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

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

参见

模式语言 文档。

与其他方法一样，大小写敏感性遵循平台默认值

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

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

在 3.13 版本加入。

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

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

此方法类似于 full_match()，但不允许空模式（会引发 ValueError），不支持递归通配符“**”（它表现得像非递归的“*”），如果提供了相对模式，则从右侧进行匹配

>>> 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 版本发生变更: pattern 参数接受一个 路径类对象。

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 版本中已移除: 传递额外的定位参数已弃用；如果提供，它们将与 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')

3.14 版本发生变更: 单个点（”.”）被视为有效后缀。在之前的版本中，如果提供了单个点，则会引发 ValueError。

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/hosts')
PosixPath('/etc/hosts')

pathsegments 的指定方式与 PurePath 类似。

3.13 版本发生变更: 在 Windows 上引发 UnsupportedOperation。在之前的版本中，改为引发 NotImplementedError。

class pathlib.WindowsPath(*pathsegments)

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

>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')

pathsegments 的指定方式与 PurePath 类似。

3.13 版本发生变更: 在非 Windows 平台上引发 UnsupportedOperation。在之前的版本中，改为引发 NotImplementedError。

您只能实例化与您的系统相对应的类风味（在不兼容的路径风味上允许系统调用可能导致应用程序中的错误或失败）

>>> 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__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system

如果系统调用失败（例如因为路径不存在），某些具体路径方法可能会引发 OSError。

解析和生成 URI

具体路径对象可以从符合 RFC 8089 的“file”URI 创建并表示。

备注

文件 URI 在具有不同 文件系统编码 的机器之间不可移植。

classmethod Path.from_uri(uri)

从解析“file”URI 返回一个新的路径对象。例如

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

在 Windows 上，DOS 设备和 UNC 路径可以从 URI 解析

>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> 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://///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')

如果 URI 不以 file: 开头，或解析的路径不是绝对路径，则会引发 ValueError。

在 3.13 版本加入。

3.14 版本发生变更: 如果 URL 授权与本地主机名匹配，则将其丢弃。否则，如果授权不为空或 localhost，则在 Windows 上返回 UNC 路径（与以前相同），在其他平台上引发 ValueError。

Path.as_uri()

将路径表示为“file”URI。如果路径不是绝对路径，则会引发 ValueError。

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

从 3.14 版本开始弃用，将在 3.19 版本中移除: 从 PurePath 而不是 Path 调用此方法是可能的，但已弃用。该方法使用 os.fsencode() 使其严格不纯。

扩展和解析路径

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，则会引发 OSError。如果 strict 为 False，则路径会尽可能地解析，任何剩余部分都将附加而不检查其是否存在。

3.6 版本发生变更: 添加了 strict 参数（3.6 之前的行为是严格的）。

3.13 版本发生变更: 符号链接循环被视为其他错误：在严格模式下引发 OSError，在非严格模式下不引发异常。在之前的版本中，无论 strict 的值如何，都会引发 RuntimeError。

Path.readlink()

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

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

在 3.9 版本中新增。

3.13 版本发生变更: 如果 os.readlink() 不可用，则引发 UnsupportedOperation。在之前的版本中，引发 NotImplementedError。

查询文件类型和状态

3.8 版本发生变更: exists()、is_dir()、is_file()、is_mount()、is_symlink()、is_block_device()、is_char_device()、is_fifo()、is_socket() 现在返回 False，而不是因为路径包含操作系统无法表示的字符而引发异常。

3.14 版本发生变更: 上述方法现在返回 False，而不是从操作系统引发任何 OSError 异常。在之前的版本中，会引发某些类型的 OSError 异常，而其他类型的则被抑制。新行为与 os.path.exists()、os.path.isdir() 等一致。使用 stat() 来检索文件状态而不抑制异常。

Path.stat(*, follow_symlinks=True)

返回一个 os.stat_result 对象，其中包含此路径的信息，类似于 os.stat()。结果在每次调用此方法时查找。

此方法通常遵循符号链接；要对符号链接进行 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。False 将在路径无效、不可访问或缺失时返回。使用 Path.stat() 来区分这些情况。

此方法通常遵循符号链接；要检查符号链接是否存在，请添加参数 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(*, follow_symlinks=True)

如果路径指向一个普通文件，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是普通文件时返回。使用 Path.stat() 来区分这些情况。

此方法通常遵循符号链接；要排除符号链接，请添加参数 follow_symlinks=False。

3.13 版本发生变更: 添加了 follow_symlinks 参数。

Path.is_dir(*, follow_symlinks=True)

如果路径指向一个目录，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是目录时返回。使用 Path.stat() 来区分这些情况。

此方法通常遵循符号链接；要排除指向目录的符号链接，请添加参数 follow_symlinks=False。

3.13 版本发生变更: 添加了 follow_symlinks 参数。

Path.is_symlink()

如果路径指向符号链接，即使该符号链接已损坏，也返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是符号链接时返回。使用 Path.stat() 来区分这些情况。

Path.is_junction()

如果路径指向一个连接点，则返回 True，对于任何其他类型的文件则返回 False。目前只有 Windows 支持连接点。

3.12 新版功能.

Path.is_mount()

如果路径是 挂载点，即文件系统中挂载了不同文件系统的点，则返回 True。在 POSIX 上，此函数检查 path 的父级 path/.. 是否与 path 位于不同的设备上，或者 path/.. 和 path 是否指向同一设备上的相同 inode — 这应该能检测到所有 Unix 和 POSIX 变体的挂载点。在 Windows 上，挂载点被认为是驱动器盘符的根（例如 c:\）、UNC 共享（例如 \\server\share）或已挂载的文件系统目录。

在 3.7 版本加入。

3.12 版本发生变更: 增加了 Windows 支持。

Path.is_socket()

如果路径指向 Unix 套接字，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是 Unix 套接字时返回。使用 Path.stat() 来区分这些情况。

Path.is_fifo()

如果路径指向 FIFO，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是 FIFO 时返回。使用 Path.stat() 来区分这些情况。

Path.is_block_device()

如果路径指向块设备，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是块设备时返回。使用 Path.stat() 来区分这些情况。

Path.is_char_device()

如果路径指向字符设备，则返回 True。False 将在路径无效、不可访问或缺失，或者它指向的不是字符设备时返回。使用 Path.stat() 来区分这些情况。

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

一个 PathInfo 对象，支持查询文件类型信息。该对象公开了缓存其结果的方法，这有助于在根据文件类型进行切换时减少所需的系统调用次数。例如

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

如果路径是由 Path.iterdir() 生成的，则此属性会使用从扫描父目录中获取的一些文件类型信息进行初始化。仅仅访问 Path.info 不会执行任何文件系统查询。

要获取最新信息，最好调用 Path.is_dir()、is_file() 和 is_symlink()，而不是此属性的方法。没有办法重置缓存；相反，您可以通过 p = Path(p) 创建一个带有空信息缓存的新路径对象。

在 3.14 版本加入。

读写文件

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, newline=None)

返回指向文件的解码内容作为字符串

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

文件被打开然后关闭。可选参数与 open() 中的含义相同。

在 3.5 版本加入。

3.13 版本发生变更: 添加了 newline 参数。

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)

以文本模式打开指向的文件，将 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 参数。

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

在此路径表示的目录中对给定的相对 pattern 进行 glob 匹配，生成所有匹配的文件（任何类型）

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

参见

模式语言 文档。

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

默认情况下，或当 recurse_symlinks 仅限关键字参数设置为 False 时，此方法遵循符号链接，但展开“**”通配符时除外。将 recurse_symlinks 设置为 True 以始终遵循符号链接。

会引发一个 审计事件 pathlib.Path.glob，带参数 self 和 pattern。

3.12 版本发生变更: 增加了 case_sensitive 参数。

3.13 版本中的变化: 增加了 recurse_symlinks 参数。

3.13 版本中的变化: pattern 参数接受 path-like object。

3.13 版本中的变化: 扫描文件系统时引发的任何 OSError 异常都会被抑制。在以前的版本中，此类异常在许多情况下会被抑制，但并非所有情况。

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

递归地全局匹配给定的相对 pattern。这就像在 pattern 前面加上 “**/” 来调用 Path.glob()。

参见

模式语言 和 Path.glob() 文档。

会引发一个 审计事件 pathlib.Path.rglob，带参数 self 和 pattern。

3.12 版本发生变更: 增加了 case_sensitive 参数。

3.13 版本中的变化: 增加了 recurse_symlinks 参数。

3.13 版本中的变化: pattern 参数接受 path-like object。

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

通过自上而下或自下而上地遍历目录树来生成目录树中的文件名。

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

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

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

当 top_down 为真时，调用者可以就地修改 dirnames 列表（例如，使用 del 或切片赋值），而 Path.walk() 将只递归到 dirnames 中保留名称的子目录。这可以用于修剪搜索，或施加特定的访问顺序，甚至可以告知 Path.walk() 调用者在再次恢复 Path.walk() 之前创建或重命名的目录。当 top_down 为假时，修改 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 为真，则根据需要创建此路径的任何缺失父目录；它们以默认权限创建，不考虑 mode（模仿 POSIX mkdir -p 命令）。

如果 parents 为假（默认值），则缺少父目录会引发 FileNotFoundError。

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

如果 exist_ok 为真，则不会引发 FileExistsError，除非给定路径已存在于文件系统中且不是目录（与 POSIX mkdir -p 命令的行为相同）。

3.5 版本中的变化: 添加了 exist_ok 参数。

Path.symlink_to(target, target_is_directory=False)

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

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

3.13 版本中的变化: 如果 os.symlink() 不可用，则会引发 UnsupportedOperation。在以前的版本中，会引发 NotImplementedError。

Path.hardlink_to(target)

使此路径成为与 target 相同文件的硬链接。

备注

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

在 3.10 版本加入。

3.13 版本中的变化: 如果 os.link() 不可用，则会引发 UnsupportedOperation。在以前的版本中，会引发 NotImplementedError。

复制、移动和删除

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

将此文件或目录树复制到给定的 target，并返回一个指向 target 的新 Path 实例。

如果源是一个文件，则如果目标是现有文件，它将被替换。如果源是符号链接且 follow_symlinks 为 true (默认)，则复制符号链接的目标。否则，将在目标位置重新创建符号链接。

如果 preserve_metadata 为假（默认值），则只保证复制目录结构和文件数据。将 preserve_metadata 设置为真以确保在支持的情况下复制文件和目录权限、标志、上次访问和修改时间以及扩展属性。此参数在 Windows 上复制文件时无效（元数据总是被保留）。

备注

在操作系统和文件系统支持的情况下，此方法执行轻量级复制，其中数据块仅在修改时才复制。这被称为写时复制。

在 3.14 版本加入。

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

将此文件或目录树复制到给定的 target_dir 中，target_dir 应该是一个现有目录。其他参数的处理方式与 Path.copy() 相同。返回一个指向副本的新 Path 实例。

在 3.14 版本加入。

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

将此文件或目录树移动到给定 target，并返回指向 target 的新 Path 实例。

如果 target 不存在，则将创建它。如果此路径和 target 都是现有文件，则 target 将被覆盖。如果两个路径指向相同的文件或目录，或者 target 是非空目录，则会引发 OSError。

如果两个路径都在同一个文件系统上，则使用 os.replace() 执行移动。否则，此路径将被复制（保留元数据和符号链接），然后删除。

在 3.14 版本加入。

Path.move_into(target_dir)

将此文件或目录树移动到给定的 target_dir 中，target_dir 应该是一个现有目录。返回一个指向移动路径的新 Path 实例。

在 3.14 版本加入。

Path.unlink(missing_ok=False)

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

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

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

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

Path.rmdir()

删除此目录。目录必须为空。

权限和所有权

Path.owner(*, follow_symlinks=True)

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

此方法通常会跟随符号链接；要获取符号链接的所有者，请添加参数 follow_symlinks=False。

3.13 版本中的变化: 如果 pwd 模块不可用，则会引发 UnsupportedOperation。在早期版本中，会引发 NotImplementedError。

3.13 版本发生变更: 添加了 follow_symlinks 参数。

Path.group(*, follow_symlinks=True)

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

此方法通常会跟随符号链接；要获取符号链接的组，请添加参数 follow_symlinks=False。

3.13 版本中的变化: 如果 grp 模块不可用，则会引发 UnsupportedOperation。在早期版本中，会引发 NotImplementedError。

3.13 版本发生变更: 添加了 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.lchmod(mode)

类似于 Path.chmod()，但是如果路径指向符号链接，则更改符号链接的模式而不是其目标的模式。

模式语言

以下通配符在 full_match()、glob() 和 rglob() 的模式中受支持

** (整个分段)

匹配任意数量的文件或目录分段，包括零个。

* (整个分段)

匹配一个文件或目录分段。

* (分段的一部分)

匹配任意数量的非分隔符字符，包括零个。

?

匹配一个非分隔符字符。

[seq]

匹配 seq 中的一个字符，其中 seq 是一系列字符。支持范围表达式；例如，[a-z] 匹配任何小写 ASCII 字母。可以组合多个范围：[a-zA-Z0-9_] 匹配任何 ASCII 字母、数字或下划线。

[!seq]

匹配 seq 中不存在的一个字符，其中 seq 遵循上述规则。

对于字面量匹配，将元字符用方括号括起来。例如，"[?]" 匹配字符 "?"。

“**” 通配符启用递归全局匹配。一些示例

模式	含义
“**/*”	任何至少有一个分段的路径。
“**/*.py”	任何最终分段以 “.py” 结尾的路径。
“assets/**”	任何以 “assets/” 开头的路径。
“assets/**/*”	任何以 “assets/” 开头的路径，不包括 “assets/” 本身。

备注

使用 “**” 通配符进行全局匹配会遍历树中的每个目录。大型目录树可能需要很长时间才能搜索。

3.13 版本中的变化: 以 “**” 结尾的模式进行全局匹配会返回文件和目录。在以前的版本中，只返回目录。

在 Path.glob() 和 rglob() 中，可以在模式末尾添加斜杠以仅匹配目录。

3.11 版本中的变化: 以路径名组件分隔符（sep 或 altsep）结尾的模式进行全局匹配只返回目录。

与 glob 模块的比较

Path.glob() 和 Path.rglob() 接受的模式和生成的结果与 glob 模块略有不同

1. 在 pathlib 中，以点开头的文件没有特殊之处。这就像将 include_hidden=True 传递给 glob.glob()。

2. 在 pathlib 中，“**” 模式组件始终是递归的。这就像将 recursive=True 传递给 glob.glob()。

3. 在 pathlib 中，“**” 模式组件默认不跟随符号链接。此行为在 glob.glob() 中没有等效项，但您可以将 recurse_symlinks=True 传递给 Path.glob() 以获得兼容的行为。

4. 像所有 PurePath 和 Path 对象一样，从 Path.glob() 和 Path.rglob() 返回的值不包含尾随斜杠。

5. pathlib 的 path.glob() 和 path.rglob() 返回的值包含 path 作为前缀，这与 glob.glob(root_dir=path) 的结果不同。

6. pathlib 的 path.glob() 和 path.rglob() 返回的值可能包含 path 本身，例如在全局匹配 “**” 时，而 glob.glob(root_dir=path) 的结果从不包含对应于 path 的空字符串。

与 os 和 os.path 模块的比较

pathlib 使用 PurePath 和 Path 对象实现路径操作，因此它被称为是 面向对象的。另一方面，os 和 os.path 模块提供处理低级 str 和 bytes 对象的函数，这是一种更 过程化 的方法。一些用户认为面向对象风格更具可读性。

os 中的许多函数和 os.path 支持 bytes 路径和 相对于目录描述符的路径。这些功能在 pathlib 中不可用。

Python 的 str 和 bytes 类型，以及 os 和 os.path 模块的一部分，是用 C 编写的，速度非常快。pathlib 是用纯 Python 编写的，通常较慢，但很少慢到需要关注。

pathlib 的路径规范化比 os.path 稍微更具主观性和一致性。例如，os.path.abspath() 从路径中删除 “..” 段，如果涉及符号链接，这可能会改变其含义，而 Path.absolute() 保留这些段以提高安全性。

pathlib 的路径规范化可能使其不适用于某些应用程序

1. pathlib 将 Path("my_folder/") 规范化为 Path("my_folder")，这会改变路径在提供给各种操作系统 API 和命令行工具时的含义。具体来说，缺少尾随分隔符可能会使路径被解析为文件或目录，而不是仅目录。

2. pathlib 将 Path("./my_program") 规范化为 Path("my_program")，这会改变路径在用作可执行搜索路径（例如在 shell 中或启动子进程时）时的含义。具体来说，路径中缺少分隔符可能会强制它在 PATH 中查找，而不是在当前目录中查找。

由于这些差异，pathlib 不能完全替代 os.path。

对应工具

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

os 和 os.path	pathlib
os.path.dirname()	PurePath.parent
os.path.basename()	PurePath.name
os.path.splitext()	PurePath.stem, PurePath.suffix
os.path.join()	PurePath.joinpath()
os.path.isabs()	PurePath.is_absolute()
os.path.relpath()	PurePath.relative_to() [1]
os.path.expanduser()	Path.expanduser() [2]
os.path.realpath()	Path.resolve()
os.path.abspath()	Path.absolute() [3]
os.path.exists()	Path.exists()
os.path.isfile()	Path.is_file()
os.path.isdir()	Path.is_dir()
os.path.islink()	Path.is_symlink()
os.path.isjunction()	Path.is_junction()
os.path.ismount()	Path.is_mount()
os.path.samefile()	Path.samefile()
os.getcwd()	Path.cwd()
os.stat()	Path.stat()
os.lstat()	Path.lstat()
os.listdir()	Path.iterdir()
os.walk()	Path.walk() [4]
os.mkdir(), os.makedirs()	Path.mkdir()
os.link()	Path.hardlink_to()
os.symlink()	Path.symlink_to()
os.readlink()	Path.readlink()
os.rename()	Path.rename()
os.replace()	Path.replace()
os.remove(), os.unlink()	Path.unlink()
os.rmdir()	Path.rmdir()
os.chmod()	Path.chmod()
os.lchmod()	Path.lchmod()

脚注

[1]

os.path.relpath() 调用 abspath() 将路径转换为绝对路径并删除 “..” 部分，这可能会改变其含义，而 PurePath.relative_to() 是一个词法操作，当其输入的锚点不同时（例如，一个路径是绝对路径而另一个是相对路径），会引发 ValueError。

[2]

os.path.expanduser() 如果无法解析主目录，则返回未更改的路径，而 Path.expanduser() 会引发 RuntimeError。

[3]

os.path.abspath() 在不解析符号链接的情况下移除“..”组件，这可能会改变路径的含义，而 Path.absolute() 则保留路径中的任何“..”组件。

[4]

os.walk() 在将路径分类为 dirnames 和 filenames 时总是遵循符号链接，而 Path.walk() 在 follow_symlinks 为假（默认值）时将所有符号链接分类到 filenames 中。

协议

pathlib.types 模块提供用于静态类型检查的类型。

在 3.14 版本加入。

class pathlib.types.PathInfo

一个描述 Path.info 属性的 typing.Protocol。实现可以从它们的方法返回缓存结果。

exists(*, follow_symlinks=True)

如果路径是现有文件或目录，或任何其他类型的文件，则返回 True；如果路径不存在，则返回 False。

如果 follow_symlinks 为 False，则对于符号链接返回 True，而不检查其目标是否存在。

is_dir(*, follow_symlinks=True)

如果路径是目录，或者指向目录的符号链接，则返回 True；如果路径是（或指向）任何其他类型的文件，或者它不存在，则返回 False。

如果 follow_symlinks 为 False，则仅当路径是目录时才返回 True（不跟随符号链接）；如果路径是任何其他类型的文件，或者它不存在，则返回 False。

is_file(*, follow_symlinks=True)

如果路径是文件，或者指向文件的符号链接，则返回 True；如果路径是（或指向）目录或其他非文件，或者它不存在，则返回 False。

如果 follow_symlinks 为 False，则仅当路径是文件时才返回 True（不跟随符号链接）；如果路径是目录或其他非文件，或者它不存在，则返回 False。

is_symlink()

如果路径是符号链接（即使已损坏），则返回 True；如果路径是目录或任何类型的文件，或者它不存在，则返回 False。