当前位置：首页 > 文章列表 > 科技周边 > 业界新闻 > Python 3.15 RC2 的 pathlib parent_mode 怎么兼容旧代码

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

来源：17golang原创 2026-09-10 11:00:25 0浏览收藏

如果项目用 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 只在 parents=True 新建中间目录时生效。
目标目录继续使用 mode，已经存在的目录不会被本次调用改权限。
兼容旧版时不要简单删除新参数，严格权限场景应改为手动逐级创建。

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

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

Python 3.15 pathlib Path.mkdir 中 mode、parent_mode、umask 对目标目录和中间目录的权限关系 — 图1：Path.mkdir 的 mode 负责目标目录，parent_mode 只负责 parents=True 时新建的中间目录。

例如 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。对于只关心“目录能否创建”的项目，去掉参数通常够用；但部署目录、缓存目录或共享目录有明确权限要求时，建议按能力检测分支处理。

Python pathlib parent_mode 兼容方案中能力检测、Python 3.15 原生分支和旧版本逐级创建分支 — 图2：兼容函数先判断 parent_mode 能力，两条实现路径最终汇合到相同的目录权限策略。

下面的函数先检查当前 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)

迁移时先确认这三个边界

检查项	实际含义	迁移建议
`parents`	为 False 时不会创建缺失父目录，`parent_mode` 也没有作用。	需要多级目录时显式写 True。
`exist_ok`	只控制已存在目标目录是否报错，不会更新已有目录权限。	权限修正另行调用 chmod，并记录变更。
`umask`	参数是创建意图，最终模式由系统权限掩码共同决定。	在目标操作系统的测试环境查看 stat 结果。

还有一个容易忽略的点：手动逐级创建只是兼容策略，不等于绕过文件系统权限。并发部署时，两个进程同时创建同一级目录仍可能遇到权限或竞态异常；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，可以直接使用新签名；如果还要支持旧版，保留上面的封装更稳妥。升级验证时同时覆盖“所有目录都不存在”“目标目录已存在”和“目标路径是普通文件”三种情况，才能看出兼容分支是否真的保留了旧行为。