github3.py

github3.py is a Python library that wraps GitHub’s REST API v3, giving developers typed, object-oriented access to repositories, issues, pull requests, organizations, gists, and more without hand-rolling HTTP requests and JSON parsing. It has been actively maintained since 2012 and supports Python 3.7+ (an older 1.3.0 release remains for legacy Python 2 users).

The library wraps authentication (basic auth, tokens, GitHub Apps, 2FA prompts), pagination, rate-limit handling, and response caching behind a single GitHub client object, and mirrors GitHub Enterprise deployments through a dedicated GitHubEnterprise class. Every API resource is represented as a Python object backed by a GitHubCore base class, so consumers work with Repository, Issue, and PullRequest instances instead of raw dictionaries.

What You Get

• A GitHub client object plus login()/enterprise_login() helpers for basic-auth, token, and GitHub Apps authentication
• Typed model classes (Repository, Issue, PullRequest, Organization, Gist, and more) built on a shared GitHubCore base
• Built-in handling for GitHub’s pagination, rate limits, and 2FA-required responses
• A GitHubEnterprise client for talking to self-hosted GitHub Enterprise instances against the same API surface
• A decorator-based permission system (requires_auth, requires_basic_auth, requires_app_credentials) that raises clear errors when an authenticated action is attempted without the right credentials

Common Use Cases

• Building internal tooling or bots that create issues, comment on pull requests, or manage labels programmatically
• Writing scripts that audit or bulk-update repository settings, branch protections, or webhooks across an organization
• Automating release workflows: creating releases, uploading assets, and querying commit/tag history
• Building GitHub Apps or CI integrations that need typed, well-tested access to the REST API instead of raw requests calls

Under The Hood

Architecture github3.py is organized as a resource-per-module library: github.py defines the top-level GitHub and GitHubEnterprise clients, which compose behavior from apps.py, auths.py, events.py, issues.py, orgs.py, pulls.py, repos/, gists/, and search/. Every resource object inherits from the GitHubCore base class in models.py, which handles JSON-to-attribute proxying via __getattr__, equality/hashing based on a resource’s canonical URL, ETag/Last-Modified tracking for caching, and conversion helpers (as_dict, as_json, from_dict, from_json). A session.py module wraps requests.Session with GitHub-specific auth classes (BasicAuth, TokenAuth) and 2FA detection, so the transport layer stays separate from the resource models above it. Changing the core GitHubCore proxying behavior would ripple through effectively every resource class in the library, since they all rely on it for lazy attribute access.

Tech Stack The library targets Python 3.7+ and depends on requests for HTTP transport, uritemplate for building GitHub’s templated API URLs, python-dateutil for parsing GitHub’s ISO 8601 timestamps, and PyJWT[crypto] for signing GitHub Apps JWTs. It uses a modern pyproject.toml/hatchling build backend with version derived from src/github3/__about__.py, and ships py.typed to mark itself as type-hint aware for consumers, though internal type annotation coverage is partial. Documentation is built with Sphinx and published to Read the Docs via .readthedocs.yml.

Code Quality The project has an extensive test suite split into unit/ and integration/ directories, using pytest together with betamax and betamax_matchers to record and replay real GitHub API interactions as cassettes, giving realistic coverage without hitting the live API on every run. Error handling is explicit: a dedicated exceptions.py module defines a hierarchy of GitHubException subclasses, and decorators like requires_auth proactively raise typed errors rather than letting failures surface as opaque HTTP errors. Code style is enforced via black, isort, and a .pre-commit-config.yaml, and CI runs across GitHub Actions workflows including build/test, CodeQL analysis, dependency review, and OpenSSF Scorecards checks.

What Makes It Unique Rather than a thin HTTP wrapper, github3.py models nearly the entire GitHub REST API surface as first-class Python objects with lazy attribute resolution, letting consumers treat API resources as native objects (repo.issues(), issue.comments()) instead of chaining raw HTTP calls and manual JSON parsing. Its long history (since 2012) and continued maintenance through the transition to Python 3-only give it unusually broad and battle-tested coverage of GitHub’s API, including GitHub Apps and Enterprise-specific behavior that many newer, thinner GitHub API clients don’t attempt.