开发者注意事项

开发环境的可编辑安装

要进行可编辑安装，请在克隆的 fastai 目录中执行

cd fastai
pip install -e ".[dev]"

这几乎与以下命令相同

pip install -e .

但添加 [dev] 会告诉 pip 安装 fastai/setup.py 中 dev_requirements 字典变量 dev 组中的可选包。这些额外依赖项仅供开发者和贡献者使用。

最好不要使用 python setup.py develop 方法文档。

当你想要将代码库与 master 分支同步时，只需回到克隆的 fastai 目录并更新它

git pull

你无需执行其他任何操作。

可编辑安装说明

如果你是可编辑安装的新手，请参阅可编辑安装及其示例。

本节将演示可编辑安装如何与 fastai 配合使用，包括一些重要的细微差别，理解这些非常重要。

首先，请确保你处于正确的 python 环境中（使用 conda activate fastai，或者如果你使用了其他名称的环境，则使用该名称；如果你使用的是系统级安装，则无需激活任何环境，不过使用专用的虚拟环境来使用 fastai 会安全得多）。

首先，我们卸载 fastai

pip   uninstall -y fastai
conda uninstall -y fastai

sys.path 是 python 在执行 import 时用于搜索要加载模块的系统路径列表。

在添加可编辑的 fastai 安装之前，我们的 sys.path 如下

python -c 'import sys, pprint; pprint.pprint(sys.path)'
['',
 '~/.local/lib/python3.6/site-packages',
 '~/anaconda3/envs/fastai/lib/python3.6/site-packages']

为便于比较，此处省略了部分条目。

现在我们为 fastai 执行可编辑安装

cd ~/github
git clone https://github.com/fastai/fastai
cd fastai
pip install -e ".[dev]"

然后我们再次查看 sys.path

python -c 'import sys, pprint; pprint.pprint(sys.path)'
['',
 '~/.local/lib/python3.6/site-packages',
 '~/anaconda3/envs/fastai/lib/python3.6/site-packages',
 '~/github/fastai']

你可以看到，我的 github 仓库克隆的 fastai 路径已被添加到 python 在遇到 import fastai 时搜索的路径列表末尾。

这种设置使得编辑 ~/github/fastai/fastai/*/*py 下的 python 模块成为可能，并且 python 会自动在运行于 conda 的 fastai 环境中的程序中加载这些文件。

你可以看到 python+pip 是如何实现这一点的

pip uninstall fastai
Uninstalling fastai-1.0.38.dev0:
  Would remove: ~/anaconda3/envs/fastai/lib/python3.6/site-packages/fastai.egg-link

在 fastai.egg-link 文件内部，你会找到 ~/github/fastai。

这里有一个重要的经验教训：你不能让常规安装的 fastai 与可编辑安装共存。正如从 sys.path 的内容可以看出，可编辑路径被添加到了模块搜索路径的最后。因此，如果你有一个常规安装的 fastai 包，python 会优先使用它而不是可编辑安装，这可能不是你想要的。

使用 pip 则不存在这个问题。如果你通过 pip 安装了一个 fastai 包，然后接着又通过 pip 进行可编辑安装，pip 会在执行可编辑安装之前卸载之前安装的包。如果你尝试在 pip 可编辑安装之上安装常规的 pip fastai 包，它也会做同样的事情。它处理得很妥当，确保只安装一个版本。

但 Conda 包的情况并非如此。如果你执行以下命令

conda install -c fastai fastai
cd ~/github/fastai
pip install -e ".[dev]"

最终你会得到两个 fastai 安装：conda 包安装的 fastai 会被 python 加载，而可编辑安装实际上对 python 不可见（因为它会首先找到 conda 包）。

$ ls -l ~/anaconda3/envs/fastai/lib/python3.6/site-packages/fastai*
~/anaconda3/envs/fastai/lib/python3.6/site-packages/fastai
~/anaconda3/envs/fastai/lib/python3.6/site-packages/fastai-1.0.37-py3.7.egg-info

因此，如果你编写脚本进行可编辑安装，请务必先卸载任何先前安装的 conda fastai 包

pip   uninstall -y fastai
conda uninstall -y fastai
cd ~/github/fastai
pip install -e ".[dev]"

另外请注意，conda 也可以进行可编辑安装

cd ~/github/fastai
conda develop .
python -c 'import sys, pprint; pprint.pprint(sys.path)'
['',
 '~/.local/lib/python3.6/site-packages',
 '~/anaconda3/envs/fastai/lib/python3.6/site-packages',
 '~/github/fastai']

它的作用与 pip 完全相同，只是通过编辑 ~/anaconda3/envs/fastai/lib/python3.6/site-packages/conda.pth 文件来实现。

所以你可能会认为，如果 conda 是你的首选方式，使用这种方法会更好。

我们不推荐使用这种方法，因为它与 conda 的常规安装配合不佳（常规的 conda 包安装会在运行时覆盖可编辑安装）。与 pip 不同，conda 的常规包不知道它们的可编辑版本，反之亦然——所以你最终会同时拥有两者，但只有一个能正常工作。此外，conda 不支持 pip 实现的额外依赖项（dev 依赖项）。

要卸载 conda 的可编辑版本，你必须使用

cd ~/github/fastai
conda develop -u .

在 Jupyter 中切换 Conda 环境

除了通过重启来切换常规环境之外

source activate env1
jupyter notebook
(Ctrl-C to kill jupyter)
source activate env2
jupyter notebook

你可以安装 nb_conda_kernels，它为每个 conda 环境提供一个单独的 jupyter 内核，并附带适当的代码来处理它们的设置。这使得切换 conda 环境就像切换 jupyter 内核一样简单（例如，从内核菜单）。而且你无需担心从哪个环境启动了 jupyter notebook——只需从 notebook 中选择正确的环境即可。

一些有用的单行命令

如何使用 CLI 安全高效地在 git 仓库中搜索/替换文件。该操作不能触碰 .git 目录下的任何内容

find . -type d -name ".git" -prune -o -type f -exec perl -pi -e 's|OLDSTR|NEWSTR|g' {} \;

但它会 touch(1) 所有文件，这会减慢 git 端的处理速度，所以我们只想对实际包含旧模式的文件进行操作

grep --exclude-dir=.git -lIr "OLDSTR" . | xargs -n1 perl -pi -e 's|OLDSTR|NEWSTR|g'