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

VS Code 中的 Jupyter Notebook

Jupyter(前身为 IPython Notebook)是一个开源项目,它允许您在称为**笔记本**的单个画布上轻松组合 Markdown 文本和可执行的 Python 源代码。Visual Studio Code 原生支持 Jupyter Notebooks,也支持通过Python 代码文件使用它们。本主题介绍对 Jupyter Notebooks 的原生支持,并演示如何

  • 创建、打开和保存 Jupyter Notebooks
  • 处理 Jupyter 代码单元格
  • 使用变量浏览器和数据查看器查看、检查和筛选变量
  • 连接到远程 Jupyter 服务器
  • 调试 Jupyter Notebook

设置环境

若要在 Jupyter Notebooks 中使用 Python,您必须在 VS Code 中激活 Anaconda 环境,或激活已安装 Jupyter 包的另一个 Python 环境。若要选择环境,请使用命令面板中的“**Python: 选择解释器**”命令 (⇧⌘P (Windows、Linux Ctrl+Shift+P))。

激活相应的环境后,您可以创建并打开 Jupyter Notebook,连接到远程 Jupyter 服务器以运行代码单元格,并将 Jupyter Notebook 导出为 Python 文件。

工作区信任

刚开始使用 Jupyter Notebooks 时,您需要确保在受信任的工作区中工作。笔记本中可能嵌入有害代码,“工作区信任”功能允许您指示哪些文件夹及其内容应允许或限制自动代码执行。

如果您尝试在 VS Code 处于不受信任的工作区并运行受限模式时打开笔记本,则将无法执行单元格,并且富输出将被隐藏。

创建或打开 Jupyter Notebook

您可以通过运行命令面板中的“**创建: 新建 Jupyter Notebook**”命令 (⇧⌘P (Windows、Linux Ctrl+Shift+P)) 或在工作区中创建新的 .ipynb 文件来创建 Jupyter Notebook。

Blank Jupyter Notebook

接下来,使用右上角的内核选择器选择一个内核。

Kernel Picker

选择内核后,每个代码单元格右下角的语言选择器将自动更新为内核支持的语言。

Language Picker

如果您有现有的 Jupyter Notebook,可以通过右键单击文件并使用 VS Code 打开它,或通过 VS Code 文件资源管理器打开它。

运行单元格

运行单个代码单元格

添加代码后,您可以使用单元格左侧的“**运行**”图标运行单元格,输出将显示在代码单元格下方。

Run Jupyter code cell

若要运行选定的代码单元格,您还可以在命令模式和编辑模式下使用键盘快捷方式。Ctrl+Enter 运行当前选定的单元格。Shift+Enter 运行当前选定的单元格并在其下方立即插入一个新单元格(焦点移动到新单元格)。Alt+Enter 运行当前选定的单元格并在其下方立即插入一个新单元格(焦点保留在当前单元格)。

运行多个代码单元格

运行多个代码单元格可以通过多种方式实现。您可以使用笔记本编辑器主工具栏中的双箭头运行笔记本中的所有单元格,或通过在当前代码单元格上方或下方选择“**全部运行**”、“**运行上方所有单元格**”或“**运行下方所有单元格**”。

Run multiple code cells

运行节中的单元格

为了更轻松地运行笔记本中的相关单元格,您可以使用“**运行节中的单元格**”操作来运行由 Markdown 节标题分组的单元格。此操作在笔记本大纲视图和粘性滚动元素中可用。

在粘性滚动元素中,右键单击所选标题,然后通过上下文菜单中的操作运行该节。在大纲视图中,选择悬停或选中时出现的工具栏图标,然后通过提供的操作运行单个单元格或一组单元格。

保存 Jupyter Notebook

您可以使用键盘快捷方式 Ctrl+S 或通过“**文件**”>“**保存**”来保存 Jupyter Notebook。

导出 Jupyter Notebook

