Jupyter nbconvert元数据掩码失效及无警告实现问题咨询

我尝试清除Jupyter笔记本的所有输出及几乎全部元数据。执行以下命令：

jupyter nbconvert --ClearOutputPreprocessor.enabled=True \
--ClearMetadataPreprocessor.enabled=True \
--ClearMetadataPreprocessor.preserve_nb_metadata_mask="{('language_info', 'name'), 'kernelspec'}" \
--to=notebook --log-level=ERROR my_notebook.ipynb

得到了预期的元数据结果：

"metadata": {
  "kernelspec": {
   "display_name": "my-kernel",
   "language": "python",
   "name": "my-kernel"
  },
  "language_info": {
   "name": "python"
  }
 }

但同时出现以下警告：

/usr/local/miniconda/lib/python3.7/site-packages/traitlets/traitlets.py:2935: FutureWarning: --ClearMetadataPreprocessor.preserve_nb_metadata_mask={('language_info', 'name'), 'kernelspec'} for containers is deprecated in traitlets 5.0. You can pass `--ClearMetadataPreprocessor.preserve_nb_metadata_mask item` ... multiple times to add items to a list.
  FutureWarning,

根据警告提示及官方文档，我修改命令为：

jupyter nbconvert --ClearOutputPreprocessor.enabled=True \
--ClearMetadataPreprocessor.enabled=True \
--ClearMetadataPreprocessor.preserve_nb_metadata_mask="{('language_info', 'name')}" \
--ClearMetadataPreprocessor.preserve_nb_metadata_mask="{'kernelspec'}" \
--to=notebook --log-level=ERROR my_notebook.ipynb

但修改后笔记本的元数据为空：

"metadata": {}

咨询问题 #

1. 该问题是否由依赖版本导致？
2. 如何无警告实现元数据掩码功能？

1. 是否由依赖版本导致？ #

是。问题核心在于traitlets 5.0+版本废弃了直接传递集合格式参数的方式，要求通过多次传递单个项来构建列表，但nbconvert的ClearMetadataPreprocessor无法正确解析你传递的字符串格式元组（比如"{('language_info', 'name')}"），导致掩码规则完全失效，最终所有元数据被清除。

2. 无警告实现元数据掩码的方法 #

有两种可靠方案：

方案一：使用配置文件（推荐）

创建或修改jupyter_nbconvert_config.py配置文件，写入以下内容：

c.ClearMetadataPreprocessor.enabled = True
c.ClearMetadataPreprocessor.preserve_nb_metadata_mask = [
    ('language_info', 'name'),
    'kernelspec'
]

之后执行简化后的命令即可：

jupyter nbconvert --ClearOutputPreprocessor.enabled=True \
--to=notebook --log-level=ERROR my_notebook.ipynb

方案二：调整命令行参数格式

放弃元组字符串格式，用.分隔多层元数据路径，直接传递单个项：

jupyter nbconvert --ClearOutputPreprocessor.enabled=True \
--ClearMetadataPreprocessor.enabled=True \
--ClearMetadataPreprocessor.preserve_nb_metadata_mask="language_info.name" \
--ClearMetadataPreprocessor.preserve_nb_metadata_mask="kernelspec" \
--to=notebook --log-level=ERROR my_notebook.ipynb

这种格式符合traitlets 5.0+的要求，不会触发警告，同时能正确保留指定元数据。

内容的提问来源于stack exchange，提问作者whoopscheckmate