玩转 VSCode 之配置 Python 语言开发环境

Linux && Windows 平台下配置 VS Code + Python 语言学习、开发环境。

我们知道，配置 VSCode多重开发环境，就是组合安装配置多种语言相关插件以及相关语言工具库 的过程。

下面正式开始在 VS Code 中配置 Python 开发、调试环境（For Windows && Linux）：

Extensions Setup

首先，需要安装 VSCode 中 Python 开发过程中可能会用到的插件 >>>>

↓↓↓↓↓↓ 推荐安装的扩展 ↓↓↓↓↓↓

Python：Python 语言支持插件，包括 Python 智能提示、代码规范和语法检查、代码格式化、调试功能以及单元测试等等。

官方说明：Support >>>> IntelliSense (Pylance), Linting, Debugging (multi-threaded, remote), Jupyter Notebooks, code formatting, refactoring, unit tests …

Python Extension 是一个插件合集包，包含了 Python && Pylance && Jupyter（4 <<< Jupyter Keymap && Jupyter Notebook Renderers && Jupyter Slide Show && Jupyter Cell Tags）在内的 7 个插件，涉及了所有 Python 开发中可能用到的流行插件。

其中，Pylance 子插件提供了：代码补全、参数提示、代码诊断、引用和跳转等基础编码功能；Jupyter 子插件提供了 Jupyter Notebook 支持，可用于直接打开、编辑 .ipynb 格式的 Jupyter Notebook 文档。

↓↓↓↓↓↓ 安装方式 ↓↓↓↓↓↓

打开 VSCode 插件商店【Ctrl + Alt + X】 >>> 搜索栏中搜索【Python】 >>> 【Install】即可。

↓↓↓↓↓↓ 插件禁用提示 ↓↓↓↓↓↓

禁用 Python 环境插件时，只需要将【Python】Extension 禁用掉即可，其子插件（7）也会一并被警用（适用于所有插件合集包警用）。

---

创建 Python 工程文件夹

我们知道，VScode 是以文件夹的形式来组织管理工程项目的。

故，首先你需要创建一个用来存放整个工程代码的文件夹也被称为 【工作目录】，这里我的为：PyProjectWSC。

注意：工作目录路径中不能含有中文和空格和引号。

然后通过 VSCode 打开该文件夹【File –> Open Folder 或使用快捷键 Ctrl + K + O】，选择刚才创建的那个文件夹（PyProjectWSC）即可。

事实上，此时你就可以将 VSCode 作为编辑器进行 Python 源码学习和编写了。

---

打起精神，重点来了….

Reffs Configuration

如果你只是将 VSCode 作为一个 Python 代码编辑器使用，那么上述就够了，当然这不是我们的目的。

再一次重申：VS Code 只是一个文本编辑器，并不是 IDE。

我们的目的是 >>> 想要在 VSCode 中直接进行 Python 代码的编写测试以及完成代码的 Debug（断点测试）功能，那么你还需要进行额外的配置。

需要配置那些？？？

1. 配置 Python 环境：你需要确定当前系统环境下确保有一个可以用来解释、执行 Python 的解释器，以及相关开发类库；
2. 配置工程文件夹：你需要使用 VSCode 设置规则在工程文件夹中进行一些配置，以可以帮助我们完成多版本 Python 环境、代码格式化工具、代码检查工具、单元测试工具 …… 的设置。

---

关于 VSCode For Python 语言开发环境，在不同平台（Windows & Linux）下的配置过程类似，有区别的地方会特别指出。

Begin to Start >>>

配置 Python 环境

首先，来配置 Python 运行必须的解释器环境：

[1] >>> 配置 Python 解释器环境

关于 Python 解释器的安装和配置，篇幅原因不再赘述，你可以参考博主前面的博文 >>> 【Python 简介与开发环境搭建】 中 【2 Python Development Envs Setup】小节，里面详细阐述了 Windows & Linux 平台下 Python 环境的安装以及配置过程。

关于 Python 的多版本管理以及运行环境相关内容，感兴趣的同学可以关注博主相关博文系列：

之一 >>> 【Python-Vers Management】

之二 >>> 【Pythoner 神器之 virtualenv】

之三 >>> 【一文了解数据科学神器 Anaconda】

Attention >>>> Python 环境安装完成之后，一定要确定完成 Python 环境变量的配置。这样，VS Code 才可以从操作系统中成功检索到你安装的 Python 解释器（包括操作系统 Python 解释器、VirtualEnv 虚拟环境、），这是关键的⚠⚠⚠