您可以将 Jupyter Notebook 导出为 Python 文件 (.py)、PDF 或 HTML 文件。若要导出,请在主工具栏上选择“**...**”>“**导出**”。然后将显示文件格式选项的下拉列表。

Convert Jupyter Notebook to Python file

**注意:** 若要导出为 PDF,必须安装 TeX。如果没有,当您选择 PDF 选项时,系统会通知您需要安装它。此外,请注意,如果您的笔记本中只有 SVG 输出,它们将不会显示在 PDF 中。若要在 PDF 中包含 SVG 图形,请确保您的输出包含非 SVG 图像格式,或者您可以先导出为 HTML,然后使用浏览器另存为 PDF。

在笔记本编辑器中处理代码单元格

笔记本编辑器使您可以轻松地在 Jupyter Notebook 中创建、编辑和运行代码单元格。

创建代码单元格

默认情况下,一个空白笔记本会有一个空的启动代码单元格,而一个现有笔记本则会在底部放置一个。将您的代码添加到空的单元格中即可开始。

msg = "Hello world"
print(msg)

Simple Jupyter code cell

代码单元格模式

在使用代码单元格时,单元格可以处于三种状态:未选中、命令模式和编辑模式。代码单元格左侧的垂直条和编辑器边框显示单元格的当前状态。当没有垂直条时,单元格未选中。当单元格被选中时,它可以处于命令模式或编辑模式。

Unselected Jupyter code cell

在命令模式下,单元格左侧会出现一个实心垂直条。该单元格可以进行操作并接受键盘命令。

Code cell in command mode

在编辑模式下,实心垂直条与单元格编辑器周围的边框连接在一起。可以修改单元格的内容(代码或 Markdown)。

Code cell in edit mode

若要切换模式,您可以使用键盘或鼠标。在键盘上,按 Enter 键进入编辑模式,或按 Esc 键进入命令模式。使用鼠标,单击单元格左侧的垂直条或代码单元格中代码/Markdown 区域之外的位置。

添加其他代码单元格

您可以使用主工具栏、单元格的添加单元格工具栏(悬停时可见)以及键盘命令来添加代码单元格。

Add code cells

若要在当前选定单元格下方添加新单元格,请使用主工具栏或单元格悬停工具栏中的加号图标。

当代码单元格处于命令模式时,使用 A 键在选定单元格上方添加一个单元格,使用 B 键在选定单元格下方添加一个单元格。

选择代码单元格

您可以使用鼠标或键盘上的上下箭头键更改选定的代码单元格。当代码单元格处于命令模式时,您还可以使用 J 键(向下)和 K 键(向上)。

选择多个代码单元格

若要选择多个单元格,请从一个处于选中模式的单元格开始。填充背景表示选定的单元格。若要选择连续的单元格,请按住 Shift 键并单击要选择的最后一个单元格。若要选择任意一组单元格,请按住 Ctrl 键并单击要添加到选择中的单元格。

Multiselected cells

移动代码单元格

您可以通过拖放操作在笔记本中上下移动单元格。对于代码单元格,拖放区域位于单元格编辑器的左侧,如下所示。对于渲染的 Markdown 单元格,您可以单击任意位置来拖放单元格。

Move a code cell

若要移动多个单元格,可以在选择中包含的任何单元格中使用相同的拖放区域。

键盘快捷方式 Alt+Arrow 也可以移动一个或多个选定的单元格。

删除代码单元格

若要删除代码,可以使用代码单元格工具栏中的“**删除**”图标。当选定的代码单元格处于命令模式时,您可以使用键盘快捷方式 dd

Delete a code cell

撤消上次更改

您可以使用 z 键撤消之前的更改,例如,如果您不小心进行了编辑,可以将其撤消到上一个正确状态,或者如果不小心删除了单元格,可以恢复它。

在代码和 Markdown 之间切换

笔记本编辑器允许您轻松地在 Markdown 和代码之间更改代码单元格。选择单元格右下角的语言选择器将允许您在 Markdown 和(如果适用)选定内核支持的任何其他语言之间切换。

