nb-path 1.9

一个赋予文件系统操作超能力的 Python 路径库

nb_path: 赋予文件系统操作超能力的 Python 路径库

nb_path 是一个对 Python 标准库 pathlib.Path 的超级增强版。它完全继承了 pathlib 的所有优雅特性（包括 / 操作符），并在此基础上无缝集成了 shutil 的高级文件操作、zipfile 的压缩解压、hashlib 的哈希计算、importlib 的动态模块导入，甚至还内置了 grep 搜索和 rsync 风格的目录同步等强大功能。

它的设计哲学是：将所有与路径相关的常用操作，都变成路径对象自身的方法，从而实现极致流畅的链式调用。

🆚 与 pathlib 对比

nb_path 不仅仅是 pathlib 的简单封装，而是一个功能强大的超集。

功能 (Feature)	pathlib.Path	nb_path.NbPath	优势说明
基本路径操作	✅	✅	nb_path 完全继承并兼容 pathlib 的所有功能
高级文件/目录操作	❌	✅	内置 copy_to, move_to, delete, empty 等方法
确保父目录存在	❌	✅	ensure_parent() 方法，避免 FileNotFoundError
压缩与解压	❌	✅	zip_to() 和 unzip_to()，轻松处理归档文件
内容搜索 (grep)	❌	✅	grep() 方法，在文件或目录中进行高效文本搜索
目录智能同步	❌	✅	sync_to() 方法，实现 rsync 风格的增量同步
网络文件下载	❌	✅	download_from_url() 方法，直接将文件下载到路径
项目根目录发现	❌	✅	find_project_root() 和 find_git_root()，告别路径烦恼
动态模块导入	❌	✅	import_as_module()，是插件化开发的利器
便捷的临时文件/目录	❌	✅	tempfile() 和 tempdir() 上下文管理器，自动清理
实用工具集	❌	✅	内置 hash(), size_human(), expand() 等多种便捷工具

✨ 核心特性

• 完全兼容 pathlib: 无缝迁移，零学习成本。
• 强大的文件/目录操作: copy_to, move_to, delete, empty, ensure_parent 等，比 shutil 更直观。
• 智能压缩与解压: zip_to() 和 unzip_to()，轻松处理 ZIP 文件。
• 内置 grep 功能: grep() 方法，可在文件或整个目录中进行高效的文本/正则搜索。
• 目录智能同步: sync_to() 方法，一个轻量级的 rsync，可智能同步两个目录。
• 网络文件下载: download_from_url()，直接将文件从 URL 下载到指定路径。
• 项目根目录发现: find_project_root() 和 find_git_root()，告别烦人的相对路径计算。
• 动态模块导入: import_as_module()，可以将任何 .py 文件作为模块动态导入，是插件化开发的利器。
• 便捷的临时文件/目录: tempfile() 和 tempdir() 上下文管理器，返回功能完备的 NbPath 对象，自动清理。
• 实用工具集: hash(), size_human(), expand() 等，满足日常开发中的各种小需求。

🚀 安装

pip install nb-path

⚡ 快速上手：优雅的链式调用

想象一下这个常见的自动化任务：下载一个 ZIP 包，解压，找到特定文件，处理其内容，然后保存到项目的 output 目录。

使用 nb_path，整个过程可以一气呵成：

from nb_path import NbPath

# 模拟一个数据源 URL
MOCK_URL = "https://example.com/data.zip" 

# 在一个临时的、会自动清理的工作区中执行所有操作
with NbPath.tempdir(prefix="data-processing-") as workspace:
    print(f"创建临时工作区: {workspace}")

    # 核心操作：下载 -> 解压 -> 在解压目录中查找 -> 读取 -> 处理
    unzipped_dir = (workspace / "downloaded.zip") \
        .download_from_url(MOCK_URL, overwrite=True) \
        .unzip_to(workspace / "unzipped")

    processed_content = (workspace / "downloaded.zip") \
        unzipped_dir.rglob_files("data.txt")[0] \
        .read_text() \
        .upper()

    # 将处理结果保存到项目的输出目录
    output_file = (NbPath.self_py_dir() / "output" / "report.txt") \
        .ensure_parent() \
        .write_text(processed_content)

    print(f"处理完成，结果已保存至: {output_file}")

print("临时工作区已自动清理。")

这个例子完美展示了 nb_path 的核心优势：高内聚、高可读、高效率。

📖 API 使用指南

以下是 nb_path 主要功能的详细介绍和示例。

1. 文件与目录操作

from nb_path import NbPath

# 确保父目录存在，然后创建一个空文件
p = NbPath("data/reports/2024/sales.csv").ensure_parent().touch()

# 复制文件
p_copy = p.copy_to("data/reports/2024/sales_backup.csv")

# 移动文件
p_moved = p_copy.move_to("data/archive/sales_2024.csv")

# 删除文件
p_moved.delete()

