or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdgit-operations.mdindex.mdissues-pull-requests.mdrepository-management.mdsearch-discovery.mduser-organization-management.mdworkflows-actions.md
tile.json

tessl/pypi-pygithub

Comprehensive Python client library providing full access to the GitHub REST API v3 for programmatic management of repositories, users, organizations, issues, pull requests, and other GitHub entities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pygithub@2.8.x

To install, run

npx @tessl/cli install tessl/pypi-pygithub@2.8.0

index.mddocs/

PyGithub

A comprehensive Python client library providing full access to the GitHub REST API v3. PyGithub enables developers to programmatically manage GitHub resources including repositories, user profiles, organizations, issues, pull requests, and other GitHub entities within their Python applications.

Package Information

  • Package Name: PyGithub
  • Language: Python
  • Installation: pip install PyGithub
  • Documentation: https://pygithub.readthedocs.io/en/stable/
  • Repository: https://github.com/pygithub/pygithub

Core Imports

import github

Most common usage with main Github client:

from github import Github

Individual components can be imported directly:

from github import Auth, GithubIntegration, GithubException

Basic Usage

from github import Github, Auth

# Authentication using personal access token
auth = Auth.Token("your_access_token")

# Create Github instance
g = Github(auth=auth)

# Get a user
user = g.get_user("octocat")
print(f"User: {user.name} ({user.login})")
print(f"Public repos: {user.public_repos}")

# Get a repository
repo = g.get_repo("octocat/Hello-World")
print(f"Repository: {repo.full_name}")
print(f"Description: {repo.description}")
print(f"Language: {repo.language}")

# Create an issue
issue = repo.create_issue(
    title="Found a bug",
    body="I'm having trouble with...",
    labels=["bug"]
)
print(f"Created issue #{issue.number}")

# List repository issues
for issue in repo.get_issues(state='open'):
    print(f"Issue #{issue.number}: {issue.title}")

Architecture

PyGithub follows a hierarchical object-oriented design that mirrors the GitHub API structure:

  • Github: Main client providing entry points to GitHub API resources
  • Resource Objects: Individual GitHub entities (Repository, NamedUser, Organization, Issue, PullRequest, etc.)
  • Authentication: Pluggable authentication system supporting multiple GitHub auth methods
  • Pagination: Automatic handling of paginated API responses through PaginatedList
  • Error Handling: Comprehensive exception hierarchy for different API error conditions

All GitHub objects inherit from GithubObject, providing consistent behavior for lazy loading, attribute access, and API interaction patterns.

Capabilities

Authentication and Client Setup

Multiple authentication methods for accessing GitHub API including personal access tokens, GitHub Apps, OAuth, and legacy authentication. The Github client serves as the main entry point for all API operations.

class Github:
    def __init__(
        self,
        login_or_token: str = None,  # deprecated, use auth parameter
        password: str = None,  # deprecated, use auth parameter
        jwt: str = None,  # deprecated, use auth parameter
        app_auth: AppAuthentication = None,  # deprecated, use auth parameter
        base_url: str = "https://api.github.com",
        timeout: int = 15,
        user_agent: str = "PyGithub/Python",
        per_page: int = 30,
        verify: Union[bool, str] = True,
        retry: Union[int, GithubRetry] = None,
        pool_size: int = None,
        seconds_between_requests: float = None,
        seconds_between_writes: float = None,
        auth: Auth = None,
        lazy: bool = False
    ): ...

# Authentication classes
class Auth:
    class Token:
        def __init__(self, token: str): ...
    
    class Login:
        def __init__(self, username: str, password: str): ...
    
    class AppAuth:
        def __init__(self, app_id: str, private_key: str): ...

Authentication

Repository Management

Comprehensive repository operations including content management, branch operations, collaboration features, webhooks, and repository settings. Supports both repository-level operations and Git-level operations.

class Repository:
    def get_contents(self, path: str, ref: str = None): ...
    def create_file(self, path: str, message: str, content: str | bytes, branch: str = None, committer: InputGitAuthor = None, author: InputGitAuthor = None): ...
    def update_file(self, path: str, message: str, content: str, sha: str, branch: str = None): ...
    def get_branches(self): ...
    def get_branch(self, branch: str): ...
    def create_git_ref(self, ref: str, sha: str): ...
    def get_collaborators(self): ...
    def add_to_collaborators(self, collaborator: str, permission: str = None): ...

Repository Management

User and Organization Management

User profile access, organization management, membership operations, and social features. Handles both public user information and authenticated user capabilities.

class NamedUser:
    def get_repos(self, type: str = None, sort: str = None, direction: str = None): ...
    def get_gists(self): ...
    def get_followers(self): ...
    def get_following(self): ...
    def get_starred(self): ...

class AuthenticatedUser:
    def create_repo(self, name: str, description: str = None, private: bool = False): ...
    def create_gist(self, description: str, files: dict, public: bool = True): ...
    def get_notifications(self): ...

class Organization:
    def get_repos(self, type: str = None): ...
    def create_repo(self, name: str, description: str = None): ...
    def get_members(self, filter: str = None, role: str = None): ...
    def get_teams(self): ...
    def create_team(self, name: str, repo_names: list = None): ...