Change language

您还可以使用键盘更改单元格类型。当单元格被选中并处于命令模式时,M 键将单元格类型切换为 Markdown,Y 键将单元格类型切换为代码。

设置 Markdown 后,您可以在代码单元格中输入 Markdown 格式的内容。

Raw Markdown displayed in code cell

若要渲染 Markdown 单元格,可以选择单元格工具栏中的复选标记,或使用键盘快捷方式 Ctrl+EnterShift+Enter

How to render Markdown

Rendered Markdown displayed in code cell

清除输出或重启/中断内核

如果您想清除所有代码单元格输出或重启/中断内核,可以使用主笔记本编辑器工具栏来实现。

Notebook Toolbar

启用/禁用行号

当您处于命令模式时,可以使用 L 键启用或禁用单个代码单元格中的行号。

Line numbers enabled in code cell

若要切换整个笔记本的行号,当任何单元格处于命令模式时,使用 Shift+L

Line numbers enabled for notebook

目录

若要浏览笔记本,请在活动栏中打开文件资源管理器。然后在侧边栏中打开“**大纲**”选项卡。

Table of contents

您可以使用大纲视图中的筛选器控件来包含 Markdown 标题、代码单元格和代码单元格符号。这些筛选器对应于以下设置

  • notebook.outline.showMarkdownHeadersOnly
  • notebook.outline.showCodeCells
  • notebook.outline.showCodeCellSymbols

**注意:** 默认情况下,大纲将只显示 Markdown。若要显示代码单元格,请启用以下设置:“**笔记本 > 大纲: 显示代码单元格**”。

Jupyter Notebook 编辑器中的 IntelliSense 支持

Python Jupyter Notebook 编辑器窗口具有完整的 IntelliSense 功能,包括代码补全、成员列表、方法的快速信息和参数提示。您在笔记本编辑器窗口中输入时可以像在代码编辑器中一样高效。

IntelliSense support

变量浏览器和数据查看器

在 Python Notebook 中,可以查看、检查、排序和筛选当前 Jupyter 会话中的变量。通过在运行代码和单元格后选择主工具栏中的“**变量**”图标,您将看到当前变量列表,该列表将随着代码中变量的使用而自动更新。变量窗格将在笔记本底部打开。

Variable Explorer

Variable Explorer

数据查看器

若要获取有关变量的更多信息,您还可以双击一行或使用变量旁边的“**在数据查看器中显示变量**”按钮,以便在数据查看器中查看变量的更详细视图。

Data Viewer

或者,您可以使用其他扩展(如 Data Wrangler)提供的数据查看体验。Data Wrangler 扩展提供了一个丰富的用户界面,用于显示有关数据的信息,并帮助您执行数据分析、质量检查、转换等。在我们的文档中了解有关 Data Wrangler 扩展的更多信息。

筛选行

在数据查看器中筛选行可以通过在每列顶部的文本框中键入内容来完成。键入要搜索的字符串,并找到该列中包含该字符串的任何行

Data Viewer

如果要查找精确匹配项,请在筛选器前加上“=”。

Data Viewer

更复杂的筛选可以通过键入正则表达式来完成。

Data Viewer

保存绘图

若要从笔记本中保存绘图,只需将鼠标悬停在输出上,然后选择右上角的“**保存**”图标。

Save output

**注意:** 支持渲染使用 matplotlibAltair 创建的绘图。

自定义笔记本差异比较

从底层来看,Jupyter Notebooks 是 JSON 文件。JSON 文件中的分段呈现为单元格,由三个组件组成:输入、输出和元数据。使用基于行的差异比较笔记本中所做的更改很困难且难以解析。笔记本的富差异比较编辑器让您可以轻松查看单元格每个组件的更改。

您甚至可以自定义要在差异比较视图中显示哪些类型的更改。在右上角,选择工具栏中的溢出菜单项,以自定义要包含哪些单元格组件。输入差异将始终显示。

