Python 3.14 pathlib.PurePath.full_match怎样匹配完整路径

如果你在 Python 3.14 里用 pathlib 判断一条路径是否符合完整规则，优先看 PurePath.full_match(pattern, case_sensitive=None)。它会把整个路径交给 glob 风格模式匹配，支持递归通配符 **；而 PurePath.match() 更像从路径右侧做非递归匹配，两者不能只靠替换方法名互换。

官方地址：https://docs.python.org/3.14/library/pathlib.html

我第一次把规则从字符串判断迁移到 pathlib 时，真正容易踩坑的不是调用形式，而是“完整匹配”与“右侧匹配”被误认为同一件事。下面按这个差异展开，重点处理 **、大小写和 /a/** 这几个边界。

最短结论：需要整条路径按 glob 规则匹配时使用 full_match；需要从右侧判断文件名或末尾目录时才考虑 match。注意 /a/** 不会匹配 /a，因为模式末尾的分隔符仍然需要一个路径段。

一、full_match 到底解决了什么问题

PurePath.full_match() 在 Python 3.13 加入，Python 3.14 可以直接使用。它接收一个 glob 风格模式，返回布尔值；相对模式也会参与整条路径的匹配，而不是只截取最后一段。

官方示例里，PurePath("a/b.py").full_match("a/*.py") 为真，但同一个路径使用 "*.py" 为假。这正是它和 match() 的第一处体感差异：后者对相对模式从右侧匹配，PurePath("a/b.py").match("*.py") 可以为真。

二、用 ** 覆盖多级目录，并显式控制大小写

当规则可能跨越多层目录时，** 是 full_match 最有价值的部分。它可以匹配零层或多层路径段；普通的 * 只覆盖一个路径段或一个段内的字符范围。

from pathlib import PurePosixPath

paths = [
    PurePosixPath("src/app.py"),
    PurePosixPath("src/core/app.py"),
    PurePosixPath("tests/app_test.py"),
]

for path in paths:
    # ** 可以跨越零层或多层目录，完整匹配从 src 开始的 Python 文件
    matched = path.full_match("src/**/*.py", case_sensitive=True)
    print(path, matched)

# 大小写规则可以脱离当前平台默认值单独指定
windows_style = PurePosixPath("src/App.py").full_match(
    "src/**/*.py",
    case_sensitive=False,
)
# windows_style 为 True，表示这里主动采用不区分大小写的规则
print(windows_style)

这里的 case_sensitive=True 适合配置文件、构建产物或跨机器规则：同一条规则在不同平台上不会悄悄改变含义。若业务明确允许大小写混用，可以传入 False；不传时则遵循路径风格对应的平台默认值。

还有一个范围边界：full_match 只比较路径对象的字符串结构，不检查文件是否真实存在，也不会替你完成权限判断。要查磁盘状态，仍然需要 Path.exists()、is_file() 等具体路径操作。

三、最容易误判的两个边界

我觉得最值得单独记住的是下面两个例子。它们都不是语法错误，而是模式含义和直觉不一致。

from pathlib import PurePosixPath

path = PurePosixPath("/a/b/c.py")

# full_match 的相对模式仍然要求完整路径满足模式
full = path.full_match("**/*.py")

# match 不支持真正的递归 **；它按非递归模式并从右侧匹配
right_side = path.match("b/*.py")
not_same = path.match("a/*.py")

# 官方文档特别提示：/a/** 需要分隔符后的路径段
root_child = PurePosixPath("/a").full_match("/a/**")
child = PurePosixPath("/a/b").full_match("/a/**")

# root_child 为 False，child 为 True；这不是文件是否存在导致的
print(full, right_side, not_same, root_child, child)

/a/** 看起来像“/a 以及它下面的一切”，但在 full_match 的模式语言里，末尾的 /** 仍然意味着分隔符后还要有路径段，所以 /a 不匹配。与此同时，PurePath 会丢弃尾部斜杠，/a/ 也不会因为写了斜杠就变成另一个可匹配对象。

四、full_match、match 和 glob 怎么选

换句话说，full_match 解决的是“这条路径长得是否符合规则”，而不是“按规则找到哪些文件”。把两类任务混在一个函数里，后面排查误报会很费时间。

五、旧版本项目怎么安排兼容

full_match 从 Python 3.13 起提供。如果项目最低版本还在 3.12 或更早，不要把 match() 当成完全等价的替代品，尤其是规则包含多层目录和 ** 时。更稳妥的做法是把版本差异收口到一个小函数里，明确旧版本只支持哪些规则。

import sys
from pathlib import PurePosixPath

def matches_source_tree(path_text, pattern):
    # 3.13+ 走完整匹配；旧版本先拒绝需要递归 ** 的规则，避免静默变宽
    path = PurePosixPath(path_text)
    if sys.version_info >= (3, 13):
        return path.full_match(pattern, case_sensitive=True)
    if "**" in pattern:
        raise RuntimeError("旧版本不支持此兼容层中的递归 ** 规则")
    # 旧版本只复用 match 的有限语义，调用方必须接受它从右侧匹配
    return path.match(pattern, case_sensitive=True)

这个兼容层故意没有伪装成“完全兼容”：在旧版本遇到 ** 直接报出边界，提醒调用方升级或引入经过测试的分段匹配实现。若你能统一升级到 Python 3.13 及以上，直接使用 full_match 会更容易维护。

结语：先确认匹配对象，再选方法

路径规则的第一问应该是“我要匹配整条路径，还是只关心右侧文件名”。整条路径用 full_match，跨目录时用 **，需要跨平台稳定时显式设置 case_sensitive；如果规则写成 /a/**，记得它不覆盖没有子路径段的 /a。最后再把实际文件遍历和存在性检查交给 glob()、rglob() 或 exists()。

full_match 会访问文件系统吗？

不会。它比较的是 PurePath 的路径结构；是否存在、是否可读需要另外调用具体路径方法。

为什么 full_match("*.py") 对 a/b.py 返回 False？

因为 full_match 要求完整路径符合模式，*.py 只覆盖一个路径段。要覆盖任意目录层级，可以使用 **/*.py。

match 能不能替代 full_match？

只能替代一部分简单、非递归的右侧匹配场景。涉及完整路径、跨多级目录或严格兼容时，不应把两者当成同义方法。