Python 3.15 RC2 的 pathlib parent_mode 怎么兼容旧代码

如果项目用 Path.mkdir(parents=True) 创建多级目录，Python 3.15 RC2 带来的 parent_mode 解决的是一个很具体的兼容问题：目标目录和中间目录不一定应该使用同一套权限。升级时不必重写所有调用点，但要先分清新参数的作用范围。

保留旧代码的关键是：Python 3.15 及以上直接传 parent_mode；旧版本则逐级创建缺失目录。mode 仍只表示目标目录权限，最终结果还要经过进程 umask。

官方变更说明：https://docs.python.org/3.15/whatsnew/3.15.html

parent_mode 到底改变了哪一层目录权限

过去的 Path.mkdir(mode=..., parents=True) 中，mode 主要描述最后一级目标目录；缺失的父目录按默认权限创建，并继续受 umask 影响。Python 3.15 新增的 parent_mode 只接管这些“中间级”目录，目标目录的 mode 不变。

例如 Path("var/app/cache").mkdir(mode=0o750, parent_mode=0o755, parents=True)，意图是让 cache 使用 750，而缺失的 var、app 使用 755。若这些目录已经存在，调用不会替它们重新 chmod；若系统设置了严格的 umask，实际权限还可能比参数更窄。

兼容 Python 3.14 及更早版本的最小写法

旧解释器不认识 parent_mode 关键字，直接调用会抛出 TypeError。对于只关心“目录能否创建”的项目，去掉参数通常够用；但部署目录、缓存目录或共享目录有明确权限要求时，建议按能力检测分支处理。

下面的函数先检查当前 Path.mkdir 是否暴露新参数。旧版本进入手动分支，从已经存在的祖先目录向下创建；最后一级使用 leaf_mode，其余新建目录使用 parent_mode。

from inspect import signature
from pathlib import Path

def mkdir_compat(target: Path, leaf_mode: int = 0o750, parent_mode: int = 0o755) -> None:
    # 文件占用了目标路径时，保持 mkdir 的失败语义。
    if target.exists() and not target.is_dir():
        raise FileExistsError(target)

    # Python 3.15 直接交给 pathlib，umask 仍由操作系统处理。
    if "parent_mode" in signature(Path.mkdir).parameters:
        target.mkdir(
            mode=leaf_mode,
            parents=True,
            exist_ok=True,
            parent_mode=parent_mode,
        )
        return

    # 旧版本没有 parent_mode，只逐级创建缺失目录来保留权限意图。
    missing = []
    current = target
    while not current.exists():
        missing.append(current)
        current = current.parent

    # 从最上层开始，避免依赖 parents=True 的默认父目录权限。
    for directory in reversed(missing):
        mode = leaf_mode if directory == target else parent_mode
        directory.mkdir(mode=mode, exist_ok=True)

迁移时先确认这三个边界

还有一个容易忽略的点：手动逐级创建只是兼容策略，不等于绕过文件系统权限。并发部署时，两个进程同时创建同一级目录仍可能遇到权限或竞态异常；exist_ok=True 只能处理“最终它是目录”的情况，不能吞掉所有 OSError。

把兼容函数放进项目的完整片段

调用侧只需要表达业务意图，不必知道当前解释器版本：

from pathlib import Path

# 缓存目录让应用可读写，父级目录保持更宽的遍历权限。
cache_dir = Path("var/app/cache/v1")
mkdir_compat(cache_dir, leaf_mode=0o750, parent_mode=0o755)

# 目录创建成功后，再写入应用生成的缓存文件。

如果项目最低版本已经确定为 Python 3.15，可以直接使用新签名；如果还要支持旧版，保留上面的封装更稳妥。升级验证时同时覆盖“所有目录都不存在”“目标目录已存在”和“目标路径是普通文件”三种情况，才能看出兼容分支是否真的保留了旧行为。

常见问题

parent_mode 会修改已经存在的父目录吗？

不会。它只用于本次调用中新建的中间目录；已有目录的权限需要单独通过权限管理逻辑调整。

mode 和 parent_mode 可以设置成不同值吗？

可以，这正是该参数的用途。通常把目标目录设置得更收敛，把父级目录设置为允许遍历但不代表可以写入的模式。

旧版本直接删除 parent_mode 行不行？

如果只要求目录存在，可以；如果依赖中间目录的精确权限，就会回到旧的默认创建行为，应采用逐级创建的兼容函数。