PyGithub 快速上手指南：从零开始用 Python 操作 GitHub API v3

开发工具【免费下载链接】PyGithubTyped interactions with the GitHub API v3项目地址https://gitcode.com/gh_mirrors/py/PyGithub点击查看免费下载PyGithub 是一个类型完备Typed的 Python 库用于调用 GitHub REST API v3让你能够从 Python 脚本中管理仓库、用户资料、组织、Issues、Pull Request 等 GitHub 资源。本文以官方 doc/introduction.rst 为骨架结合仓库源码展开带你完成安装、认证、实例化、对象操作与连接管理的完整入门并深入理解auth、lazy、api_version、base_url等关键参数背后的实现细节。一、PyGithub 是什么PyGithub 的核心价值在于把 GitHub API v3 的 HTTP 请求与 JSON 响应封装为一个个 Python 对象与方法。你不再需要手写requests.get(https://api.github.com/...)并自行解析 JSON而是通过Github入口对象获取Repository、NamedUser、Organization、Issue、PullRequest等对象直接读取属性、调用方法完成操作。整个包以 github/MainClass.py 中的Github类为总入口以 github/Requester.py 为底层 HTTP 请求引擎包内每个功能模块如 Repository.py、Issue.py对应 GitHub API 的某一类资源。仓库根目录下还提供了 ARCHITECTURE.md 和 doc/Design.md 供深入理解设计。二、下载与安装PyGithub 已发布到 Python Package Index最简单的安装方式是通过 pip 直接安装pip install PyGithub安装后即可通过以下方式导入并开始使用from github import Github如果你需要最新的开发版本也可以从仓库克隆源码后本地安装。安装完成后仓库的依赖与开发环境要求可参考 pyproject.toml 和 tox.ini。三、快速教程第一个 PyGithub 脚本官方文档给出一段“极简教程”它覆盖了从认证到操作对象的完整链路是理解 PyGithub 的最佳起点。1. 创建 Github 实例首先创建Github实例。注意认证信息通过github.Auth模块提供而不是直接传入裸 tokenfrom github import Github # Authentication is defined via github.Auth from github import Auth # Using an access token auth Auth.Token(access_token) # Public Web Github g Github(authauth) # Github Enterprise with custom hostname g Github(authauth, base_urlhttps://{hostname}/api/v3) # Use lazy mode g Github(authauth, lazyTrue) # Set a Github API version g Github(authauth, api_version2022-11-28)2. 操作你的 Github 对象拿到实例后就可以遍历、读取、修改 GitHub 资源了for repo in g.get_user().get_repos(): print(repo.name) repo.edit(has_wikiFalse) # to see all the available attributes and methods print(dir(repo))这段代码的含义是g.get_user()获取当前认证用户对象get_repos()返回该用户的所有仓库对每个仓库打印名称、通过edit(has_wikiFalse)关闭 wiki并用dir(repo)查看该仓库对象上全部可用的属性和方法——这正是 PyGithub“对象即 API”的直观体现。3. 关闭连接PyGithub 底层维护着 HTTP 连接池使用完毕后应显式关闭g.close()在 MainClass.py 的源码中close()委托给内部Requester.close()同时Github实现了上下文管理器协议__enter__/__exit__因此更推荐的写法是with Github(authauth) as g: for repo in g.get_user().get_repos(): print(repo.name) # 退出 with 块时自动调用 g.close()四、深入Github 实例的构造参数Github.__init__的定义位于 MainClass.py其完整签名如下Github( login_or_tokenNone, # 已废弃请改用 authgithub.Auth.Login(...) 或 Auth.Token(...) passwordNone, # 已废弃请改用 authgithub.Auth.Login(...) jwtNone, # 已废弃请改用 Auth.AppAuth / Auth.AppAuthToken app_authNone, # 已废弃请改用 Auth.AppInstallationAuth base_urlConsts.DEFAULT_BASE_URL, timeoutConsts.DEFAULT_TIMEOUT, user_agentConsts.DEFAULT_USER_AGENT, per_pageConsts.DEFAULT_PER_PAGE, verifyTrue, retrygithub.Github.default_retry, pool_sizeNone, seconds_between_requestsConsts.DEFAULT_SECONDS_BETWEEN_REQUESTS, seconds_between_writesConsts.DEFAULT_SECONDS_BETWEEN_WRITES, authNone, lazyFalse, api_versionNone, )各参数的核心作用如下参数默认值说明base_urlhttps://api.github.com见 Consts.pyAPI 基础地址连接 GitHub Enterprise 时改为https://{hostname}/api/v3timeout15秒请求超时GitHub 要求 API 请求在 10 秒内完成默认值略大于 10 秒以覆盖网络与前端延迟user_agentPyGithub/Python请求的 User-Agentper_page30分页时每页条数GitHub 允许最大 100verifyTrue是否校验 TLS 证书可传布尔值或证书路径字符串retryGithubRetry()重试策略可传整数或urllib3.util.Retry对象传None表示禁用重试pool_sizeNone连接池大小seconds_between_requests0.25连续两次请求的最小间隔秒用于规避 GitHub 次级速率限制seconds_between_writes1.0连续两次写请求的最小间隔秒authNone认证方式来自github.Auth模块lazyFalse是否启用惰性Lazy模式见下文api_versionNoneGitHub API 版本如2022-11-28部分 PyGithub 方法在其实现不支持该版本时会自动降级设为None则不指定任何版本源码中每个参数都有对应的assert类型检查MainClass.py传入错误类型会在构造阶段立即抛出异常这是 PyGithub 工程化严谨性的体现。遗留参数与弃用警告login_or_token、password、jwt、app_auth这些早期版本的参数仍然兼容但构造方法内部会发出DeprecationWarning并自动将它们转换为等价的Auth对象见 MainClass.py。新代码应当一律使用auth...关键字参数。五、认证方式详解github.Auth认证是使用 PyGithub 的第一步也是官方文档强调的重点。所有认证类都继承自 github/Auth.py 中的抽象基类Auth它定义了token_type与token两个抽象属性最终以Authorization: token_type token的形式写入请求头authentication()方法Auth.py。PyGithub 支持的认证方式包括Auth.Login(login, password)用户名 密码登录生成 HTTP Basic 认证头token 为 base64 编码的login:password。Auth.Token(token)单一常量 token个人访问令牌 / OAuth token是最常用的方式token_type为token。Auth.NetrcAuth()从.netrc文件读取凭据见下文。Auth.AppAuth(app_id, private_key)以 GitHub App 身份认证使用私钥签发 JWTRS256 算法。Auth.AppAuthToken(jwt)直接使用一个已签发的常量 JWT 认证。Auth.AppInstallationAuth(app_auth, installation_id, token_permissions)以某个 App 安装Installation身份认证自动获取并刷新安装访问令牌。Auth.AppUserAuth(...)以 GitHub App 名义代表用户认证支持 token 过期自动刷新依赖 refresh token。各认证类的_masked_token属性会在日志中把真实凭据替换为脱敏文本避免敏感信息泄露Auth.py。1. 用户名密码登录from github import Auth from github import Github auth Auth.Login(user_login, password) g Github(authauth) print(g.get_user().login)2. OAuth Token推荐auth Auth.Token(access_token) g Github(authauth) print(g.get_user().login)3. Netrc 认证先在.netrc文件中写入凭据machine api.github.com login token password TOKEN必要时通过环境变量NETRC指定该文件的路径。然后在代码中auth Auth.NetrcAuth() g Github(authauth) print(g.get_user().login)从源码看NetrcAuth会在withRequester阶段通过requests.utils.get_netrc_auth(requester.base_url)解析对应主机如api.github.com的凭据若解析不到会抛出运行时错误Auth.py。4. GitHub App 认证GitHub App 认证使用的端点有限官方文档明确建议以 App 身份认证时入口不应是github.Github而应使用github.GithubIntegrationfrom github import Auth from github import GithubIntegration auth Auth.AppAuth(123456, private_key) gi GithubIntegration(authauth) for installation in gi.get_installations(): print(installation.id)再通过 installation 拿到一个以安装身份工作的Github实例installation gi.get_installations()[0] g installation.get_github_for_installation() print(g.get_repo(user/repo).name)AppAuth内部使用 JWT 签名器生成 payload 为{iat, exp, iss}的令牌Auth.py其中iat默认提前 60 秒DEFAULT_JWT_ISSUED_AT -60、exp默认 300 秒GitHub 规定 JWT 有效期最长 600 秒这些常量定义在 Consts.py。5. App 安装认证自动刷新auth Auth.AppAuth(123456, private_key).get_installation_auth(installation_id, token_permissions) g Github(authauth) print(g.get_repo(user/repo).name)AppInstallationAuth.token属性会惰性获取安装访问令牌并在令牌即将过期提前 20 秒见 Auth.py 的ACCESS_TOKEN_REFRESH_THRESHOLD_SECONDS时自动重新获取实现无缝续期。更完整的认证示例与每种方式的适用场景可参考 doc/examples/Authentication.rst 与 doc/utilities.rst。六、Lazy 模式惰性加载Github(authauth, lazyTrue)会启用惰性模式。在该模式下由这个实例创建的“可完成对象”Completable Objects如AuthenticatedUser、Repository默认不立即从 API 拉取全部数据而是延迟到属性或方法真正被访问时才请求。get_user()的源码体现了这一点lazy未显式指定时按实例的惰性设置决定是否先返回未完成completedFalse的对象MainClass.py。惰性模式适合只关心对象上少数属性、希望减少初始请求的场景而需要对象完整数据时可通过Github.withLazy(lazy)复制一份配置相同但惰性设置不同的实例或对对象显式调用complete()。更细致的说明见 doc/examples/LazyMode.rst 与相关测试 tests/GithubObject.py。七、更多入口方法除get_user()/get_repo()外Github类还提供了大量面向全局资源的方法例如get_rate_limit()查询当前速率限制MainClass.pyget_user_by_id(user_id)、get_users(since...)按 ID 或分页获取用户get_repos(since...)分页获取仓库search_repositories(...)搜索仓库MainClass.pyget_emojis()、get_gitignore_templates()、render_markdown(text)等辅助功能完整方法清单与对应 GitHub API 的映射关系见 doc/reference.rst。八、许可协议PyGithub 以 GNU Lesser General Public LicenseLGPL发布许可文本见仓库根目录的 COPYING 与 COPYING.LESSER。九、下一步参考文档、贡献与生态完成本文的入门后可以从以下几个方向继续深入API 参考想查找“某个 GitHub API 能力对应哪个类”查阅 doc/reference.rst。更多示例仓库 doc/examples 目录下按主题组织了大量可直接运行的示例包括Repository.rst、Issue.rst、PullRequest.rst、Branch.rst、Commit.rst、Milestone.rst、Webhook.rst等。参与贡献PyGithub 是社区驱动的项目新类、新方法和修复由社区编写经维护者审查后发布。贡献流程详见 doc/development.rst 与 CONTRIBUTING.md。十、生态谁在使用 PyGithubPyGithub 已被大量真实项目采用官方文档列举了其中一部分可作为你评估其成熟度的参考Github-iCalendar将 GitHub 的 Issues 与 Pull Request 转换为 iCalendar 格式的 VTODO 任务列表。DevAssistant、Upverter在各自产品中集成 GitHub 资源管理。Notifico接收来自服务和脚本的消息并投递到 IRC 频道可导入/同步 GitHub。Tratihubis将 Trac 工单转换为 GitHub Issues。git-gifi为 git 增加 GitHub 增强能力。gitsuggest基于你关注的仓库推荐其他 GitHub 仓库。Gitana基于 SQL 的项目活动分析工具。satsuki自动化 GitHub Release 发布与二进制资产上传。check-in以机器人身份使用 GitHub Checks API 的 Python CLI 工具。gittodoistclone把 GitHub Issues 转换为 Todoist 任务。这些案例覆盖了工单同步、CI 机器人、发布自动化、数据分析等多个典型场景说明 PyGithub 作为 GitHub API v3 的 Python 封装层具备良好的生产可用性与社区基础。无论你的场景是仓库巡检、Issue 自动化、还是构建 GitHub App都可以基于本文的入门路径快速落地。赞分享开发工具【免费下载链接】PyGithubTyped interactions with the GitHub API v3项目地址https://gitcode.com/gh_mirrors/py/PyGithub点击查看免费下载相关推荐Spotipy开发指南从零开始使用Python操作Spotify APISpotipy开发指南从零开始使用Python操作Spotify API 前言 Spotipy是一个强大的Python库它简化了与Spotify Web A后端用 Claude Code 补齐单元测试一个终端里就能跑通的实践用 Claude Code 补齐单元测试一个终端里就能跑通的实践 给项目补测试时最费时间的不是写断言而是想清楚这个函数要测哪些情况边界输入、错误分支AI 应用AI 技能/插件开发工具MeterSphere API接口调用终极指南从零开始快速上手MeterSphere API接口调用终极指南从零开始快速上手 你是否在集成MeterSphere测试平台时苦于找不到完整的接口文档想要自动化调用测试接口质量保障接口测试测试后端前端AI 应用DevOps上一篇httpx无头浏览器截图指南headless截图与JavaScript执行轻松掌握下一篇AutoFitTextView自定义扩展如何基于核心算法开发自己的文本适配控件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考