设置Matplotlib进行开发#
要设置Matplotlib进行开发,请按照以下步骤操作:
Fork Matplotlib存储库#
Matplotlib 托管在 matplotlib/matplotlib.git. 如果您计划解决问题或向主Matplotlib存储库提交pull request,您应该首先通过单击 页面顶部附近的 project repository Fork 按钮来fork此存储库.
这将在GitHub服务器上您的帐户下创建代码的副本. 有关更多详细信息,请参见 the GitHub documentation .
检索最新版本的代码#
现在,您的存储库fork位于您的GitHub用户名下,您可以使用以下命令之一检索最新版本的源代码(将 <your-username> 替换为您的GitHub用户名):
git clone https://github.com/<your-username>/matplotlib.git
git clone git@github.com:<your-username>/matplotlib.git
这需要您提前设置一个 SSH key ,但可以省去每次连接时输入密码的麻烦.
这会将源代码放置在当前工作目录下的 matplotlib 目录中,并将远程名称 origin 设置为指向您的 fork.在继续操作之前,请进入此目录:
cd matplotlib
现在将远程名称 upstream 设置为指向 Matplotlib 主仓库:
git remote add upstream https://github.com/matplotlib/matplotlib.git
git remote add upstream git@github.com:matplotlib/matplotlib.git
现在您可以使用 upstream 来检索源代码的最新快照,如 开发工作流程 中所述.
其他 git 和 GitHub 资源
创建专用环境#
您应该设置一个专用环境,以将 Matplotlib 的开发与其他 Python 和 Matplotlib 安装隔离开来.
我们建议使用以下选项之一作为专用开发环境,因为这些选项配置为在安装过程中安装 Python 依赖项.
使用以下命令创建一个新的 venv 环境:
python -m venv <file folder location>
并使用以下命令之一激活它:
source <file folder location>/bin/activate # Linux/macOS
<file folder location>\Scripts\activate.bat # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1 # Windows PowerShell
在某些系统上,您可能需要键入 python3 而不是 python .有关技术原因的讨论,请参见 PEP-394 .
使用以下命令安装 Python 依赖项:
pip install -r requirements/dev/dev-requirements.txt
请记住,每当您开始处理 Matplotlib 时都要激活环境!
创建一个新的 conda 环境并使用以下命令安装 Python 依赖项:
conda env create -f environment.yml
如果您安装了 mamba ,则可以在上面的命令中使用 mamba 代替 conda .
使用以下命令激活环境:
conda activate mpl-dev
请记住,每当您开始处理 Matplotlib 时都要激活环境!
GitHub Codespaces 是一个基于云的浏览器内开发环境,它带有贡献 Matplotlib 的适当设置.
通过单击 GitHub Web 界面上的绿色
Code按钮并选择Codespaces标签,在您的 fork 上打开 codespaces.接下来,单击"Open codespaces on <您的分支名称>".您稍后可以更改分支,因此可以选择默认的
main分支.创建 codespace 后,您将被带到一个新的浏览器选项卡,您可以在其中使用终端激活一个预定义的名为
mpl-dev的 conda 环境:conda activate mpl-dev
请记住,每当您开始处理 Matplotlib 时都要激活 mpl-dev 环境.
如果您需要在 Codespaces 上打开一个带有 Matplotlib 输出的 GUI 窗口,我们的配置包括一个 light-weight Fluxbox-based desktop .您可以通过 Web 浏览器连接到此桌面来使用它.为此:
按
F1或Ctrl/Cmd+Shift+P并在 VSCode 会话中选择Ports: Focus on Ports View,使其成为焦点.在您的工具中打开端口视图,选择noVNC端口,然后单击地球图标.在出现的浏览器中,单击"连接"按钮并输入桌面密码(默认为
vscode).
查看 GitHub instructions 以获取有关连接到桌面的更多详细信息.
如果您还构建了文档页面,则可以使用 Codespaces 查看它们.使用活动栏中的"扩展"图标安装"Live Server"扩展.在资源管理器中找到 doc/build/html 文件夹,右键单击要打开的文件,然后选择"使用 Live Server 打开".
安装外部依赖项#
Python 依赖项已作为 setting up the environment 的一部分安装.此外,还必须在本地安装以下非 Python 依赖项:
有关依赖项的完整列表,请参见 依赖项 .在 codespace 中工作时,无需安装外部依赖项.
以可编辑模式安装 Matplotlib#
使用以下命令从 matplotlib 目录以可编辑模式安装 Matplotlib
python -m pip install --verbose --no-build-isolation --editable ".[dev]"
"可编辑/开发模式"构建所有内容,并在您的 Python 环境中放置链接,以便 Python 能够从您的开发源目录导入 Matplotlib.这允许您导入修改后的 Matplotlib 版本,而无需在更改 .py 或编译的扩展文件后重新安装.
如果在未启用 Meson 的分支上工作,这意味着其历史记录 (log) 中没有 PR #26621 ,则每次更改任何已编译的扩展代码时,都必须从源代码重新安装.
如果安装不起作用,请查阅 troubleshooting guide .如果该指南没有提供解决方案,请通过 chat 或 open an issue .
构建选项#
如果您经常使用需要编译的文件,您可能需要检查编译日志.可以通过设置环境变量 MESONPY_EDITABLE_VERBOSE 或在安装期间设置 editable-verbose 配置来启用此功能
python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable .
有关安装和其他配置选项的更多信息,请参见 Meson Python :external+meson-python editable installs guide .
有关可以在安装前设置的其他环境变量的列表,请参见 环境变量 .
验证安装#
运行以下命令以确保您已在可编辑模式下正确安装 Matplotlib.该命令应在虚拟环境激活时运行
python -c "import matplotlib; print(matplotlib.__file__)"
此命令应返回: <matplotlib_local_repo>\lib\matplotlib\__init__.py
我们鼓励您运行测试和构建文档,以验证代码是否已正确安装以及文档是否已干净地构建,这样当您进行代码或文档相关更改时,您会事先意识到现有问题.
安装 pre-commit 钩子#
pre-commit 钩子通过在正式打开拉取请求之前识别代码问题,从而节省了审查过程中的时间.大多数钩子还可以帮助修复错误,并且检查应具有相应的 development workflow 和 pull request 指南.钩子在 .pre-commit-config.yaml 中配置,包括拼写和格式检查,flake 8 一致性,意外提交的文件,导入顺序和不正确的分支.
安装 pre-commit 钩子
python -m pip install pre-commit
pre-commit install
钩子在 editing workflow 的 git commit 阶段之后自动运行.当钩子找到并修复了文件中的错误时,必须再次暂存并提交该文件.
钩子也可以手动运行.可以使用以下命令,按照 .pre-commit-config.yaml 中列出的顺序,针对整个代码库运行所有钩子
pre-commit run --all-files
要手动运行特定钩子,请使用钩子 id 运行 pre-commit run
pre-commit run <hook id> --all-files
请注意, mypy pre-commit 钩子无法检查新函数的 类型提示 ;而是使用 stubtest CI check 检查新函数的存根,并且可以使用 tox -e stubtest 在本地进行检查.