JupyterLab GitHub

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

这个扩展的功能

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

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

这个扩展不提供的功能

这不是一个提供完整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应用。不推荐第二种方法，将在未来版本中移除。

获取访问令牌（推荐）

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

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

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

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

登录您的GitHub账户。
前往https://github.com/settings/developers，并选择左侧的"OAuth Apps"选项卡。
点击"New OAuth App"按钮。
在表单中填写名称、主页URL、描述和回调URL。这个扩展实际上并不使用OAuth，所以这些值实际上并不重要，您只需要输入它们来注册应用程序。
点击"Register application"按钮。
您应该会被带到一个显示新应用程序信息的新页面。如果您看到显示"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是您想要打开的仓库名称。