ghapi

ghapi提供了对整个GitHub API的100%始终更新的覆盖。由于我们自动将OpenAPI规范转换为Pythonic API，ghapi始终与GitHub API的最新变更保持同步。此外，由于这一切都是动态完成的，整个软件包大小仅为35kB！

使用ghapi，您几乎可以自动化通过GitHub网页界面或git客户端可以执行的任何操作，例如：

打开、列出、评论或修改问题或拉取请求
创建、列出或修改git标签或GitHub发布，包括上传发布资产
配置和运行GitHub Actions和webhooks
设置GitHub用户和组织
管理您的部署
...还有更多功能。

有两种使用ghapi的方式：通过Python或从命令行。下面概述了每种方式。

安装

安装时，运行pip install ghapi或conda install -c fastai ghapi。

如何使用 - Python

在整个文档中，您将看到以下格式显示的代码输入和输出：

1+1

我们建议在官方网站上阅读文档，而不是在GitHub上，因为本页描述的部分功能在GitHub查看器中无法使用。

所有文档都直接以Jupyter Notebook的形式提供，例如，您正在阅读的当前页面可作为notebook在这里获取。要在Google Colab中打开任何页面作为交互式notebook，请点击页面顶部的Colab徽章。

要访问GitHub API，首先创建一个GhApi对象：

from ghapi.all import GhApi
api = GhApi()

API的每个部分都在api对象本身中包含文档。例如，以下是如何通过显示对象来探索API提供的功能组：

api

然后我们可以探索API在每个组中提供的端点，例如git组：

api.git

git.create_blob(owner, repo, content, encoding): 创建一个blob
git.get_blob(owner, repo, file_sha): 获取一个blob
git.create_commit(owner, repo, message, tree, parents, author, committer, signature): 创建一个提交
git.get_commit(owner, repo, commit_sha): 获取一个提交
git.list_matching_refs(owner, repo, ref, per_page, page): 列出匹配的引用
git.get_ref(owner, repo, ref): 获取一个引用
git.create_ref(owner, repo, ref, sha, key): 创建一个引用
git.update_ref(owner, repo, ref, sha, force): 更新一个引用
git.delete_ref(owner, repo, ref): 删除一个引用
git.create_tag(owner, repo, tag, message, object, type, tagger): 创建一个标签对象
git.get_tag(owner, repo, tag_sha): 获取一个标签
git.create_tree(owner, repo, tree, base_tree): 创建一个树
git.get_tree(owner, repo, tree_sha, recursive): 获取一个树

以下是如何了解你想使用的端点，例如：

api.git.get_ref

git.get_ref(owner, repo, ref): 获取一个引用

在Jupyter Notebook中，所有端点都提供完整的Tab补全、参数列表等功能。端点调用方式与标准Python方法相同：

api.git.get_ref(owner='fastai', repo='fastcore', ref='heads/master')

ref: refs/heads/master
node_id: MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy
url: https://api.github.com/repos/fastai/fastcore/git/refs/heads/master
object:
- sha: 0e3084ed009baa51db38a640ae7c23d638af2756
- type: commit
- url: https://api.github.com/repos/fastai/fastcore/git/commits/0e3084ed009baa51db38a640ae7c23d638af2756

要使用 ghapi 访问需要身份验证的操作（除了在 GitHub Actions 中运行时），你需要一个 GitHub 个人访问令牌，这是用于访问你账户的秘密代码。如果你还没有，点击这里创建一个。你将被要求输入一个名称 - 随便选择一个，比如"ghapi"。你还需要选择"作用域"；这限制了你使用此令牌可以通过 API 执行的操作。如果你不确定，点击"repo"、"gist"、"notifications"和"workflow"。然后点击屏幕底部的"Generate Token"，并复制令牌（显示的一长串字母和数字）。你可以通过点击令牌旁边的小剪贴板图标轻松完成复制。

与其将该令牌粘贴到每个脚本中，最简单的方法是将其保存为环境变量。如果将其保存为 $GITHUB_TOKEN，那将最为方便，所以在你的 .bashrc 或 .zshrc 文件末尾添加以下内容：

export GITHUB_TOKEN=xxx

...将 xxx 替换为你刚刚复制的令牌。（修改后别忘了 source 该文件。），传递一个 [GitHub 令牌]。

除了 token，你还可以传递任何你想自动插入相关方法的参数，比如 owner 和 repo：

api = GhApi(owner='fastai', repo='fastcore', token=github_token)

现在我们可以重复之前的方法，但只需传递 ref：

api.git.get_ref('heads/master')

ref: refs/heads/master
node_id: MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy
url: https://api.github.com/repos/fastai/fastcore/git/refs/heads/master
object:
- sha: 0e3084ed009baa51db38a640ae7c23d638af2756
- type: commit
- url: https://api.github.com/repos/fastai/fastcore/git/commits/0e3084ed009baa51db38a640ae7c23d638af2756

现在我们已经提供了令牌，我们可以使用需要身份验证的端点，比如创建一个问题：

issue = api.issues.create("记得查看 GhApi！")

既然我们已经查看了 GhApi，让我们关闭这个问题。😎

api.issues.update(issue.number, state='closed')

如何使用 - 命令行

你可以通过命令行使用 GhApi，并且可以访问 GitHub API 中的几乎所有内容。这里我们概述一下其中一个命令行程序 ghapi - 有关所有可用程序的详细信息，请参阅完整的 CLI 文档页面。

我们强烈建议为 ghapi 启用 tab 补全功能，你可以通过在 ~/.bashrc 或 ~/.zshrc 文件末尾放置以下命令来实现：

eval "$(completion-ghapi --install)"

要开始使用 ghapi 命令，首先找到你想执行的操作的名称，例如通过搜索完整 API 参考。

要使用 ghapi，将方法名称（与你在 Python API 中使用的完全相同）作为第一个参数传递，然后是任何必需的位置参数，最后是关键字参数，每个参数名前加上 "--"。例如，git.get_ref需要三个参数：owner、repo和ref。如果我们希望将前两个作为位置参数传递，最后一个作为命名参数，那么我们可以这样调用：

ghapi git.get_ref fastai ghapi-test --ref heads/master

如果您启用了tab补全功能，那么在输入ghapi g之后，尝试按Tab键，您将看到GitHub API中所有以g开头的操作组。如果您继续输入，例如ghapi git.，然后再次按Tab键，您将看到git组中所有可用的操作，即：

git.create_blob git.create_commit git.create_ref git.create_tag git.create_tree git.delete_ref git.get_blob git.get_commit git.get_ref git.get_tag git.get_tree git.list_matching_refs git.name git.update_ref git.verbs

如果您在操作名称后只传递--help，您将看到所有接受的参数的完整列表，以及官方GitHub文档的链接。

ghapi git.get_ref --help
>>> git.get_ref(owner, repo, ref)
>>> https://docs.github.com/rest/reference/git#get-a-reference

除了--help和GitHub操作参数外，您还可以传递以下参数：

--headers：要传递的额外头部列表，JSON编码
--token：GitHub认证令牌
--debug：在发送请求前打印请求内容