PyGithub用法详解

PyGithub 是 Python 生态中最主流、功能最完整的 GitHub API 客户端库 ，它对 GitHub REST API v3（官方当前稳定版）进行了全面封装，提供面向对象的接口，让开发者能以自然、简洁的方式操作 GitHub 上的资源（如仓库、用户、Issue、PR、Release 等），而无需手动拼接 URL、处理 JSON 或管理认证细节。

一、核心特点（Why PyGithub?）

PyGithub 具备以下优势：

特性	说明
✅ 官方风格封装	虽非 GitHub 官方出品，但被社区广泛认可为"事实标准"，API 设计贴近 GitHub 原生概念
✅ 面向对象接口	`repo.get_issues()` 比 `requests.get("/repos/.../issues")` 更直观
✅ 完整 API 覆盖	支持 99%+ 的 GitHub REST API v3 功能（含 Enterprise）
✅ 类型安全（Type Hints）	新版本提供类型注解，提升 IDE 补全和代码可靠性
✅ 企业级支持	可连接 GitHub Enterprise 实例
✅ 活跃维护	持续更新，兼容最新 GitHub 功能

⚠️ 注意：不要与已废弃的 python-github2（仅支持 API v2）混淆。

二、安装与认证

1. 安装

bash 复制代码

pip install PyGithub

2. 认证（必须）

GitHub API 要求认证以提高速率限制（未认证：60次/小时；认证：5000次/小时）。

推荐方式：Personal Access Token (PAT)

创建路径：GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
权限建议：
- repo：读写私有/公开仓库
- user：读取用户信息
- admin:repo_hook：管理 Webhook（可选）

初始化客户端

python 复制代码

from github import Github, Auth

# 方式1：使用 Token（推荐）
auth = Auth.Token("your_github_token")
g = Github(auth=auth)

# 方式2：经典方式（仍有效）
g = Github("your_github_token")

# 方式3：GitHub Enterprise
g = Github(
    base_url="https://github.your-company.com/api/v3",
    auth=auth
)

# 验证
print(g.get_user().login)  # 输出你的用户名

🔒 安全提示：切勿硬编码 Token ！使用环境变量或 .env 文件：
python 复制代码
import os
g = Github(auth=Auth.Token(os.getenv("GITHUB_TOKEN")))

三、核心对象模型与常用操作

PyGithub 的设计哲学是：客户端 → 资源对象 → 资源操作。主要对象包括：

1. 用户（User）

python 复制代码

# 获取当前用户
me = g.get_user()
print(me.login, me.email, me.public_repos)

# 获取其他用户
octocat = g.get_user("octocat")
for repo in octocat.get_repos()[:3]:
    print(repo.name, repo.stargazers_count)

2. 仓库（Repository）--- 最常用

python 复制代码

repo = g.get_repo("microsoft/vscode")

# 基础信息
print(repo.name, repo.description, repo.stargazers_count)
print("最后推送时间:", repo.pushed_at)  # 注意：用 pushed_at 而非 _updated_at [10]

# 获取 Topics
print(repo.get_topics())  # ['editor', 'ide', 'typescript', ...]

# 流量统计 [2]
views = repo.get_views_traffic(per="week")
print(f"本周访问量: {views['count']}, 独立访客: {views['uniques']}")

# 克隆统计
clones = repo.get_clones_traffic(per="day")
for day in clones["clones"]:
    print(day.timestamp, day.count)

3. Issue 与 PR 管理

python 复制代码

# 获取开放的 Issue
for issue in repo.get_issues(state="open", labels=["bug"]):
    print(f"#{issue.number}: {issue.title}")

# 创建 Issue
repo.create_issue(
    title="自动创建的 Issue",
    body="由 PyGithub 脚本生成",
    labels=["automation"]
)

# 获取 PR（PR 本质是特殊的 Issue）
pulls = repo.get_pulls(state="open")
for pr in pulls:
    print(pr.title, pr.user.login)

4. 文件内容管理（Content Management）

python 复制代码

# 获取文件
file = repo.get_contents("README.md")
print(file.decoded_content.decode())

# 创建文件
repo.create_file(
    path="new_file.txt",
    message="Add new file",
    content="Hello from PyGithub!",
    branch="main"
)

# 更新文件（需提供原 SHA）
file = repo.get_contents("existing.txt")
repo.update_file(
    path=file.path,
    message="Update content",
    content="New content",
    sha=file.sha,
    branch="main"
)

# 删除文件
repo.delete_file(
    path="old_file.txt",
    message="Remove old file",
    sha=file.sha,
    branch="main"
)

5. Release 管理

python 复制代码

# 创建 Release
repo.create_git_release(
    tag="v1.0.0",
    name="Version 1.0",
    message="Initial stable release",
    draft=False,
    prerelease=False
)

# 获取最新 Release
latest = repo.get_latest_release()
print(latest.tag_name, latest.published_at)

6. 分支与 Commit

python 复制代码

# 获取分支
branch = repo.get_branch("main")
print(branch.commit.sha)

# 获取提交历史
commits = repo.get_commits()
for commit in commits[:5]:
    print(commit.sha, commit.commit.message)

四、高级功能

1. 错误处理

python 复制代码

from github import GithubException

try:
    repo = g.get_repo("non/existent")
except GithubException as e:
    if e.status == 404:
        print("仓库不存在")
    elif e.status == 403:
        print("权限不足或速率限制")

2. 分页处理

PyGithub 自动处理分页，你只需遍历即可：

python 复制代码

# 自动获取所有 Issue（即使超过 30 条）
for issue in repo.get_issues(state="all"):
    print(issue.title)

3. 企业版支持

python 复制代码

g = Github(
    base_url="https://github.acme.com/api/v3",
    auth=Auth.Token("enterprise_token")
)

五、典型应用场景

场景	实现方式
🤖 自动化 Issue 管理	定期关闭 stale Issue、自动打标签
📦 自动发布 Release	CI/CD 成功后调用 `create_git_release`
📊 仓库数据分析	抓取 star/fork/traffic 数据做可视化
🧪 代码质量监控	获取 Code Scanning Alerts
🔄 跨仓库同步	从 A 仓库读文件，写入 B 仓库
📬 自定义通知机器人	监控 PR 状态并发送企业微信消息

六、最佳实践

使用 Auth.Token() 而非字符串直接传入（新版本推荐）
及时关闭连接 （虽非强制，但良好习惯）：
python 复制代码
```
g = Github(auth=auth)
# ... 操作 ...
g.close()
```
避免硬编码敏感信息，使用环境变量
合理处理速率限制 ：捕获 RateLimitExceeded 异常
优先使用 pushed_at 获取代码更新时间 ，而非 _updated_at

七、学习资源

官方文档：https://pygithub.readthedocs.io/
示例代码：doc/examples/ 目录（项目源码中）
测试用例：tests/ 目录包含大量实战场景
项目地址：https://github.com/PyGithub/PyGithub

总结

PyGithub 是 Python 开发者与 GitHub 交互的首选工具。它将复杂的 HTTP API 调用转化为直观的 Python 对象操作，极大提升了开发效率和代码可读性。无论是简单的仓库信息抓取，还是复杂的自动化工作流，PyGithub 都能胜任。

💡 提示：如果你正在构建 GitHub 相关的自动化脚本、数据爬虫、CI/CD 插件或内部工具，PyGithub 几乎是必选项。！