为代码空间设置 Python 项目

简介

本指南介绍如何在 Codespaces 中设置 Python 项目。它将演示在代码空间中打开项目以及从模板添加和修改开发容器配置的示例。

基本要求

您应该在 GitHub.com 的仓库中有现有的 Python 项目。如果您没有项目，可以使用以下示例尝试本教程：https://github.com/2percentsilk/python-quickstart.
您必须为组织启用 Codespaces 。

步骤 1：在代码空间中打开项目

在存储库名称下，使用代码下拉菜单，然后在Codespaces（代码空间）选项卡中，单击 Create codespace on main（在主分支上创建代码空间）。

如果您看不到此选项，则表示 Codespaces 不适用于您的项目。有关详细信息，请参阅访问 Codespaces。

创建代码空间时，您的项目是在专用于您的远程 VM 上创建的。默认情况下，代码空间的容器有许多语言和运行时，包括 Node.js、JavaScript、Typescript、nvm、npm 和 yarn。它还包括一套常见的工具，例如 git、wget、rsync、openssh 和 nano。

您可以通过调整 vCPU 和 RAM 的数量、添加 dotfiles 以个性化环境或者修改安装的工具和脚本来自定义代码空间。

Codespaces 使用名为 devcontainer.json 的文件来配置在代码空间中工作时使用的开发容器。每个存储库可以包含一个或多个 devcontainer.json 文件，以便为您提供在代码空间中处理代码所需的开发环境。

启动时，Codespaces 使用 devcontainer.json 文件以及构成开发容器配置的任何依赖文件来安装工具和运行时，并执行项目所需的其他设置任务。更多信息请参阅“开发容器简介”。

第 2 步：将开发容器配置从模板添加到存储库

GitHub Codespaces 的默认开发容器预安装了最新的 Python 版本、包管理器（pip、Miniconda）及其他常用工具。但是，我们建议你配置自己的开发容器，以包含项目所需的所有工具和脚本。这将确保仓库中的所有 GitHub Codespaces 用户都拥有完全可复制的环境。

若要将存储库设置为使用自定义开发容器，需要创建一个或多个 devcontainer.json 文件。您可以从模板、 Visual Studio Code 中添加这些内容，也可以编写自己的模板。有关开发容器配置的详细信息，请参阅“开发容器简介”。

访问 Visual Studio 代码命令面板 (Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux))，然后键入 "dev container"。选择 Codespaces: Add Development Container Configuration Files...（Codespaces：添加开发容器配置文件...）.
对于此示例，单击 Python 3。如果需要其他功能，您可以选择任何特定于 Python 或工具（如 Python 3 和 PostgreSQL）组合的容器。
单击推荐的 Python 版本。
接受默认选项，将 Node.js 添加到您的自定义中。
Access the Visual Studio 代码命令面板 (Shift + Command + P / Ctrl + Shift + P), then start typing "rebuild". 选择 Codespaces: Rebuild Container（代码空间：重建容器）。

开发容器的剖析

添加 Python 开发容器模板会将 .devcontainer 目录添加到项目仓库的根目录中，其中包含以下文件：

devcontainer.json
Dockerfile

新添加的 devcontainer.json 文件定义了几个在样本之后描述的属性。

devcontainer.json

{
    "name": "Python 3",
    "build": {
        "dockerfile": "Dockerfile",
        "context": "..",
        "args": {
            // Update 'VARIANT' to pick a Python version: 3, 3.6, 3.7, 3.8, 3.9
            "VARIANT": "3",
            // Options
            "INSTALL_NODE": "true",
            "NODE_VERSION": "lts/*"
        }
    },

    // Set *default* container specific settings.json values on container create.
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash",
        "python.pythonPath": "/usr/local/bin/python",
        "python.linting.enabled": true,
        "python.linting.pylintEnabled": true,
        "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
        "python.formatting.blackPath": "/usr/local/py-utils/bin/black",
        "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
        "python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
        "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
        "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
        "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
        "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
        "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint"
    },

    // Add the IDs of extensions you want installed when the container is created.
    "extensions": [
        "ms-python.python"
    ],

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "pip3 install --user -r requirements.txt",

    // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
    "remoteUser": "vscode"
}