除了操作系统级别的 Python 解释器，VS Code 还可以自动检测到你通过 virtualenvwrapper && anaconda 等虚拟环境管理工具已创建好的虚拟级别的 Python 解释器，这对于 VS Code 配置 Python 多版本环境是有益的！！！

---

[2] >>> 配置 Python 开发相关的第三方库

这里，主要包含三个第三方库：

1. flake8：Python 静态代码检测工具，代码规范器。作用：用于检查编写的 Python 代码是否不规范，是否存在语法错误；
2. yapf：Google 开源的 Python 代码格式化工具，作用：一键美化代码；
3. pytest：一个广泛使用的第三方单元测试框架，兼容 unittest（Python 默认测试工具） && nose。

安装方式 >>>>

$ pip install flake8
$ pip install yapf
$ pip install pytest

完美~~~，至此 关于 Python 环境的配置就完成了…

---

上面，我们已经创建了一个工程文件夹（目录：PyProjectWSC），并在 VSCode 中进行了打开。

下面我们来看如何为一个 Python 项目进行配置，即针对 Python 工程文件夹进行配置，涉及到我们前面讲解过的 “文件夹设置”。

配置工程文件夹

关于工程文件夹设置内容主要包括：

多版本 Python 解释器环境配置、IntelliSense 智能语言支持、代码格式化工具、代码检查工具、调试、单元测试工具等。更多设置可关注插件 >>> Python Extension。

配置 Python 解释器

Python 是一个解释型语言，故你需要先为 Python 工程文件夹选择一个适合项目的 Python 解释器。

官方文档：opening the Command Palette (Ctrl+Shift+P), start typing the Python: Select Interpreter command to search

👇👇👇 Configuration Method 👇👇👇

打开 VSCode 命令面板【Ctrl+Shift+P】 >>>> 搜索 Interpreter >>>>【Python: Select Interpreter】，此时你可以看到一个当前系统中存在的 Python 解释器列表（操作系统级别 Python 解释器 && 虚拟级别 Python 解释器） >>>> 选择一个适合项目 Python 版本的 Python 解释器。

如果你是在某个工作区中切换 Python 解释器环境，选择【Python: Select Interpreter】后会先让你选择你要配置当前工作区下的哪个项目？【Select the workspace folder to set the interpreter】，然后才提供给你可供选择的 Python 解释器列表。

配置完成之后，可以在 VS Code 下方导航栏中看到你配置好的 Python 解释器，例如：Python 3.5.6(vscodePyWSC:conda)。这是由于我使用的是 Anaconda 创建的虚拟环境 vscodePyWSC，其中 Python 解释器版本为 3.5.6。

---

配置 IntelliSense

Python Extension 中支持 IntelliSense（智能语言支持），提供代码自动补全，参数提醒、代码跳转等功能，可以极大的提高 Python 的变成效率。

一般情况下，Python 插件会自动读取本地的各种 Python Packages，然后为你提供智能提醒。

需要注意的是，如果你有一些第三方的 Python 脚本，但是它们并没有被 VS Code 的 Python 插件所识别，而你又希望能够获得它们的智能提示，那你可以通过生成 文件夹设置（.vscode/settings.json） 添加如下的配置来实现：

"python.autoComplete.extraPaths": [
]

这样，Python 插件就会分析 python.autoComplete.extraPaths 下的所有文件夹，然后分析这些代码，并且提供 IntelliSense 功能。

---

目前（2023.12.20），Python Extension 中已不再支持代码格式化工具、和静态代码检测工具的配置（Deprecated），正如 Python Extension 官方所说的：

As announced on April 2022, our team has been working towards breaking the tools support we offer in the Python extension for Visual Studio Code into separate extensions, with the intent of improving performance, stability and no longer requiring the tools to be installed in a Python environment – as they can be shipped alongside an extension. This also allows the extensions to be shipped separately from the Python one once a new version of their respective tool becomes available.

当然，你可以使用官方给出的替代方案来支持代码格式化和静态代码检测 >>> 见本文【4 Problems】中【Linting and Formatting Settings Deprecation】说明。

| ================================================== Split Line =============================================== |

配置代码格式化工具

Python 插件默认是使用 `autopep8` 来进行代码的格式化，同时也支持 `black` 和 `yapf`。

