PyGithub — Typed Python Client for the GitHub API

Introduction

PyGithub is a Python library that provides typed interactions with the GitHub REST API v3. It maps GitHub resources (repositories, issues, pull requests, users, organizations) to Python objects with attributes and methods, making it easy to automate GitHub workflows, build integrations, and manage repositories from Python scripts.

What PyGithub Does

• Maps GitHub API resources to Python objects with typed attributes and methods
• Supports authentication via personal access tokens, OAuth tokens, and GitHub App installation tokens
• Handles pagination transparently through lazy-loading paginated lists
• Provides read and write access to repos, issues, PRs, branches, releases, actions, and more
• Manages rate limiting with automatic wait or exception-based handling

Architecture Overview

PyGithub wraps the GitHub REST API v3 using the requests library for HTTP transport. Each GitHub resource (Repository, Issue, PullRequest, Organization) is represented as a Python class with properties that map to API response fields. Related resources are accessed via methods that return lazy-loaded objects or paginated lists. Authentication tokens are passed at the Github object level and attached to every request. The library caches ETags for conditional requests to reduce rate limit consumption.

Self-Hosting & Configuration

• Requires Python 3.8 or newer
• Install with pip install PyGithub
• Generate a personal access token at github.com/settings/tokens
• For GitHub Apps, use the GithubIntegration class with your app's private key
• Set base_url for GitHub Enterprise Server instances

Key Features

• Full coverage of GitHub REST API v3 endpoints
• Typed Python objects with IDE autocompletion and type hints
• Transparent pagination: iterate over all items without managing page tokens
• Support for GitHub Apps authentication and installation token generation
• Conditional requests using ETags to minimize API quota usage

Comparison with Similar Tools

• Octokit.js — JavaScript equivalent; PyGithub serves the same role for Python developers
• ghapi — FastAI's GitHub API wrapper with a more dynamic approach; PyGithub offers typed objects
• github3.py — Alternative Python GitHub library with a similar design; PyGithub has broader adoption
• gh CLI — GitHub's official command-line tool; PyGithub is for programmatic access in Python applications

FAQ

Q: How do I handle rate limits? A: PyGithub tracks remaining API calls. You can check g.get_rate_limit() or enable retry on the Github object to automatically wait when limits are hit.

Q: Does PyGithub support the GraphQL API? A: No, PyGithub only covers the REST API v3. For GraphQL, use libraries like gql or sgqlc.

Q: Can I use PyGithub with GitHub Enterprise? A: Yes. Pass base_url="https://your-ghe-instance/api/v3" when creating the Github object.

Q: What license does PyGithub use? A: LGPL-3.0 License.

Sources

• https://github.com/PyGithub/PyGithub
• https://pygithub.readthedocs.io