name - 您可以将开发容器命名为任何名称，这只是默认名称。
build - 构建属性。
- dockerfile - 在 build 对象中，dockerfile 包含也从模板添加的 Dockerfile 的路径。
- args
  - Variant：此文件仅包含一个构建参数，即我们要用于传递到 Dockerfile 的节点变量。
settings - 它们是 Visual Studio Code 设置。
- terminal.integrated.shell.linux - 虽然 bash 是这里的默认设置，但您可以通过修改它来使用其他终端 shell。
extensions - 它们是默认包含的扩展名。
- ms-python.python - Microsoft Python 扩展为 Python 语言提供丰富的支持（对于所有积极支持的语言版本：>=3.6），包括 IntelliSense、linting、调试、代码导航、代码格式化、重构、变量资源管理器、测试资源管理器等功能。
forwardPorts - 此处列出的任何端口都将自动转发。更多信息请参阅“在代码空间中转发端口”。
postCreateCommand - 在创建代码空间后，使用此选项可运行 Docker 文件中未定义的命令，如 pip3 install -r requirements。
remoteUser - 默认情况下，您以 vscode 用户身份运行，但您可以选择将其设置为 root。

Dockerfile

# [Choice] Python version: 3, 3.9, 3.8, 3.7, 3.6
ARG VARIANT="3"
FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}

# [Option] Install Node.js
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi

# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
# COPY requirements.txt /tmp/pip-tmp/
# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
#    && rm -rf /tmp/pip-tmp

# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

您可以使用 Dockerfile 添加其他容器层，以指定要包含在容器中的操作系统包、节点版本或全局包。

步骤 3：修改 devcontainer.json 文件

添加开发容器配置并基本了解所有内容的功能后，现在可以进行更改以进一步自定义环境。在此示例中，您将在代码空间启动时添加属性以安装扩展和项目依赖项。

在 Explorer 中，展开 .devcontainer 文件夹，从树中选择 devcontainer.json 文件并打开它。

更新 devcontainer.json 文件中的 extensions 列表，以添加一些在处理项目时有用的扩展。

JSON

"extensions": [
        "ms-python.python",
        "cstrap.flask-snippets",
        "streetsidesoftware.code-spell-checker"
    ],

取消注释 postCreateCommand 以自动安装要求，作为代码空间设置过程的一部分。

JSON

// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "pip3 install --user -r requirements.txt",

Access the Visual Studio 代码命令面板 (Shift + Command + P / Ctrl + Shift + P), then start typing "rebuild". 选择 Codespaces: Rebuild Container（代码空间：重建容器）。

在代码空间内进行重建可确保在将更改提交到仓库之前，更改能够按预期工作。如果某些问题导致了故障，您将进入带有恢复容器的代码空间中，您可以从该容器进行重建以继续调整容器。
通过验证是否安装了 Code Spell Checker 和 Flask Snippet 扩展，检查更改是否成功应用。

步骤 4：运行应用程序

在上一节中，您使用 postCreateCommand 通过 pip3 安装了一组包。现已安装您的依赖项，您可以运行应用程序。

通过按 F5 或在代码空间终端中输入 python -m flask run 来运行您的应用程序。
项目启动时，您应该在右下角看到一个信息框，提示您连接到项目使用的端口。

步骤 5：提交更改

在对代码空间进行更改（无论是添加新代码还是更改配置）之后，您需要提交更改。将更改提交到仓库可确保从此仓库创建代码空间的其他任何人都具有相同的配置。这也意味着您所做的任何自定义，例如添加 VS 代码扩展，都会显示给所有用户。

有关信息，请参阅“在代码空间中使用源控制”。

后续步骤

现在，您应该准备开始在 Codespaces 中开发您的 Python 项目。以下是用于更高级场景的一些额外资源。