PyGithub

PyGithub is a Python client for the GitHub REST API v3, giving applications programmatic access to repositories, issues, pull requests, organizations, and the dozens of other resources GitHub exposes. Rather than returning raw JSON, every API response is mapped onto a typed Python object — a Repository, an Issue, a NamedUser — with attributes that lazily complete themselves against the API only when accessed, so a partially-populated object returned from a list endpoint can still be read as a fully-formed one.

The library covers authentication (personal access tokens, GitHub App JWTs and installation tokens, OAuth user-to-server tokens), pagination over both REST Link headers and GraphQL cursors, rate-limit tracking, and conditional requests via ETags. It has been developed against the real GitHub API surface since 2012, and its ~150 resource classes track the platform’s growth — from basic repository and issue management to code scanning alerts, dependency-review results, Copilot seat management, and GitHub Actions workflows.

It is the de facto standard for scripting and automating GitHub from Python: CI tooling, bots, migration scripts, and internal developer platforms use it to avoid hand-rolling REST calls and pagination logic against GitHub’s API directly.

What You Get

• Typed wrapper objects for ~150 GitHub API resources (Repository, Issue, PullRequest, Organization, Workflow, and more), each with full attribute access
• Lazy loading: objects populate on first attribute access, or eagerly on creation, controlled globally or per-call via Github(lazy=True) / withLazy()
• Five authentication strategies out of the box: personal access tokens, username/password (deprecated), GitHub App JWT signing with auto-refreshing installation tokens, and OAuth user-to-server
• Unified pagination via PaginatedList — follows REST Link headers or GraphQL cursor pagination transparently, with lazy per-page fetching and a cheap totalCount probe
• Built-in rate-limit tracking and conditional GET support (ETag / If-Modified-Since) to minimize wasted API calls
• A structured exception hierarchy (GithubException and subclasses like BadCredentialsException, UnknownObjectException, RateLimitExceededException) instead of bare HTTP errors

Common Use Cases

• Writing CI/CD or release-automation scripts that create issues, merge pull requests, or manage releases without shelling out to gh or hand-writing HTTP calls
• Building GitHub Apps or bots that authenticate as an installation and act on repositories on an organization’s behalf
• Bulk repository administration — auditing branch protection rules, managing teams and permissions, or migrating settings across many repos at once
• Pulling analytics or reporting data (commit activity, code scanning alerts, dependency review results) into internal dashboards or data pipelines
• Scripting one-off repository or organization migrations that need to walk paginated collections of issues, PRs, or members reliably

Under The Hood

Architecture Everything is rooted at github/MainClass.py’s Github class, which owns a Requester (github/Requester.py) and exposes get_* methods returning either a single PyGithub object or a PaginatedList (github/PaginatedList.py). Every resource class inherits from one of two bases defined in github/GithubObject.py: CompletableGithubObject, for resources with their own endpoint that can lazily complete themselves via a GET on first attribute access, and NonCompletableGithubObject, for embedded objects (like CommitStats or Reaction) that only ever appear nested inside another resource’s JSON and have no endpoint of their own. Attributes are declared via a strict two-method contract per class — _initAttributes() sets every field to a NotSet sentinel, and _useAttributes() parses whatever keys are present in a given API response — with typed helper constructors (_makeStringAttribute, _makeClassAttribute, _makeUnionClassAttributeFromTypeKey, etc.) doing the JSON-to-Python conversion, including polymorphic fields that resolve to different classes based on a discriminator key. This gives partially-populated, lazily-completing objects a uniform shape across all ~150 resource files without each one reinventing parsing logic.

Tech Stack The library is pure Python (3.10–3.15 supported, per tox.ini’s py{310-315} matrix) with a deliberately small runtime dependency set declared in pyproject.toml: requests for HTTP, pyjwt[crypto] and pynacl for GitHub App JWT signing and secret encryption, typing-extensions for backporting newer typing features, and urllib3. github/Requester.py layers pooled requests sessions and custom retry behavior (github/GithubRetry.py) on top of raw HTTP. The build uses setuptools with setuptools_scm for version derivation from git tags, and documentation is built with Sphinx (doc/, requirements/docs.txt) and published to Read the Docs.

Code Quality Testing is extensive: tests/ mirrors github/ with one test file per resource class (147 files), built on unittest plus the responses library for HTTP mocking, with a shared tests/Framework.py base class and a frame-buffer debug recorder in Requester for inspecting request/response pairs during test failures. CI (.github/workflows/ci.yml, codeql.yml, lint.yml) runs the matrix across all supported Python versions plus a dedicated mypy pass — pyproject.toml sets disallow_untyped_defs = true for the github.* module tree, and every public method carries full PEP 484 type hints plus a documented :calls: tag naming the exact REST endpoint it hits. Style is enforced via ruff, docformatter, codespell, and pre-commit, wired together through tox.ini’s lint environment. A 674-line ARCHITECTURE.md codifies file layout, naming, and class-ordering conventions precisely enough to onboard new contributors (or AI coding agents) without reverse-engineering the codebase.

What Makes It Unique Most thin API wrappers return dictionaries or loosely-typed models; PyGithub instead gives every one of GitHub’s ~150 resource types a real Python class with typed attributes, explicit lazy-completion semantics, and a documented distinction between an omitted parameter (NotSet, excluded from the request entirely) and an explicit None (serialized and sent to clear a field) — a distinction that matters for GitHub’s PATCH-style partial updates. Combined with transparent unification of REST Link-header and GraphQL cursor pagination behind one PaginatedList interface, it removes an entire class of manual JSON-walking and pagination bugs that hand-rolled requests calls against the GitHub API commonly hit.