当然，你可以通过 python.formatting.provider 设置项来进行格式化工具的配置：

"python.formatting.provider": "yapf"

当你第一次使用格式化文件（Format Document）时（快捷键：Shift + Alt + F），如果你本地并没有安装对应的格式化工具的话，VS Code会提出警告（formatter xxxxx is not installed. install?），此时你需要通过包管理器进行安装。

同时，推荐 >>> 设置 editor.formatOnSave && editor.formatOnType，对代码进行及时的格式化。

"editor.formatOnSave": true,
"editor.formatOnType": true

此外，还可以通过 python.formatting.autopep8Args && python.formatting.yapfArgs && python.formatting.blackArgs 来调整格式化参数。

---

配置代码检测工具

默认情况，VS Code 会在你保存 Python 文件时，检查编写的 Python 代码是否不规范？是否存在语法错误？然后将错误显示在问题面板中。

Python 插件默认使用的代码检测工具是 Pylint。如果你希望使用其他的 Linter，你可以：打开命令面板【Ctrl + Alt + P】 >>>> 搜索【Python: Select Linter】执行 >>>> 选择你想要使用的 Linter。

这里我们选用的代码检查工具是：flake8，【Python: Select Linter】选择之后，配置文件内容如下：

"python.linting.enabled": true,
"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,

行最长字符数 79 限制 >>> 可设置单行最长字符限制 ：

"python.linting.flake8Args": ["--max-line-length=248"]

还可以忽略掉一些无关错误：

"python.linting.flake8Args": ["--extend-ignore=E231,E203"]

---

调试相关

Python 代码的调试，并不需要安装其它插件，只要你选择了合适的 Python 解释器即可。

如果没有配置调试配置文件 launch.json 的话，VS Code 会默认调试当前文件，你可以编写个简单的 Hello Python Demo 通过 F5（Debug） 尝试一下。

调试时可能会遇到：无法加载文件 C:\Users\Jie Guo\Documents\WindowsPowerShell\profile.ps1，因为在此系统上禁止运行脚本 的问题，解决方法见【4 Problems】小节。

需要注意的是：由于 Python 开发组已停止对 Python3.6 的维护，导致 VSCode 当前新版本的 Python 插件无法使用，且无法对代码 Debug，你可以选择升级 Python 版本至 3.7 以上版本；或者降低 Python 插件版本。

当你为当前 Python 工程创建调试配置 launch.json 时，Python 插件会自动提供多种不同的模板，比如在集成终端中调试当前文件，Attach 到某个正在运行的 Python 脚本上，调试 Python 模块，调试 Django 等等。

相信你还记得，在介绍调试器 launch.json 的书写时，提到过，各个调试器的配置选项都不完全相同，如果 Python 调试的模板不能满足你的需求，你可以通过 相关文档 来了解 Python 插件都支持哪些调试参数。

---

配置单元测试

Python 插件既支持 Python 自带的 unittest，同时也支持第三方的 pytest 和 Nose 单元测试框架。想要使用第三方单元测试框架，你需要在当前 Python 环境中安装相应的测试框架 Python Package，正如我前面安装的 pytest。

你可以，打开【命令面板】 >>>> 执行 【Python: Configure Tests】 命令，Python 插件就会依次问以下问题：

• Select a test framework/tool to enable：选择测试框架，我们选择 pytest framework;
• Select the directory containing the tests：选择在哪个文件夹下搜索测试文件，我们选择根目录；

为了测试上述单元测试框架，我们分别给出示例代码和相应的 pytest 测试单元代码：

[1] 计算器功能实现（示例代码：calculator.py），内容如下：

class Calculator:

    def add(self, a, b):
        return a + b

    def sub(self, a, b):
        return a - b

    def mul(self, a, b):
        return a * b

    def div(self, a, b):
        return a / b

[2] 计算器功能 pytest 测试代码（test_calculator.py），内容如下：

import pytest

from calculator import Calculator


class TestCalculator():

    def test_add(self):
        c = Calculator()
        result = c.add(3, 5)
        assert result == 8

    def test_sub(self):
        c = Calculator()
        result = c.sub(10, 5)
        assert result == 5

    def test_mul(self):
        c = Calculator()
        result = c.mul(5, 7)
        assert result == 35

    def test_div(self):
        c = Calculator()
        result = c.div(10, 5)
        assert result == 2


if __name__ == '__main__':
    pytest.main(['-s', 'test_calculator.py'])

