本文介绍使用 pathlib 实现一个健壮函数：接收任意路径（文件或目录），返回按路径排序的元组列表，每个元组包含类型标识（'f' 或 'd'）和绝对路径字符串。
本文介绍使用 `pathlib` 实现一个健壮函数：接收任意路径（文件或目录），返回按路径排序的元组列表，每个元组包含类型标识（'f' 或 'd'）和绝对路径字符串。
在 Python 文件系统操作中，一个常见但易被忽视的需求是：统一处理文件与目录输入，并递归获取其全部子项（含自身），同时明确区分每一项的类型。传统方法如 os.listdir() 或 os.walk() 均假设输入必为目录，无法优雅处理单个文件作为目标的情形；而手动拼接路径、反复判断类型又容易引入逻辑错误或路径解析问题。
pathlib 模块（Python 3.4+ 内置）提供了面向对象、语义清晰的路径操作接口，是解决该问题的理想选择。其 Path.rglob("*") 方法可递归匹配所有条目（包括目录本身及其子孙），配合 is_file() 和 is_dir() 方法即可精准分类。
以下是一个生产就绪的实现：
from pathlib import Path
def list_target_contents(target: str | Path) -> list[tuple[str, str]]:
"""
列出目标路径下所有文件与目录（含自身），返回排序后的 (type, abs_path) 元组列表。
Args:
target: 文件或目录路径（支持字符串或 Path 对象）
Returns:
list[tuple[str, str]]: 每个元素为 ('f', '...') 或 ('d', '...')，
按绝对路径字符串升序排列。
"""
path = Path(target).expanduser().resolve() # 处理 ~、符号链接、相对路径
if path.is_file():
return [("f", str(path))]
if not path.is_dir():
raise ValueError(f"Target does not exist or is not accessible: {target}")
result = []
# 先添加根目录自身（符合需求：“including `target` itself”）
result.append(("d", str(path)))
# rglob("*") 匹配所有后代条目（不包含根目录本身）
for item in path.rglob("*"):
if item.is_file():
result.append(("f", str(item)))
elif item.is_dir():
result.append(("d", str(item)))
# 按绝对路径字符串排序（自然排序，非按类型分组）
return sorted(result, key=lambda x: x[1])✅ 关键设计说明：
立即学习“Python免费学习笔记（深入）”；
- expanduser().resolve() 确保路径标准化：展开 ~、解析符号链接、转为绝对路径，避免因路径格式差异导致行为不一致；
- 显式校验 path.is_dir() 后再递归，防止对不存在路径静默失败；
- rglob("*") 是核心——它天然跳过根目录，仅遍历后代，因此需显式追加根目录以满足“including target itself”的需求；
- 排序使用 sorted(..., key=lambda x: x[1])，确保结果严格按路径字符串字典序排列（如 /a/1.txt, /a/b/, /a/c.txt），而非先按类型再按路径，更符合“sorted order”原始要求。
⚠️ 注意事项：
- rglob("*") 会遍历所有层级子目录，对超大目录可能较慢。若仅需一级内容，应改用 iterdir() 并手动处理；
- 返回类型为 list[tuple[str, str]]，其中 'f' 表示文件、'd' 表示目录，便于后续逻辑分支处理；
- 不推荐用 os.scandir() 手动递归实现：代码复杂度高、易出错（如路径拼接错误、循环引用未处理）、且 pathlib 在可读性与跨平台兼容性上优势显著。
调用示例：
# 当前目录
for typ, p in list_target_contents("."):
print(f"{typ}: {p}")
# 指定文件（仅返回自身）
print(list_target_contents("README.md"))
# 输出: [('f', '/full/path/README.md')]
# 指定子目录
print(list_target_contents("src/"))综上，pathlib 不仅简化了路径操作，更通过一致的 API 抽象消除了“文件 vs 目录”的边界判断负担。本方案兼顾正确性、可读性与健壮性，是现代 Python 文件遍历任务的推荐实践。
