JupyterLab GitHub

一个用于访问GitHub仓库的JupyterLab扩展。

这个扩展的功能

安装此扩展后，JupyterLab左侧区域将添加一个额外的文件浏览器标签。这个文件浏览器允许您选择GitHub组织和用户，浏览他们的仓库，并打开这些仓库中的文件。如果这些文件是笔记本，您可以像运行其他笔记本一样运行它们。您还可以将内核附加到文本文件并运行它们。基本上，您应该能够打开仓库中JupyterLab可以处理的任何文件。

以下是插件在GitHub上打开这个文件的截图：

这个扩展不提供的功能

这不是一个提供完整GitHub访问功能的扩展，如保存文件、提交更改、复刻仓库等。要实现这些功能，它需要或多或少地重新创造GitHub网站，这将大大增加扩展的复杂性。

关于速率限制的说明

此扩展既有客户端组件（即与JupyterLab打包的JavaScript），也有服务器端组件（即添加到Jupyter服务器的Python代码）。这个扩展在没有服务器扩展的情况下也能工作，但有一个主要缺点：当向GitHub发出未经认证的请求时（我们必须这样做以获取仓库数据），GitHub对我们可以发出的请求数量施加了相当严格的速率限制。因此，您可能在几分钟的工作后就会达到这个限制。然后您将不得不等待最多一小时才能重新获得访问权限。

因此，我们建议您花时间和精力同时设置服务器扩展和实验室扩展，这将允许您访问更高的速率限制。这个过程在安装部分有描述。

先决条件

• JupyterLab > 3.0
• 服务器扩展需要GitHub账户

安装

如上所述，这个扩展既有服务器扩展，也有实验室扩展。从PyPI安装时，默认会安装这两个扩展，但如果您使用JupyterLab的扩展管理器，可能只安装了实验室扩展。

我们建议完成以下步骤以避免受到速率限制。服务器扩展的目的是添加您需要从https://github.com/settings/developers 获取的GitHub凭据，然后代理您对GitHub的请求。

对于3版本以前的JupyterLab，请参阅2.x分支上的说明。

1. 安装服务器和预构建的实验室扩展

JupyterLab 4.x

要安装服务器扩展和（预构建的）实验室扩展，在终端中输入以下命令：

pip install jupyterlab-github

JupyterLab 3.x

我们需要将扩展版本固定为3.0.1以使其在JupyterLab 3.x上工作。

pip install 'jupyterlab-github==3.0.1'

重启JupyterLab后，扩展应该能够工作，您可以亲身体验被速率限制的乐趣！

2. 从GitHub获取凭据

从GitHub获取凭据有两种方法： (1) 您可以获取访问令牌，(2) 您可以注册OAuth应用。 不推荐第二种方法，将在未来版本中移除。

获取访问令牌（推荐）

您可以按照以下步骤获取访问令牌：

1. 验证您的GitHub电子邮件地址。
2. 进入GitHub上的账户设置，从左侧面板选择"Developer Settings"。
3. 在左侧，选择"Personal access tokens"。
4. 点击"Generate new token"按钮，并输入您的密码。
5. 给令牌一个描述，并勾选"repo"范围复选框。
6. 点击"Generate token"。
7. 您将得到一个字符串，这就是您的访问令牌。 请记住，这个令牌实际上是您GitHub账户的密码。 切勿在网上分享或将令牌存入版本控制系统中，因为他人可以利用它访问您在GitHub上的所有数据。

设置OAuth应用程序（已弃用）

这种与GitHub认证的方法已被弃用，将在未来的版本中移除。 新用户应使用访问令牌方法。 您可以按照以下步骤在GitHub上注册OAuth应用程序：

1. 登录您的GitHub账户。
2. 前往https://github.com/settings/developers，并选择左侧的"OAuth Apps"选项卡。
3. 点击"New OAuth App"按钮。
4. 在表单中填写名称、主页URL、描述和回调URL。 这个扩展实际上并不使用OAuth，所以这些值实际上并不重要， 您只需要输入它们来注册应用程序。
5. 点击"Register application"按钮。
6. 您应该会被带到一个显示新应用程序信息的新页面。 如果您看到显示"Client ID"和"Client Secret"的字段，恭喜您！ 这些就是我们需要的字符串，您已成功设置了应用程序。

需要注意的是，"Client Secret"字符串顾名思义是一个秘密。 切勿在网上分享这个值，因为他人可能会利用它在GitHub上冒充您。

3. 启用和配置服务器扩展

如果您使用pip安装，服务器扩展将在新的JupyterLab安装中默认启用。 如果您使用JupyterLab中的扩展管理器，请卸载扩展并按照第(1)点的说明重新安装。

通过以下命令确认服务器扩展已安装并启用：

jupyter server extension list

您应该看到以下内容：

- Validating jupyterlab_github...
     jupyterlab_github 4.0.0 OK

在一些较旧的安装（例如旧版JupyterHub）中使用jupyter notebook服务器而不是新的jupyter-server，扩展需要显示在旧的serverextensions列表中（注意：server和extension之间没有空格）：

jupyter serverextension list

如果扩展未启用，请运行：

jupyter server extension enable jupyterlab_github

或者如果使用旧版notebook服务器：

jupyter serverextension enable jupyterlab_github

现在您需要将从GitHub获得的凭证添加到服务器配置文件中。生成配置文件的说明可以在这里找到。 一旦您找到了这个文件，请在其中添加以下行：

c.GitHubConfig.access_token = '< YOUR_ACCESS_TOKEN >'

其中"< YOUR_ACCESS_TOKEN >"是您上面获得的字符串值。 如果您生成了OAuth应用程序，请输入以下内容：

c.GitHubConfig.client_id = '< YOUR_CLIENT_ID >'
c.GitHubConfig.client_secret = '< YOUR_CLIENT_SECRET >'

其中"< YOUR_CLIENT_ID >"和"< YOUR_CLIENT_SECRET >"是您上面获得的应用程序值。

这样，您就完成了！启动JupyterLab并在左侧寻找GitHub选项卡！

自定义

您可以设置插件在启动时显示特定的仓库。 在设置菜单中打开"高级设置"编辑器， 在GitHub设置下添加

{
  "defaultRepo": "owner/repository"
}

其中owner是GitHub用户/组织， repository是您想要打开的仓库名称。