依照上述操作，配置单元测试。在测试被成功找到后，你能够看到测试文件里，每个测试的行号右侧都有一个 Run Test 标识，并且右键标识，还可以看到 Debug Test 条目，你可以点击它们进行测试的执行。

并且，你可以在左侧导航栏 >>> Testing 资源区中可以看到所有的测试 Case。在该区域可以逐条对测试 Case 进行测试以及调试，还可以直接运行所有测试。

当然，真正发挥 VS Code 威力，还是通过 Debug Test 来调试某个单独的测试。你只需设置断点，点击 Debug Test 即可进入调试状态。

---

这里，整理一份完整的 Python 项目文件夹设置（settings.json），内容如下：

{
    "files.autoSave": "onWindowChange",     // // 文件自动保存选项；参数说明：onFocusChange => 当前文件失去焦点后自动保存; onWindowChange => 需要当前 VScode 窗口失去焦点才会自动保存
    "files.autoSaveDelay": 5000,            // // 间隔多少毫秒自动保存，默认「1000毫秒」;如果配置了保存格式化代码，这个配置下自动保存不会格式化代码

    "editor.tabSize": 4,                    // 配置 Tab 空格数
    "editor.formatOnSave": true,            // 保存文件时进行格式化
    "editor.formatOnType": true,            // 一行语句编辑完成之后格式化

    "code-runner.runInTerminal": true,      // 设置成 false 会在 “output” 中进行输出，无法输入
    "code-runner.executorMap": {
        "python": "python -u"
    },
    "code-runner.saveFileBeforeRun": true,  // Run Code 前保存
    "code-runner.preserveFocus": true,      // 若为 false，Run code 后光标会聚焦到终端上。如果需要频繁输入数据可设为 false；
    "code-runner.clearPreviousOutput": true,// 每次 Run code 前清空终端中属于之前 Code runner 的日志消息

    "python.autoComplete.extraPaths": [],   // 为路径下的第三方 Python 脚本提供 IntelliSense 功能
    "python.analysis.extraPaths": [],       // 可解决 “Import “xxxxxx” could not be resolved from source”

    "python.formatting.provider": "yapf",   // 配置文件格式化工具
    "python.formatting.yapfArgs": [],       // yapf 工具格式化参数设置

    "python.linting.enabled": true,         // 配置代码检查工具：flake8
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.linting.flake8Args": [          // 配置 flake8 工具
        "--max-line-length=200",
        "--extend-ignore=xxx"
    ],

    "python.testing.unittestEnabled": false,// 配置单元测试框架
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [
        "."
    ]
}

---

Problems

系统上禁止运行脚本问题

终端调试脚本时，可能会遇到 无法加载文件 C:\Users\Jie Guo\Documents\WindowsPowerShell\profile.ps1，因为在此系统上禁止运行脚本。 的问题。

Solution：以管理身份启动 VS Code，运行您编写的未签名脚本和来自其他用户的签名脚本，请使用以下命令将计算机上的执行策略更改为 RemoteSigned（默认为：Restricted）：

$ set-ExecutionPolicy RemoteSigned

修改后，查看执行策略：

$ get-ExecutionPolicy
Restricted

---

Linting and Formatting Settings Deprecation

Python Extension 早期版本中是支持代码格式化工具、和静态代码检测工具的配置的，目前已 Deprecated。

如果你的 VS Code Settings 中仍然沿用之前的配置，如：

"python.formatting.provider": "yapf",   // 配置文件格式化工具
"python.formatting.yapfArgs": [],       // yapf 工具格式化参数设置

"python.linting.enabled": true,         // 配置代码检查工具：flake8
"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,
"python.linting.flake8Args": [          // 配置 flake8 工具
    "--max-line-length=200",
    "--extend-ignore=xxx"
]

而 Python Extension 升级为最新版本，VS Code 会出现如下异常信息：

You have deprecated linting or formatting settings for Python. Please see the logs for more details.

Python Extension 官方推荐，安装单独的代码格式化插件（autopep8 / yapf / black）、和静态代码检测插件（Pylint）来解决：

插件商店搜索：flake8 && black-formatter，然后配置如下：

"[python]": {
    "editor.formatOnType": true,
    "editor.formatOnSave": false,
    "editor.defaultFormatter": "ms-python.black-formatter"
},
"flake8.args": [
    "--max-line-length=124",
    "--extend-ignore=E202, xxx, ...",
]

---