尝试以扩展 VS Code 中的代理模式!

Python 交互窗口

Jupyter (前身为 IPython Notebook) 是一个开源项目,可让你在一个称为**笔记本**的画布上轻松地组合 Markdown 文本和可执行的 Python 源代码。Visual Studio Code 支持原生使用 Jupyter Notebooks,以及通过 Python 代码文件使用。本主题介绍通过 Python 代码文件提供的支持,并演示如何:

  • 使用类似 Jupyter 的代码单元
  • 在 Python 交互窗口中运行代码
  • 使用变量资源管理器和数据查看器查看、检查和筛选变量
  • 连接到远程 Jupyter 服务器
  • 调试 Jupyter Notebook
  • 导出 Jupyter Notebook

要使用 Jupyter Notebook,你必须在 VS Code 中激活一个 Anaconda 环境,或者已安装 Jupyter 包的其他 Python 环境。要选择一个环境,请从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中使用 **Python: Select Interpreter** 命令。

一旦激活了适当的环境,你就可以创建和运行类似 Jupyter 的代码单元,连接到远程 Jupyter 服务器以运行代码单元,并将 Python 文件导出为 Jupyter Notebook。

Jupyter 代码单元

你可以在 Python 代码中使用 # %% 注释来定义类似 Jupyter 的代码单元。

# %%
msg = "Hello World"
print(msg)

# %%
msg = "Hello again"
print(msg)

注意:请确保将上面显示的代码保存在扩展名为 .py 的文件中。

当 Python 扩展检测到代码单元时,它会添加 **Run Cell** (运行单元格) 和 **Debug Cell** (调试单元格) 的 CodeLens 装饰。第一个单元格还包括 **Run Below** (运行下方代码),所有后续单元格都包括 **Run Above** (运行上方代码)。

Jupyter adornments for code cells in the VS Code editor

注意:默认情况下,**Debug Cell** (调试单元格) 仅单步进入用户代码。如果你想单步进入非用户代码,你需要在 Jupyter 扩展设置 (⌘, (Windows, Linux Ctrl+,)) 中取消选中 **Debug Just My Code** (仅调试我的代码)。

**Run Cell** (运行单元格) 只适用于单个代码单元。**Run Below** (运行下方代码),出现在第一个单元格上,会运行文件中的所有代码。**Run Above** (运行上方代码) 适用于所有代码单元,直到但不包括带有该装饰的单元格。例如,你可以在运行特定单元格之前使用 **Run Above** 来初始化运行时环境的状态。

选择一个命令会启动 Jupyter(如果需要,这可能需要一分钟),然后在 **Python Interactive** (Python 交互) 窗口中运行相应的单元格。

Code cells running in a Python Interactive window

你还可以使用 (Ctrl+Enter) 或 **Python: Run Selection/Line in Python Terminal** (在 Python 终端中运行选定内容/行) 命令 (Shift+Enter) 来运行代码单元。使用此命令后,Python 扩展会自动将光标移动到下一个单元格。如果你在文件的最后一个单元格中,该扩展会自动为新单元格插入另一个 # %% 分隔符,模仿 Jupyter Notebook 的行为。

你也可以在行号左侧的空白处点击以设置断点。然后你可以使用 **Debug Cell** (调试单元格) 为该代码单元启动一个调试会话。调试器会在断点处停止执行,并允许你逐行单步执行代码并检查变量(详见调试)。

其他命令和键盘快捷键

下表列出了在使用代码单元时支持的其他命令和键盘快捷键。

