github3.py: GitHub API Wrapper

Warnings

• breaking In version 4.0.0, the `Comparison.commits` method was renamed to `original_commits`. The `commits` method now uses GitHub's API to get the full commit list out of the compare endpoint, enabling pagination/iterator functionality. This change affects how commit lists are retrieved from `Comparison` objects.
  Fix: Update calls to `Comparison.commits` to `Comparison.original_commits` for the old behavior (max 250 commits), or adapt to the new paginated `Comparison.commits` method for full commit lists.
• breaking Starting with version 1.0.0, methods that iterate over collections (e.g., users, organizations, issues, pull requests, teams) now return distinct 'short' classes (e.g., `ShortUser`, `ShortOrganization`, `ShortIssue`, `ShortPullRequest`, `ShortTeam`) instead of the full object. This means if you expect full attributes immediately, you might need to explicitly fetch the full object or call `refresh()` on the 'short' object.
  Fix: Review code interacting with collection iterations. If full object details are required, either fetch the full object using its ID (e.g., `gh.user(short_user.login)`) or call the `.refresh()` method on the 'short' object to populate all attributes.
• gotcha When using username/password authentication with GitHub's Two-Factor Authentication (2FA) enabled, `github3.py` will prompt for a 2FA code on *every* API call, which is highly inefficient and disruptive.
  Fix: Always use a Personal Access Token (PAT) for authentication when 2FA is enabled. PATs can be generated from your GitHub settings and provide a more secure and seamless experience. Store tokens securely, e.g., in environment variables.
• gotcha For older versions of `github3.py` (e.g., 0.9.x), retrieving the authenticated user's information was done via `gh.user()`. In newer versions (1.0.0+), the correct method is `gh.me()`. Mixing documentation versions can lead to `AttributeError`s.
  Fix: Ensure you are referencing documentation for your installed version. For current versions (1.0.0+), use `gh.me()` to get the authenticated user object.
• gotcha When listing repositories via the API, GitHub often refuses to return certain attributes (e.g., `source` and `parent`) to save bandwidth. These attributes will be `None` or missing.
  Fix: If you require these omitted attributes for a specific repository object, call the `.refresh()` method on that `Repository` object. This will make an additional API call to retrieve the full details. Example: `repo.refresh()`.
• gotcha Versions of `github3.py` prior to 1.3.0 supported older Python versions (e.g., Python 2.x, 3.5, 3.6). Current versions (4.x) require Python 3.7 or newer. Attempting to install or run newer versions on unsupported Python interpreters will result in errors.
  Fix: Ensure your Python environment meets the `requires_python` specification for the desired `github3.py` version. For `github3.py==4.x`, use Python 3.7+. If you must use an older Python version, consider pinning `github3.py==1.3.0`.

Install

• pip install github3.py Install latest version

Imports

• login

  from github3 import login

  The primary function to authenticate and get a GitHub object.
• github3

  import github3

  General module import for accessing other utilities or API functions directly.

Quickstart

This quickstart demonstrates how to authenticate with github3.py using a Personal Access Token (PAT), which is the recommended approach to avoid rate limits and issues with Two-Factor Authentication. It then fetches and prints the authenticated user's repositories.

import os
from github3 import login

# It's highly recommended to use a Personal Access Token (PAT) for authentication,
# especially when 2FA is enabled, to avoid repeated prompts.
# Store your token in an environment variable, e.g., GITHUB_TOKEN.
TOKEN = os.environ.get('GITHUB_TOKEN', 'YOUR_GITHUB_TOKEN') # Replace with actual token or ensure env var is set

if TOKEN and TOKEN != 'YOUR_GITHUB_TOKEN':
    gh = login(token=TOKEN)
    if gh:
        print(f"Successfully authenticated as: {gh.me().login}")
        # Example: Get your repositories
        print("Your repositories:")
        for repo in gh.iter_repos(type='owner'):
            print(f"- {repo.name}")
    else:
        print("Authentication failed. Check your GITHUB_TOKEN.")
else:
    print("GITHUB_TOKEN environment variable not set or is placeholder. Please set it for proper authentication.")
    print("You can generate a PAT at: https://github.com/settings/tokens")