配置

配置 nbdev 并引导 Notebook 导出

配置 nbdev

nbdev 可高度定制，这得益于此模块中定义的配置系统。与 nbdev 配置交互有两种方式

请继续阅读以了解它们如何工作。

源码

nbdev_create_config

 nbdev_create_config (repo:str=None, branch:str=None, user:str=None,
                      author:str=None, author_email:str=None,
                      description:str=None, path:str='.',
                      cfg_name:str='settings.ini', lib_name='%(repo)s',
                      git_url='https://github.com/%(user)s/%(repo)s',
                      custom_sidebar:<function bool_arg>=False,
                      nbs_path:pathlib.Path='nbs',
                      lib_path:pathlib.Path=None,
                      doc_path:pathlib.Path='_docs', tst_flags='notest',
                      version='0.0.1',
                      doc_host='https://%(user)s.github.io',
                      doc_baseurl='/%(repo)s', keywords='nbdev jupyter
                      notebook python', license='apache2',
                      copyright:str=None, status='3', min_python='3.9',
                      audience='Developers', language='English',
                      recursive:<function bool_arg>=True,
                      black_formatting:<function bool_arg>=False,
                      readme_nb='index.ipynb', title='%(lib_name)s',
                      allowed_metadata_keys='',
                      allowed_cell_metadata_keys='',
                      jupyter_hooks:<function bool_arg>=False,
                      clean_ids:<function bool_arg>=True,
                      clear_all:<function bool_arg>=False,
                      cell_number:<function bool_arg>=True,
                      put_version_in_init:<function bool_arg>=True,
                      update_pyproject:<function bool_arg>=True,
                      skip_procs:str='')

创建一个配置文件。

类型 默认值 详情
repo str None 仓库名称
branch str None 仓库默认分支
user str None 仓库用户名
author str None 包作者姓名
author_email str None 包作者电子邮件地址
description str None 包的简短摘要
path str . 创建配置文件的路径
cfg_name str settings.ini 要创建的配置文件名称
lib_name str %(repo)s 包名称
git_url str https://github.com/%(user)s/%(repo)s 仓库 URL
custom_sidebar bool_arg False 使用自定义 sidebar.yml?
nbs_path Path nbs Notebook 路径
lib_path Path None 包根目录路径（默认：repo 中的 - 替换为 _）
doc_path Path _docs 渲染后文档路径
tst_flags str notest 测试标志
version str 0.0.1 此发布的版本
doc_host str https://%(user)s.github.io 文档主机名
doc_baseurl str /%(repo)s 文档基础 URL
keywords str nbdev jupyter notebook python 包关键词
license str apache2 包的许可证
copyright str None 包的版权信息，默认为“当前年份起，作者”
status str 3 开发状态 PyPI 分类器
min_python str 3.9 最低 Python 版本 PyPI 分类器
audience str 开发者 目标受众 PyPI 分类器
language str 英语 语言 PyPI 分类器
recursive bool_arg True 在 notebook globs 中包含子文件夹?
black_formatting bool_arg False 使用 black 格式化库?
readme_nb str index.ipynb 要导出为仓库 README 的 Notebook
title str %(lib_name)s Quarto 网站标题
allowed_metadata_keys str 保留主 notebook 元数据中的键列表
allowed_cell_metadata_keys str 保留单元格级别元数据中的键列表
jupyter_hooks bool_arg False 运行 Jupyter 钩子?
clean_ids bool_arg True 从纯文本表示中移除 ID?
clear_all bool_arg False 移除所有单元格元数据和单元格输出?
cell_number bool_arg True 将单元格编号添加到导出的文件
put_version_in_init bool_arg True 将版本添加到 nbdev_export 中主要的 init.py
update_pyproject bool_arg True 创建/更新 pyproject.toml 并使用正确的项目名称
skip_procs str 要跳过的处理器列表，以逗号分隔

上表也提供了 nbdev 设置的完整参考（不包括决定配置文件保存位置的 path 和 cfg_name 参数）。有关 PyPI 分类器的更多信息，请参阅 分类器。

您可以通过命令行传递所有必需的设置以及任何想要覆盖的可选设置来创建一个配置文件，例如