# 创建一个目录并清空它
report_dir = NbPath("data/reports").empty()

# 递归删除整个目录树
report_dir.delete()

2. 文本与数据读写

nb_path 继承了 pathlib 的 read_text/write_text 和 read_bytes/write_bytes，并为文本操作默认使用 utf-8 编码。

p = NbPath("config.txt")

# 写入文本
p.write_text("setting=enabled")

# 读取文本
content = p.read_text()
print(content)  # "setting=enabled"

3. 搜索与发现

递归查找文件/目录

src_dir = NbPath("./my_project")

# 查找所有 Python 文件
py_files = src_dir.rglob_files("*.py")

# 查找所有名为 'tests' 的目录
test_dirs = src_dir.rglob_dirs("tests")

grep：在文件中搜索内容

这是 nb_path 的一个“杀手级”功能。

project_dir = NbPath("./my_project")

# 1. 在所有 .py 文件中搜索字符串 "import requests"
for result in project_dir.grep("import requests", file_pattern="*.py", is_regex=False):
    print(f"{result.path.name}:{result.line_number}: {result.line_content.strip()}")

# 2. 使用正则表达式查找所有 Flask 路由
for result in project_dir.grep(r"@app\.route\(['\"](.*?)['\"]\)", file_pattern="*.py"):
    print(f"发现路由: {result.match.group(1)}")

4. 项目与路径导航

# 自动找到当前文件所在的 Git 仓库的根目录
git_root = NbPath(__file__).find_git_root()

# 根据标记文件（如 'pyproject.toml'）找到项目根目录
project_root = NbPath().find_project_root()

# 展开环境变量和用户目录
# NbPath('$HOME/.config/my_app').expand() -> /home/user/.config/my_app
# NbPath('~/.bashrc').expand() -> /home/user/.bashrc
config_path = NbPath("$HOME/.config").expand()

5. 压缩与解压

assets_dir = NbPath("./assets")

# 将整个目录压缩成一个 ZIP 文件
zip_file = assets_dir.zip_to("assets_archive.zip", overwrite=True)

# 将 ZIP 文件解压到指定目录
unzipped_dir = zip_file.unzip_to("./unzipped_assets")

6. 网络与同步

从 URL 下载文件

# 下载一个图片并显示进度条
image_path = NbPath("python_logo.png").download_from_url(
    "https://www.python.org/static/community_logos/python-logo-master-v3-TM.png",
    overwrite=True
)
print(f"图片已下载至: {image_path}, 大小: {image_path.size_human()}")

sync_to：智能同步目录

此方法只会复制新增或被修改的文件，非常高效。

source_dir = NbPath("./src")
deploy_dir = NbPath("./deploy")

# 将源目录同步到部署目录
# delete_extraneous=True 会删除部署目录中多余的文件（镜像同步）
source_dir.sync_to(deploy_dir, delete_extraneous=True, ignore_patterns=['*.pyc', '__pycache__'])

7. 临时文件与目录

nb_path 提供了比标准库更易用的上下文管理器，并且返回的是 NbPath 对象。

# 创建一个临时的配置文件
with NbPath.tempfile(suffix=".txt", prefix="config_") as tmp_file:
    print(f"临时文件: {tmp_file}")
    tmp_file.write_text("temporary setting")
    # 此代码块结束时，文件会被自动删除

# 创建一个临时的插件工作区
with NbPath.tempdir(prefix="plugin_") as tmp_dir:
    print(f"临时目录: {tmp_dir}")
    (tmp_dir / "plugin.py").write_text("print('hello from plugin')")
    # 此代码块结束时，目录及其所有内容会被自动删除

8. 动态模块导入 (高级功能)

这是 nb_path 最独特的功能之一，对于构建插件系统或动态加载脚本非常有用。

from nb_path import NbPathPyImporter

# 将任意 .py 文件作为模块导入
plugin_path = NbPathPyImporter("./plugins/my_plugin.py")
my_plugin_module = plugin_path.import_as_module()

# 调用插件中的函数
my_plugin_module.run()

# 自动导入一个目录下的所有 .py 文件
plugins_dir = NbPathPyImporter("./plugins")
plugins_dir.auto_import_pyfiles_in_dir()

9. 实用工具

p = NbPath("my_large_file.dat")
p.write_bytes(b"0" * 5 * 1024 * 1024) # 写入 5MB 数据

# 获取文件大小（字节）
print(p.size())  # 5242880

# 获取人类可读的文件大小
print(p.size_human())  # "5.0 MB"

# 计算文件哈希值
print(p.hash())  # 'f3a3535...' (sha256)
print(p.hash('md5')) # 'a74f6...' (md5)

贡献

欢迎任何形式的贡献！如果您有好的想法、功能建议或发现了 Bug，请随时提交 Issues 或 Pull Requests。

许可证

本项目基于 MIT License 开源。