命令 键盘快捷键
Python: 转到下一个单元格 Ctrl+Alt+]
Python: 转到上一个单元格 Ctrl+Alt+[
Python: 向上扩展单元格选择 Ctrl+Shift+Alt+[
Python: 向下扩展单元格选择 Ctrl+Shift+Alt+]
Python: 上移选定的单元格 Ctrl+; U
Python: 下移选定的单元格 Ctrl+; D
Python: 在上方插入单元格 Ctrl+; A
Python: 在下方插入单元格 Ctrl+; B
Python: 在当前位置下方插入单元格 Ctrl+; S
Python: 删除选定的单元格 Ctrl+; X
Python: 将单元格更改为代码 Ctrl+; C
Python: 将单元格更改为 Markdown Ctrl+; M

使用 Python 交互窗口

上一节中提到的 **Python Interactive** (Python 交互) 窗口可以作为带有任意代码(有或没有代码单元)的独立控制台使用。要将该窗口用作控制台,请从命令面板中打开 **Jupyter: Create Interactive Window** (Jupyter: 创建交互窗口) 命令。然后你可以输入代码,使用 Enter 换行,使用 Shift+Enter 运行代码。

要将窗口与文件一起使用,请从命令面板中使用 **Jupyter: Run Current File in Python Interactive Window** (Jupyter: 在 Python 交互窗口中运行当前文件) 命令。

IntelliSense

Python 交互窗口具有完整的 IntelliSense 功能——代码补全、成员列表、方法的快速信息和参数提示。在 Python 交互窗口中打字可以像在代码编辑器中一样高效。

IntelliSense in the Python Interactive window

绘图查看器

绘图查看器使你能够更深入地处理你的绘图。在查看器中,你可以平移、缩放和导航当前会话中的绘图。你还可以将绘图导出为 PDF、SVG 和 PNG 格式。

在 Python 交互窗口中,双击任何绘图以在查看器中打开它,或选择绘图左上角的展开按钮。

Plot Viewer with the Python Interactive window

注意:Python 交互窗口支持渲染用 matplotlibAltair 创建的绘图。

变量资源管理器和数据查看器

在 Python 交互窗口中,可以查看、检查和筛选当前 Jupyter 会话中的变量。在运行代码和单元格后,选择交互窗口工具栏上的 **Variables** (变量) 按钮以打开变量资源管理器,你将看到当前变量的列表,该列表会在代码中使用变量时自动更新。

Variables Explorer

有关变量的更多信息,你还可以双击一行或使用 **Show variable in data viewer** (在数据查看器中显示变量) 按钮,在数据查看器中查看更详细的变量视图。打开后,你可以通过搜索行来筛选值。

Data Viewer

连接到远程 Jupyter 服务器

你可以通过连接到远程 Jupyter 服务器,将 Jupyter Notebook 中的密集计算卸载到其他计算机上。连接后,代码单元将在远程服务器而不是本地计算机上运行。

连接到远程 Jupyter 服务器

  1. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行 **Jupyter: Specify local or remote Jupyter server for connections** (Jupyter: 指定用于连接的本地或远程 Jupyter 服务器) 命令。

  2. 选择你希望如何连接到 Jupyter 服务器。 提供 Jupyter 服务器 URI 的提示

  3. 如果远程工作,请在提示时提供服务器的 URI (主机名),并附带包含在 ?token= URL 参数中的身份验证令牌。(如果你在启用了身份验证令牌的 VS Code 终端中启动服务器,带有令牌的 URL 通常会出现在终端输出中,你可以从中复制它。)或者,你可以在提供 URI 后指定用户名和密码。

    Prompt to supply a Jupyter server URI

  4. Python 交互窗口通过显示 URI (在下图中被模糊处理) 来指示代码运行的位置。

    The Python Interactive window showing that code is running on a remote Jupyter server

注意:为增强安全性,Microsoft 建议为你的 Jupyter 服务器配置安全预防措施,例如 SSL 和令牌支持。这有助于确保发送到 Jupyter 服务器的请求经过身份验证,并且到远程服务器的连接是加密的。有关保护 Notebook 服务器的指南,请参阅 Jupyter 文档

将 Jupyter Notebook 转换为 Python 代码文件

当你激活了安装有 Jupyter 的环境后,你可以在 VS Code 中打开一个 Jupyter Notebook 文件 (.ipynb),然后将其转换为 Python 代码。转换文件后,你可以像运行任何其他 Python 文件一样运行代码,并使用 VS Code 调试器。在 VS Code 中打开和调试 Notebook 是查找和解决代码错误的便捷方式,这在 Jupyter Notebook 中直接操作很困难。

当你打开一个 Notebook 文件时,Visual Studio Code 会自动在 Notebook 编辑器中打开它。使用工具栏上的转换图标将 Notebook (.ipynb) 文件转换为 Python 文件 (.py)。

Icon to convert a Jupyter notebook file

选择转换图标,然后选择“Python Script”,等待几秒钟,VS Code 就会在一个无标题的文件中打开转换后的 Notebook。Notebook 的单元格在 Python 文件中用 # %% 注释分隔;Markdown 单元格被完全转换为以 # %% [markdown] 为前缀的注释,并在交互窗口中与代码和图表等输出一起呈现为 HTML。

Jupyter notebook running in VS Code and the Python Interactive window

注意:当你第一次在 Python 文件中运行代码单元时,Python 扩展会启动一个 Jupyter 服务器。服务器启动和 **Python Interactive** (Python 交互) 窗口出现代码结果可能需要一些时间。

调试 Jupyter Notebook

Visual Studio Code 调试器可让你单步执行代码、设置断点、检查状态和分析问题。使用调试器是查找和纠正 Notebook 代码中问题的有效方法。

  1. 在 VS Code 中,激活已安装 Jupyter 的 Python 环境,如本文开头所述。

  2. 将 Notebook 的 .ipynb 文件导入 VS Code,如上一节所述。(如果你正在使用基于云的 Jupyter 环境,例如 Azure Notebooks,请先下载文件。)

  3. 要启动调试器,请使用以下选项之一:

    • 对于整个 Notebook,打开命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 并运行 **Jupyter: Debug Current File in Python Interactive Window** (Jupyter: 在 Python 交互窗口中调试当前文件) 命令。
    • 对于单个单元格,使用出现在单元格上方的 **Debug Cell** (调试单元格) 装饰。调试器专门在该单元格的代码上启动。默认情况下,**Debug Cell** 仅单步进入用户代码。如果你想单步进入非用户代码,你需要在 Jupyter 扩展设置 (⌘, (Windows, Linux Ctrl+,)) 中取消选中 **Debug Just My Code** (仅调试我的代码)。
  4. 要熟悉 VS Code 的一般调试功能,例如检查变量、设置断点和其他活动,请查看 VS Code 调试

  5. 当你发现问题时,停止调试器,更正你的代码,保存文件,然后再次启动调试器。

  6. 当你确信所有代码都正确无误后,保存文件,然后如下一节所述导出 Notebook。然后你可以将 Notebook 上传到你的常规 Jupyter 环境中。

导出 Jupyter Notebook

除了打开 Jupyter Notebook 之外,你还可以使用命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中的以下命令之一,将 VS Code 中 Python 文件的内容导出为 Jupyter Notebook (扩展名为 .ipynb)。

  • Jupyter: Export Current Python File as Jupyter Notebook (Jupyter: 将当前 Python 文件导出为 Jupyter Notebook):根据当前文件的内容创建一个 Jupyter Notebook,使用 # %%# %% [markdown] 分隔符来指定它们各自的单元格类型。
  • Jupyter: Export Current Python File and Output as Jupyter Notebook (Jupyter: 将当前 Python 文件和输出导出为 Jupyter Notebook):根据当前文件的内容创建一个 Jupyter Notebook,并包含代码单元的输出。
  • Jupyter: Export Interactive Window as Jupyter Notebook (Jupyter: 将交互窗口导出为 Jupyter Notebook):根据 Python 交互窗口的内容创建一个 Jupyter Notebook。

导出内容后,VS Code 会显示一个提示,你可以通过它在浏览器中打开 Notebook。