jupytext and nbdev

Jupytext

界面点击操作

当你 Pair 一种文件，保存时，会自动生成你 pair 关联的格式的文件。在其中一个文件修改的任何文本都会同步到两个文件中。

首先你有文件

然后，在jupyter lab中 ctrl + shift + c，选择pair的文件类型（jupyter notebook在功能菜单中找到）

然后，保存

关联成功。py文件可以在自己喜欢IDE环境编辑，ipynb文件可以同步展示。删除任意一个，都可以再次恢复。

取消pair，则不会同步。（unpair 取消关联）

py文件中包含的 metadata 如下格式

命令行操作

Notebook to text

1
2
jupytext --to markdown notebook.ipynb
jupytext --to script notebook.ipynb

text to notebook

1
2
jupytext --to notebook notebook.py
jupytext --to notebook notebook.md

text to notebook and preserve outputs

1
2
jupytext --to notebook --update notebook.py
jupytext --to notebook --update notebook.md

命令行pair操作

1
jupytext --set-formats ipynb,py:percent notebook.ipynb

同步paired notebooks，当在其他文件中修改后，同步到ipynb

1
jupytext --sync notebook.ipynb

应用code style(flake8, black, isort)

1
jupytext --pipe flake8 notebook.ipynb

支持文件格式

NBDEV开发

step 1 新建git

使用 the template 创建一个github repo

image

1
pip install nbdev

可选，使用git自带的服务器：在setting中

image

在edit中添加生成的网址

image

step 2 编辑settings.ini

编辑settings.ini （注意这里的lib_name就是生成的包名，所以有空格很不规范）。前面的个人相关信息基本都要取消注释，后面在git上创建网页展示环境要check。

image

1
git clone https://github.com/RacleRay/Hello_nbdev.git

step 3 安装git_hooks

1
nbdev_install_git_hooks

出现conflict错误时

1
nbdev_fix_merge filename.ipynb

step 4 编辑代码

开始编辑ipynb文件

image

标记类别：

  • #default_exp

对于新创建的 .ipynb，需要加入 #default_exp target_module_name

这会导出生成以下py文件

1
lib_name/target_module_name.py

lib_name与settings时，保持一致

  • #export：效果如下

image

导出后显示如下

image

如果是类里面的方法，显示doc需要使用函数 show_doc

1
from nbdev,showdoc import show_doc
  • 不加标记会显示代码和输出

image

测试代码也可以写在这里，不代标记

1
assert say_hello("Jeremy")=="Hello Jeremy!"

step 5 nbdev_build_lib

1
nbdev_build_lib

注意，发生keyError时，多半是settings.ini配置不完整

image

生成新的lib包文件夹及py文件

core.py

image

step 6 编写index文件

编辑index.ipnb

image

step 7 生成docs文档

1
nbdev_build_docs

生成HTML文档

step 8 上传git

1
2
3
4
git add -A
git status
git commit -m "test"
git push

step 9 bug

检查 commits中的问题

image

image

没有设置keywords，在settings.ini中进行设置。

image

optional step 10 发布pypi

上传到pypi

  1. 注册pypi

  2. 在用户家目录下新建~/.pypirc

    1
    2
    3
    [pypi]
    username = your_pypi_username
    password = your_pypi_password

  3. pip install twine

  4. make release

附 其他事项

  • 安装包，同时同步所有在源码上的编辑
1
pip install -e .
  • 可以将自己开发的包链接到python包路径下
1
ln -s lib_path lib_name
  • autoreload
1
2
%load_ext autoreload
%autoreload 2
  • 在ipynb结尾添加以下代码，用以代替命令行nbdev_build_lib。
1
from nbdev.export import notebook2script; notebook2script()

  • 检查可读的notebook

    1
    nbdev_read_nbs

  • 检查可能造成merge conficts的文件，

    1
    nbdev_clean_nbs

    可能导致cleaned项不通过，此时用，然后再push

    image

  • 检查notebook和已经导出的lib files之间的是否有差异

    1
    nbdev_diff_nbs

  • 运行notebooks中的测试

    1
    nbdev_test_nbs

fastai文档 nbdev git

nbdev_template