Custom notebook diffing

若要详细了解 VS Code 中的 Git 集成,请访问VS Code 中的源代码管理

调试 Jupyter Notebook

调试 Jupyter 笔记本有两种不同的方式:一种更简单的模式,称为“逐行运行”,以及完整的调试模式。

**注意:** 这两项功能都需要 ipykernel 6+。有关安装或升级 ipykernel 的详细信息,请参阅此 Wiki 页面

逐行运行

逐行运行允许您一次执行一个单元格的一行,而不会受到其他 VS Code 调试功能的干扰。若要开始,请选择单元格工具栏中的“**逐行运行**”按钮。

Run by line button

使用相同的按钮逐句执行。您可以单击单元格的“**停止**”按钮提前停止,或单击工具栏中的“**继续**”按钮以继续运行到单元格末尾。

调试单元格

如果您想使用 VS Code 中支持的完整调试功能,例如断点以及单步进入其他单元格和模块的功能,则可以使用完整的 VS Code 调试器。

  1. 首先,通过单击笔记本单元格的左边距来设置所需的任何断点。
  2. 然后选择“**运行**”按钮旁边的菜单中的“**调试单元格**”按钮。这将在调试会话中运行该单元格,并会在运行的任何代码(即使在不同单元格或 .py 文件中)中的断点处暂停。
  3. 您可以像在 VS Code 中通常一样使用“调试”视图、“调试控制台”和调试工具栏中的所有按钮。

请注意,调试 Jupyter 笔记本中的单元格不使用 launch.json 中的任何调试配置。相反,可以通过 jupyter.debugJustMyCode 等设置进行自定义。

Debug cell button

搜索笔记本

您可以使用键盘快捷方式 Ctrl/Cmd + F 在笔记本中搜索(或通过筛选搜索选项搜索部分内容)。单击“筛选”选项(漏斗图标)以搜索

  • Markdown 单元格输入(**Markdown 源**)
  • Markdown 单元格输出(**渲染的 Markdown**)
  • 代码单元格输入(**代码单元格源**)
  • 代码单元格输出(**单元格输出**)

笔记本搜索默认仅筛选单元格输入。

Search options

连接到远程 Jupyter 服务器

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

连接到远程 Jupyter 服务器

  1. 打开笔记本右上角的“内核选择器”按钮(或从命令面板运行“**笔记本: 选择笔记本内核**”命令)。

    Notebook kernel picker

  2. 选择“**现有 Jupyter 服务器**”选项以连接到现有 Jupyter 服务器。

    Select existing Jupyter server

  3. 若要首次连接到现有服务器,请选择“**输入正在运行的 Jupyter 服务器的 URL**”。

    Choose to connect to an existing server

  4. 当系统提示“**输入正在运行的 Jupyter 服务器的 URL**”时,请提供服务器的 URI(主机名),并在其中包含 ?token= URL 参数作为身份验证令牌。(如果您在启用了身份验证令牌的 VS Code 终端中启动服务器,则带有令牌的 URL 通常会出现在终端输出中,您可以从中复制。)或者,您可以在提供 URI 后指定用户名和密码。

    Prompt to supply a Jupyter server URI

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

数据科学配置文件模板

配置文件允许您根据当前项目或任务快速切换扩展、设置和 UI 布局。为了帮助您开始使用 Jupyter Notebooks,您可以使用数据科学配置文件模板,它是一个精选的配置文件,其中包含有用的扩展、设置和代码片段。您可以直接使用配置文件模板,也可以将其用作进一步自定义以适应您自己工作流的起点。

您通过“**配置文件**”>“**创建配置文件...**”下拉菜单选择一个配置文件模板

Create Profile dropdown with profile templates

选择配置文件模板后,您可以查看设置和扩展,如果不想将某些项包含在新配置文件中,可以删除它们。在基于模板创建新配置文件后,对设置、扩展或 UI 所做的更改将保留在您的配置文件中。