nbwipers

nbwipers 是一个用Rust编写的命令行工具，用于清理Jupyter笔记本。

界面和功能基于 nbstripout，而将其实现在Rust中的想法来自 nbstripout-fast。

用法

nbwipers 有几个子命令，提供与清理Jupyter笔记本相关的功能。

• clean：清理单个笔记本。这大致等同于 nbstripout。
• check：检查给定路径中的笔记本，以确定将被 clean 移除的元素。这可以在CI环境中用于强制执行干净的笔记本。
• clean-all 清理给定路径中的所有笔记本。这个命令应该谨慎使用！
• install 将 nbwipers 注册为 ipynb 文件的 git 过滤器。等同于 nbstripout --install
• uninstall 删除 nbwipers 作为 git 过滤器。
• check-install 检查 nbwipers 或 nbstripout 是否已安装在本地仓库中。这在 pre-commit 钩子中使用。

完整选项可以在 CommandLineHelp.md 中找到。

示例

要在您的仓库中设置 nbwipers 作为 git 过滤器，请使用

nbwipers install local

如果在此步骤上执行现有仓库，您可以 touch 您的笔记本，以便 git 可以检测更改。在 bash 中

for f in $(git ls-files '*.ipynb'); do touch $f; done

要检查您的文件夹中的笔记本，您可以运行以下命令

nbwipers check .

pre-commit

您可以将以下内容添加到您的 pre-commit-config.yaml 文件中，以确保 nbwipers 或 nbstripout 已安装到您的仓库中，以防止将 Jupyter 笔记本输出提交到版本控制。

  - repo: https://github.com/felixgwilliams/nbwipers-pre-commit
    rev: v0.3.4
    hooks:
      - id: nbwipers-check-install

或者，您可以在配置中使用此仓库的URL，但这将从源代码编译 nbwipers，而不是从 PyPI 获取二进制文件，因此不推荐使用。

如果您将预提交配置作为CI的一部分使用，您应该设置环境变量 NBWIPERS_CHECK_INSTALL_EXIT_ZERO，这将强制此检查通过，因为您不需要在CI环境中配置nbwipers。

动机

一个Jupyter笔记本的工作副本包含

1. 作者编写的代码。
2. 笔记本输出：表格、日志、跟踪信息、图像、小部件等等...
3. 执行次数。
4. 元数据，例如单元格是否折叠、可滚动等。

在这些数据类别中，只有第一类——作者编写的代码——应该绝对通过版本控制来跟踪，因为它是作者意图和辛勤工作的成果。其他类别的数据可能会超出作者的明确意图而改变，并且通常在版本控制方面是嘈杂的。

此外，将笔记本输出包含在版本控制中

• 使得差异难以解释，因为它们将包含大量不希望的变化。
• 增加了不同用户运行同一单元格并获得略微不同结果时的复杂合并冲突的风险。
• 增加了提交的数据量，这可能会降低存储库性能。
• 可能导致敏感数据泄露。

确保您不提交笔记本中有问题部分的有效的办法是使用nbwipers或nbstripout作为git过滤器。

git过滤器位于您的实际文件和git在您挂载和提交更改时看到的文件之间。这样，git只看到没有问题元素的文件转换版本。同时，您不必从本地副本中丢失它们。

一个例外是当您检出分支或执行git pull时，这将导致笔记本发生变化。在这种情况下，您的本地副本将被干净的版本替换，并且您将丢失单元格输出。

配置

配置目前是通过pyproject.toml文件的tool.nbwipers部分完成的。大多数命令行选项都可以在pyproject.toml、nbwipers.toml或.nbwipers.toml文件中按项目设置。如果您使用pyroject.toml，您需要将配置放在[tool.nbwipers]下。如果您使用nbwipers.toml或.nbwipers.toml，配置需要放在顶级。

例如，您可以使用extra-keys来指定要忽略的附加笔记本元素。如果您不需要Python版本或Jupyter内核的详细信息，您可以将以下内容包含在您的pyproject.toml文件中

[tool.nbwipers]
extra-keys = ["metadata.kernelspec", "metadata.language_info.version"]

nbwipers.toml或.nbwipers.toml的等效项只是

extra-keys = ["metadata.kernelspec", "metadata.language_info.version"]

这对于协作来说很有用，因为精确的Python版本和分配给内核的名称是短暂的，并且可能因人而异。

测试覆盖率

要测试覆盖率，请使用以下命令

cargo tarpaulin -o stdout -o html -o lcov --engine llvm

使用llvm引擎意味着集成测试有助于覆盖率。

致谢

nbwipers依赖于来自几个项目的灵感和代码。有关使用了哪些代码的项目，请参阅LICENSE中的第三方声明。

nbstripout

从Jupyter和IPython笔记本中剥离输出

nbstripout是在版本控制环境中与Jupyter笔记本一起工作的无价工具。本项目构成了本项目接口和逻辑的基础，也是测试示例的来源。

nbstripout-fast

使用 Rust 编写的一个比 nbstripout 更快的版本（当然）。

nbstripout-fast，像这个项目一样，使用 Rust 实现了 nbstripout 的功能，同时允许在 YAML 文件中进行仓库级别的配置。

通过 nbwipers，我希望重新创建 nbstripout-fast 的想法，但使其能够作为 git 过滤器安装，并通过 pyproject.toml 进行配置。

ruff

一个极快的 Python 代码检查器和代码格式化工具，由 Rust 编写。

Ruff 正迅速成为 Python 代码的代码检查器，归功于其性能、广泛的规则集以及其易用性。它是配置组织和文件发现的组织的一个确定的知识来源。Jupyter Notebooks 的模式以及一些文件发现代码是从 Ruff 中改编的。