nbdev_create_config --repo nbdev --user fastai --author fastai \
                    --author_email [email protected] --description 'A test project'

如果您未从命令行提供必需的设置，我们将尝试从 Git 和 GitHub 中推断它们。最后，您将被要求手动输入我们无法自动填写的任何必需设置。

源码

get_config

 get_config (cfg_name='settings.ini', path=None)

返回 nbdev 配置。

从 path 向上搜索，直到找到 cfg_name。用户设置从 ~/.config/nbdev/{cfg_name} 加载。未指定的可选设置返回默认值。

有关 nbdev 设置的完整参考，请参阅 nbdev_create_config。

cfg = get_config()

cfg 是一个 fastcore Config 对象，因此您可以像访问属性一样访问键

p = Path.cwd().parent.parent
test_eq(cfg.lib_name, 'nbdev')
test_eq(cfg.git_url, 'https://github.com/AnswerDotAI/nbdev')

它本身的路径和父级也是属性

test_eq(cfg.config_path, p)
test_eq(cfg.config_file, p/'settings.ini')

路径相对于项目

test_eq(cfg.doc_path, p/'_docs')
test_eq(cfg.lib_path, p/'nbdev')
test_eq(cfg.nbs_path, p/'nbs')

它自动为配置文件中未指定的键返回默认值。这里我们创建一个空的配置文件，并访问 lib_path 和 copyright，即使它们没有被明确定义

with tempfile.TemporaryDirectory() as d, working_directory(d):
    Config('.', 'test_settings.ini', {'repo': 'my-project', 'author': 'fastai', 'nbs_path': 'nbs'});
    cfg = get_config('test_settings.ini', '.')
    test_eq(cfg.repo, 'my-project')
    test_eq(cfg.lib_path.name, 'my_project')

事实上，即使您没有 settings 文件，也可以返回一个默认配置。这是为了支持某些 nbdev 命令在 nbdev 仓库之外工作

cfg = get_config('test_settings.ini', '.')
test_eq(cfg.lib_path, Path('nbdev').resolve())
test_eq(cfg.nbs_path, Path('nbs').resolve())

您可以使用 ~/.config/nbdev/settings.ini 文件（默认情况下如此，尽管我们遵循更广泛的 XDG 规范）为您用户的所有仓库定制 nbdev。例如，您可以通过创建一个包含 jupyter_hooks = False 的用户 settings 文件来全局禁用 nbdev 的 Jupyter 钩子。

源码

config_key

 config_key (c, default=None, path=True, missing_ok=None)

已弃用：请改用 get_config().get 或 get_config().path。

辅助函数

源码

is_nbdev

 is_nbdev ()

源码

create_output

 create_output (txt, mime)

添加包含 txt 的单元格输出，其文本 MIME 子类型为 mime

源码

show_src

 show_src (src, lang='python')
show_src("print(create_output('text', 'text/plain'))")
print(create_output('text', 'text/plain'))

导出基本模块

源码

add_init

 add_init (path=None)

如果 path 的所有子目录中包含 python 文件但没有 __init__.py，则添加它。

源码

update_proj

 update_proj (path)

在项目根目录中创建或更新 pyproject.toml。

源码

update_version

 update_version (path=None)

在库的主要 __init__.py 中添加或更新 __version__。

Python 模块要求所有是模块的目录中都有一个 __init.py__ 文件。我们假定所有包含 python 文件的目录（包括任何深度的子目录）都是模块，因此会为每个目录添加一个 __init__.py。

with tempfile.TemporaryDirectory() as d:
    d = Path(d)
    (d/'a/b').mkdir(parents=True)
    (d/'a/b/f.py').touch()
    (d/'a/c').mkdir()
    add_init(d)
    assert not (d/'a/c'/_init).exists(), "Should not add init to dir without py file"
    for e in [d, d/'a', d/'a/b']: assert (e/_init).exists(),f"Missing init in {e}"

源码

write_cells

 write_cells (cells, hdr, file, offset=0, cell_number=True, solo_nb=False)

将 cells 以及从索引 offset 开始的头部 hdr 写入 file（主要用于 nbdev 内部使用）。

这是一个简单的导出器，其功能足以正确导出此 notebook，以便引导 nbdev 本身的创建过程。