User and Organization Management

Issues and Pull Requests

Complete issue and pull request lifecycle management including creation, editing, commenting, labeling, milestone assignment, and review processes.

class Issue:
    def edit(self, title: str = None, body: str = None, assignee: str = None, state: str = None): ...
    def create_comment(self, body: str): ...
    def get_comments(self): ...
    def add_to_labels(self, *labels): ...
    def remove_from_labels(self, *labels): ...

class PullRequest:
    def merge(self, commit_message: str = None, commit_title: str = None, merge_method: str = None): ...
    def get_commits(self): ...
    def get_files(self): ...
    def create_review(self, body: str = None, event: str = None, comments: list = None): ...
    def get_reviews(self): ...

Issues and Pull Requests

Git Operations

Low-level Git operations including commit creation, tree manipulation, blob handling, references, and tags. Provides direct access to Git objects and operations.

class Repository:
    def create_git_commit(self, message: str, tree: str, parents: list): ...
    def create_git_tree(self, tree: list, base_tree: str = None): ...
    def create_git_blob(self, content: str, encoding: str): ...
    def get_git_ref(self, ref: str): ...
    def create_git_tag(self, tag: str, message: str, object: str, type: str): ...

# Git object classes
class GitCommit:
    @property
    def sha(self) -> str: ...
    @property
    def message(self) -> str: ...
    @property
    def author(self) -> GitAuthor: ...

class GitTree:
    @property
    def sha(self) -> str: ...
    @property
    def tree(self) -> list: ...

Git Operations

Search and Discovery

Search functionality across repositories, users, issues, code, commits, and topics. Provides comprehensive search capabilities with filtering and sorting options.

class Github:
    def search_repositories(self, query: str, sort: str = None, order: str = None): ...
    def search_users(self, query: str, sort: str = None, order: str = None): ...
    def search_issues(self, query: str, sort: str = None, order: str = None): ...
    def search_code(self, query: str, sort: str = None, order: str = None): ...
    def search_commits(self, query: str, sort: str = None, order: str = None): ...
    def search_topics(self, query: str): ...

Search and Discovery

Workflows and Actions

GitHub Actions workflow management, workflow runs, jobs, artifacts, and self-hosted runners. Supports automation and CI/CD pipeline integration.

class Workflow:
    def create_dispatch(self, ref: str, inputs: dict = None): ...
    def get_runs(self, actor: str = None, branch: str = None, event: str = None): ...
    
class WorkflowRun:
    def cancel(self): ...
    def rerun(self): ...
    def get_jobs(self): ...
    def get_artifacts(self): ...

class Repository:
    def get_workflows(self): ...
    def get_workflow_runs(self): ...

Workflows and Actions

Core Types

# Main client class
class Github:
    def close(self) -> None: ...
    def get_user(self, login: str = None) -> Union[AuthenticatedUser, NamedUser]: ...
    def get_repo(self, full_name_or_id: Union[str, int]) -> Repository: ...
    def get_organization(self, login: str) -> Organization: ...

# Pagination support
class PaginatedList:
    def totalCount(self) -> int: ...
    def __iter__(self): ...
    def __getitem__(self, index: Union[int, slice]): ...

# Input helper classes
class InputFileContent:
    def __init__(self, content: str, new_name: str | None = None): ...

class InputGitAuthor:
    def __init__(self, name: str, email: str, date: str = None): ...

class InputGitTreeElement:
    def __init__(self, path: str, mode: str, type: str, content: str = None, sha: str = None): ...

# Rate limiting
class RateLimit:
    @property
    def limit(self) -> int: ...
    @property
    def remaining(self) -> int: ...
    @property
    def reset(self) -> datetime: ...

# Exception classes
class GithubException(Exception):
    """Base exception class for all PyGithub errors"""
    @property
    def status(self) -> int: ...
    @property
    def data(self) -> Any: ...
    @property
    def headers(self) -> dict: ...
    @property 
    def message(self) -> str: ...

class BadCredentialsException(GithubException):
    """Authentication failures (401/403 errors)"""

class UnknownObjectException(GithubException):
    """Resource not found (404 errors)"""

class RateLimitExceededException(GithubException):
    """API rate limit exceeded"""

class BadUserAgentException(GithubException):
    """Invalid user agent string"""

class TwoFactorException(GithubException):
    """Two-factor authentication required"""

class BadAttributeException(Exception):
    """Type conversion errors when parsing API responses"""
    @property
    def actual_value(self) -> Any: ...
    @property
    def expected_type(self) -> Any: ...

class IncompletableObject(GithubException):
    """Missing URL data for lazy loading"""

Configuration

# Rate limiting information
def get_rate_limit(self) -> RateLimit: ...

# Retry configuration
class GithubRetry:
    def __init__(
        self,
        total: int = None,
        status_forcelist: list = None,
        backoff_factor: float = None
    ): ...

# Utility functions
def set_log_level(level: int) -> None: ...
def enable_console_debug_logging() -> None: ...