Python pathlib.Path.rglob 如何排除隐藏目录：递归扫描与过滤边界

用 pathlib.Path.rglob() 扫描项目目录时，最容易踩的坑不是“能不能递归”，而是隐藏目录会不会被一起带进结果。稳妥做法是先让 rglob() 产生路径，再按每个路径的 parts 过滤隐藏目录；如果只想排除目录、保留 .env.example 这类隐藏文件，就不要只检查文件名开头。

rglob() 本身不会替你定义“隐藏目录”的业务规则。把路径拆成 parts，在结果层排除任意祖先目录以点号开头的路径，边界最清楚。

rglob 返回什么，决定了过滤应该放在哪里

Path.rglob('*.py') 返回的是匹配到的 Path 对象，不是只包含文件名的字符串。它会从起点目录向下查找，匹配模式负责“找什么”，却不负责表达你的目录策略。

from pathlib import Path

root = Path('demo-project')
for path in root.rglob('*.py'):
    print(path)

如果目录结构里有 .venv/lib/python3.12/site.py 或 .cache/generated.py，这些路径仍可能出现在匹配结果里。此时再用 path.name.startswith('.') 过滤不够，因为它只能看最后一级名称，挡不住隐藏祖先目录。

按 parts 排除任意层级的隐藏目录

下面的函数保留普通目录中的 Python 文件，同时跳过路径中任意一级以点号开头的目录。path.parts 让规则不依赖操作系统的路径分隔符，过滤条件也能直接读出来。

from pathlib import Path


def visible_python_files(root: Path) -> list[Path]:
    files = []
    for path in root.rglob('*.py'):
        if path.is_file() and not any(part.startswith('.') for part in path.parts):
            files.append(path)
    return files

这里有一个容易忽略的细节：如果 root 本身是 .workspace，它也会出现在 path.parts 中，于是所有结果都会被排除。更适合通用工具的写法，是只检查相对于根目录的部分。

def visible_python_files(root: Path) -> list[Path]:
    files = []
    for path in root.rglob('*.py'):
        relative = path.relative_to(root)
        hidden_parent = any(
            part.startswith('.') for part in relative.parts[:-1]
        )
        if path.is_file() and not hidden_parent:
            files.append(path)
    return files

想保留隐藏文件时，目录和文件必须分开判断

例如项目里有 .env.example，它是隐藏文件，不一定应该被排除。过滤祖先目录时使用 relative.parts[:-1]，故意不检查最后一个文件名，就能保留它：

root = Path('demo-project')
for path in root.rglob('*'):
    relative = path.relative_to(root)
    in_hidden_dir = any(part.startswith('.') for part in relative.parts[:-1])
    if path.is_file() and not in_hidden_dir:
        print(path)

若需求变成“隐藏目录和隐藏文件都不要”，再额外增加 not path.name.startswith('.')。不要把两种规则揉成一个模糊的正则，否则后面很难解释为什么配置样例被过滤掉。

符号链接、根目录和结果验收

扫描工具还要明确是否跟随符号链接、根目录是否允许是隐藏目录，以及结果是否需要排序。目录规模较大时，建议先把路径转成相对路径，再排序后交给后续打包或分析逻辑：

def scan(root: Path) -> list[Path]:
    result = []
    for path in root.rglob('*.py'):
        relative = path.relative_to(root)
        if path.is_file() and not any(
            part.startswith('.') for part in relative.parts[:-1]
        ):
            result.append(relative)
    return sorted(result)

验收时至少准备三组样本：普通目录中的文件、隐藏目录中的文件、普通目录中的隐藏文件。预期分别是保留、排除、保留。这样测试的是过滤边界，而不是只证明 rglob() 能递归。

常见问题

path.name.startswith('.') 能替代 parts 判断吗？

不能。它只判断当前路径最后一级名称，无法排除 .cache/generated.py 这样的隐藏祖先目录。

为什么示例要先 relative_to(root)？

这样不会把隐藏的根目录名称误当成子目录规则，过滤范围只针对根目录之下的相对路径。

是否应该直接用字符串拼接路径？

不建议。Path 的 parts、relative_to() 和 is_file() 能把平台差异和文件类型判断写得更明确。

小结

rglob() 负责递归匹配，隐藏目录是否跳过应由调用方定义。以根目录为基准取得相对路径，检查 parts[:-1]，再结合 is_file()，既能跳过任意层级的隐藏目录，也能按需保留 .env.example 这类隐藏文件。