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. 安装
pipinstallPyGithub2. 认证（必须）
GitHub API 要求认证以提高速率限制（未认证：60次/小时；认证：5000次/小时）。
推荐方式：Personal Access Token (PAT)
- 创建路径：GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
- 权限建议：
repo：读写私有/公开仓库user：读取用户信息admin:repo_hook：管理 Webhook（可选）
初始化客户端
fromgithubimportGithub,Auth# 方式1：使用 Token（推荐）auth=Auth.Token("your_github_token")g=Github(auth=auth)# 方式2：经典方式（仍有效）g=Github("your_github_token")# 方式3：GitHub Enterpriseg=Github(base_url="https://github.your-company.com/api/v3",auth=auth)# 验证print(g.get_user().login)# 输出你的用户名🔒 安全提示：切勿硬编码 Token！使用环境变量或
.env文件：importos g=Github(auth=Auth.Token(os.getenv("GITHUB_TOKEN")))
三、核心对象模型与常用操作
PyGithub 的设计哲学是：客户端 → 资源对象 → 资源操作。主要对象包括：
1. 用户（User）
# 获取当前用户me=g.get_user()print(me.login,me.email,me.public_repos)# 获取其他用户octocat=g.get_user("octocat")forrepoinoctocat.get_repos()[:3]:print(repo.name,repo.stargazers_count)2. 仓库（Repository）— 最常用
repo=g.get_repo("microsoft/vscode")# 基础信息print(repo.name,repo.description,repo.stargazers_count)print("最后推送时间:",repo.pushed_at)# 注意：用 pushed_at 而非 _updated_at [10]# 获取 Topicsprint(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")fordayinclones["clones"]:print(day.timestamp,day.count)3. Issue 与 PR 管理
# 获取开放的 Issueforissueinrepo.get_issues(state="open",labels=["bug"]):print(f"#{issue.number}:{issue.title}")# 创建 Issuerepo.create_issue(title="自动创建的 Issue",body="由 PyGithub 脚本生成",labels=["automation"])# 获取 PR（PR 本质是特殊的 Issue）pulls=repo.get_pulls(state="open")forprinpulls:print(pr.title,pr.user.login)4. 文件内容管理（Content Management）
# 获取文件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 管理
# 创建 Releaserepo.create_git_release(tag="v1.0.0",name="Version 1.0",message="Initial stable release",draft=False,prerelease=False)# 获取最新 Releaselatest=repo.get_latest_release()print(latest.tag_name,latest.published_at)6. 分支与 Commit
# 获取分支branch=repo.get_branch("main")print(branch.commit.sha)# 获取提交历史commits=repo.get_commits()forcommitincommits[:5]:print(commit.sha,commit.commit.message)四、高级功能
1. 错误处理
fromgithubimportGithubExceptiontry:repo=g.get_repo("non/existent")exceptGithubExceptionase:ife.status==404:print("仓库不存在")elife.status==403:print("权限不足或速率限制")2. 分页处理
PyGithub 自动处理分页，你只需遍历即可：
# 自动获取所有 Issue（即使超过 30 条）forissueinrepo.get_issues(state="all"):print(issue.title)3. 企业版支持
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()而非字符串直接传入（新版本推荐） - 及时关闭连接（虽非强制，但良好习惯）：
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 几乎是必选项。！
