使用 pathlib 实现 Python 跨平台安全路径处理

纯路径与具体路径：选择正确的类

pathlib 将其 API 分为两个家族。PurePath 及其子类（PurePosixPath, PureWindowsPath）仅执行字符串级别的计算，如连接、分割和后缀替换，不发出任何系统调用。Path, PosixPath 和 WindowsPath 继承自纯类，并添加了 I/O 方法，如 open, read_text 和 mkdir。

关键的跨平台洞察是，你可以在任何操作系统上实例化任何纯风味。在 Linux 机器上，你不能创建 WindowsPath，因为这会尝试 Windows 特定的系统调用，但 PureWindowsPath 在所有地方都有效。这允许你在仅限 Unix 的测试环境中验证、规范化或转换 Windows UNC 路径，而无需触及文件系统。

根据 pathlib 文档，当你想在 Unix 机器上操作 Windows 路径或需要保证代码从不执行 OS 访问操作时，纯路径很有用。具体路径应保留在你实际需要与文件系统交互的时刻。

from pathlib import Path, PureWindowsPath, PurePosixPath, UnsupportedOperation, NotImplementedError  # noqa: F401 (illustrative imports only)

检查存在性和类型而不产生竞争条件

exists(), is_file() 和 is_dir() 通过底层调用 stat 返回布尔值。它们对于快速诊断很方便，但引入了检查到使用的竞争条件：另一个进程或线程可能在检查和随后的 open 之间删除或替换文件。pathlib 文档指出，如果系统调用失败，具体路径方法可能会引发 OSError。

更安全的模式是在 try/except OSError 块中直接尝试操作。如果你必须先检查（例如，决定是创建还是读取），请尽量缩小检查和动作之间的时间窗口，并将动作包裹在异常处理中。

from pathlib import Path

target = Path('output/report.csv')

# Preferred: attempt and handle failure
try:
    content = target.read_text(encoding='utf-8')
except FileNotFoundError:
    print(f'{target} does not exist yet')
except PermissionError:
    print(f'No permission to read {target}')
except OSError as exc:
    print(f'OS error on {target}: {exc}')

使用 with_suffix, with_name 和 with_stem 安全地更改扩展名

with_suffix 替换现有后缀或在不存在时追加一个。传递空字符串会完全移除后缀。该方法只查看最后一个点段，所以对于名为 archive.tar.gz 的文件，后缀是 '.gz'，with_suffix('.bz2') 生成 archive.tar.bz2，而不是 archive.bz2。

with_name 替换整个最终组件，包括任何后缀。with_stem（在 Python 3.9 中添加）仅更改后缀之前的部分，保留它。两者都在路径没有名称组件时引发 ValueError，例如像 C:/ 这样的裸驱动器根目录。

常见的错误是假设 with_suffix 将 .tar.gz 等多点扩展名作为一个单元处理。它不会；你必须为复合扩展名使用 with_name 或手动词干构造。

from pathlib import PureWindowsPath

p = PureWindowsPath('c:/Downloads/archive.tar.gz')
print(p.with_suffix('.bz2'))   # c:/Downloads/archive.tar.bz2
print(p.with_stem('backup'))   # c:/Downloads/backup.gz
print(p.with_name('new.txt'))  # c:/Downloads/new.txt

使用 iterdir 和 glob 导航目录树

glob 接受 shell 风格的模式；'' 表示此目录及所有子目录递归，且 recursive=True 是默认值，因此 glob('/*.py') 搜索整个树而无需显式标志。rglob 是 glob('**/pattern') 的简写。

iterdir 和 glob 的结果以任意顺序返回，并且可能包含隐藏条目（Unix 上的点文件，Windows 上具有隐藏属性的文件）。如果你需要确定性排序，请显式对结果进行排序。glob 是否跟随符号链接可能因 Python 版本而异，因此请针对你使用的版本对照 pathlib 文档验证行为，而不是假设固定规则。

from pathlib import Path

data_dir = Path('output')
for p in sorted(data_dir.iterdir()):
    if p.is_file() and p.suffix == '.csv':
        print(p.resolve())

# Recursive search for all Python files
for py in data_dir.rglob('*.py'):
    print(py)

解析路径：absolute, resolve, expanduser 和 home

absolute() 前置当前工作目录，但不规范化 dot-dot 组件或跟随符号链接。resolve() 消除 '..' 组件并跟随遇到的每个符号链接，返回规范路径。在 Python 3.6 中添加了 strict 参数；strict=True 时，缺失的路径或符号链接循环会引发 OSError，而默认的 strict=False 尽可能解析并附加剩余部分。

expanduser() 将前导波浪号或波浪号用户结构替换为相应的家目录。home() 是一个类方法，直接返回当前用户家路径。两者在家目录无法确定时都会引发 RuntimeError。

from pathlib import Path

p = Path('docs/../setup.py')
print(p.resolve())          # /home/user/project/setup.py

q = Path('~/notes.txt')
print(q.expanduser())       # /home/user/notes.txt

print(Path.home())          # /home/user

跨平台属性：drive, root, parts 和大小写敏感性

drive 属性返回 Windows 驱动器字母或 UNC 共享字符串，在 POSIX 上始终为空。root 返回前导斜杠或反斜杠。parts 将路径分解为组件元组，在 Windows 上将驱动器和根组合为一个条目。

PureWindowsPath 在相等性和排序比较中折叠大小写，因此 PureWindowsPath('FOO') 等于 PureWindowsPath('foo')。PurePosixPath 区分大小写。这一区别在构建必须在不同平台上保持一致行为的集合或字典中的路径时很重要。

from pathlib import PureWindowsPath, PurePosixPath

w = PureWindowsPath('C:/Users/alice/docs')
print(w.parts)   # ('C:\\', 'Users', 'alice', 'docs')
print(w.drive)   # 'c:'
print(w.root)    # '\\'

print(PureWindowsPath('FOO') == PureWindowsPath('foo'))  # True
print(PurePosixPath('FOO') == PurePosixPath('foo'))      # False

处理路径错误：OSError, UnsupportedOperation 和平台限制

触及文件系统的具体路径方法在底层系统调用失败时引发 OSError（或子类如 FileNotFoundError, PermissionError）。resolve(strict=True) 对不存在的路径或符号链接循环引发 OSError。从 Python 3.13 开始，PosixPath 在 Windows 上实例化时引发 UnsupportedOperation，WindowsPath 在非 Windows 平台上引发它。以前这些引发 NotImplementedError。

UnsupportedOperation 继承自 NotImplementedError，因此捕获 NotImplementedError 也会捕获它，但显式处理更清晰。编写必须在两个平台上运行的代码时，优先使用 Path 而不是 PosixPath 或 WindowsPath，以避免意外实例化错误的风格。

from pathlib import Path

try:
    Path('/nonexistent').resolve(strict=True)
except OSError as exc:
    print(f'Resolution failed: {exc}')

# On Python 3.13+, this raises UnsupportedOperation on Linux:
# from pathlib import WindowsPath
# WindowsPath('C:/')

将 pathlib 对象与 os 模块函数集成

PurePath 从 Python 3.6 起实现了 os.PathLike，因此任何 pathlib 对象都可以直接传递给 os.listdir, os.stat, os.remove, os.symlink 等函数而无需转换。这允许你将 pathlib 的便利性与缺乏 pathlib 等效项的 os 级操作混合使用。

os.name 返回 'posix' 或 'nt'，这是当 pathlib 本身未暴露足够信息时在平台上分支的标准方式，例如检查 os.symlink 在 Windows 上是否需要提升权限，或者函数是否支持 dir_fd 参数。

import os
from pathlib import Path

p = Path('/tmp/example')
# pathlib object works directly with os functions
os.makedirs(p, exist_ok=True)
os.remove(p / 'old.txt')

if os.name == 'nt':
    print('Windows: symlinks need Developer Mode')
else:
    print('Unix: symlinks available without elevation')