GitHub¶

Required Extra

To use the GitHub connector, you will need to install parsons with the github extra. To do this, you will need to install it with pip install parsons[github] or pip install parsons[all]. For more information, see our Installation notes.

Overview¶

GitHub is an online tool for software collaboration.

This GitHub class uses the PyGitHub library to make requests to the GitHub REST API. The class provides methods to:

Get an individual user, organization, repo, issue, or pull request
Get lists of user or organization repos for a given username or organization_name
Get lists of repo issues, pull requests, and contributors for a given repo_name
Download files and tables

API Credentials

If you have a GitHub account you can use your normal username and password to authenticate with the API.
You can also use a personal access token.

Quickstart¶

To instantiate the GitHub class using a username and password, you can store your username and password as environmental variables (GITHUB_USERNAME and GITHUB_PASSWORD), or pass them in as arguments. Alternatively, you can provide a personal access token as an environmental variable (GITHUB_ACCESS_TOKEN) or as an argument.

Authenticate by passing a username and password arguments¶

from parsons import GitHub
github = GitHub(username='my_username', password='my_password')

Authenticate by passing an access token as an argument¶

from parsons import GitHub
github = GitHub(access_token='my_access_token')

Authenticate with environmental variables¶

from parsons import GitHub
github = GitHub()

With the class instantiated, you can now call various endpoints.

Get repo by its full name (account/name)¶

parsons_repo = github.get_repo("move-coop/parsons")

Get the first page of a repo’s issues as a Table¶

parsons_issues_table = github.list_repo_issues("move-coop/parsons")

Download Parsons README.md to local “/tmp/README.md”¶

parsons_readme_path = github.download_file("move-coop/parsons", "README.md", local_path="/tmp/README.md")

API¶

class parsons.github.github.GitHub(username=None, password=None, access_token=None)[source]¶

Creates a GitHub class for accessing the GitHub API.

Uses parsons.utilities.check_env to load credentials from environment variables if not supplied. Supports either a username and password or an access token for authentication. The client also supports unauthenticated access.

Parameters:

username – Optional[str] Username of account to use for credentials. Can be set with GITHUB_USERNAME environment variable.
password – Optional[str] Password of account to use for credentials. Can be set with GITHUB_PASSWORD environment variable.
access_token – Optional[str] Access token to use for credentials. Can be set with GITHUB_ACCESS_TOKEN environment variable.

get_user(username)[source]¶

Loads a GitHub user by username

Parameters:

username – str Username of user to load

Returns:

dict: User information

get_organization(organization_name)[source]¶

Loads a GitHub organization by name

Parameters:

organization_name – str Name of organization to load

Returns:

dict: Organization information

get_repo(repo_name)[source]¶

Loads a GitHub repo by name

Parameters:

repo_name – str Full repo name (account/name)

Returns:

dict: Repo information

list_user_repos(username, page=None, page_size=100)[source]¶

List user repos with pagination, returning a Table

Parameters:

username – str GitHub username
page – Optional[int] Page number. All results are returned if not set.
page_size – int Page size. Defaults to 100.

Returns:

Table: Table with page of user repos

list_organization_repos(organization_name, page=None, page_size=100)[source]¶

List organization repos with pagination, returning a Table

Parameters:

organization_name – str GitHub organization name
page – Optional[int] Page number. All results are returned if not set.
page_size – int Page size. Defaults to 100.

Returns:

Table: Table with page of organization repos

get_issue(repo_name, issue_number)[source]¶

Loads a GitHub issue

Parameters:

repo_name – str Full repo name (account/name)
issue_number – int Number of issue to load

Returns:

dict: Issue information

list_repo_issues(repo_name, state: Literal['open', 'closed', 'all'] = 'open', assignee=None, creator=None, mentioned=None, labels=None, sort: Literal['created', 'updated', 'comments'] = 'created', direction: Literal['asc', 'desc'] = 'desc', since=None, page=None, page_size=100)[source]¶

List issues for a given repo

Parameters:

repo_name – str Full repo name (account/name)
state (Literal['open', 'closed', 'all']) – str State of issues to return. One of “open”, “closed”, “all”. Defaults to “open”.
assignee – Optional[str] Name of assigned user, “none”, or “*”.
creator – Optional[str] Name of user that created the issue.
mentioned – Optional[str] Name of user mentioned in the issue.
labels – list[str] List of label names. Defaults to []
sort (Literal['created', 'updated', 'comments']) – str What to sort results by. One of “created”, “updated”, “comments”. Defaults to “created”.
direction (Literal['asc', 'desc']) – str Direction to sort. One of “asc”, “desc”. Defaults to “desc”.
since – Optional[Union[datetime.datetime, datetime.date]] Timestamp to pull issues since. Defaults to None.
page – Optional[int] Page number. All results are returned if not set.
page_size – int Page size. Defaults to 100.

Returns:

Table: Table with page of repo issues

get_pull_request(repo_name, pull_request_number)[source]¶

Loads a GitHub pull request

Parameters:

repo_name – str Full repo name (account/name)
pull_request_number – int Pull request number

Returns:

dict: Pull request information

list_repo_pull_requests(repo_name, state: Literal['open', 'closed', 'all'] = 'open', base=None, sort: Literal['created', 'updated', 'popularity'] = 'created', direction: Literal['asc', 'desc'] = 'desc', page=None, page_size=100)[source]¶

Lists pull requests for a given repo

Parameters:

repo_name – str Full repo name (account/name)
state (Literal['open', 'closed', 'all']) – str One of “open, “closed”, “all”. Defaults to “open”.
base – Optional[str] Base branch to filter pull requests by.
sort (Literal['created', 'updated', 'popularity']) – str How to sort pull requests. One of “created”, “updated”, “popularity”. Defaults to “created”.
direction (Literal['asc', 'desc']) – str Direction to sort by. Defaults to “desc”.
page – Optional[int] Page number. All results are returned if not set.
page_size – int Page size. Defaults to 100.

Returns:

Table: Table with page of repo pull requests

list_repo_contributors(repo_name, page=None, page_size=100)[source]¶

Lists contributors for a given repo

Parameters:

repo_name – str Full repo name (account/name)
page – Optional[int] Page number. All results are returned if not set.
page_size – int Page size. Defaults to 100.

Returns:

Table: Table with page of repo contributors

download_file(repo_name, path, branch=None, local_path=None)[source]¶

Download a file from a repo by path and branch. Defaults to the repo’s default branch if branch is not supplied.

Uses the download_url directly rather than the API because the API only supports contents up to 1MB from a repo directly, and the process for downloading larger files through the API is much more involved.

Because download_url does not go through the API, it does not support username / password authentication, and requires a token to authenticate.

Parameters:

repo_name – str Full repo name (account/name)
path – str Path from the repo base directory
branch – Optional[str] Branch to download file from. Defaults to repo default branch
local_path – Optional[str] Local file path to download file to. Will create a temp file if not supplied.

Returns:

str: File path of downloaded file

download_table(repo_name, path, branch=None, local_path=None, delimiter=',')[source]¶

Download a CSV file from a repo by path and branch as a Parsons Table.

Parameters:

repo_name – str Full repo name (account/name)
path – str Path from the repo base directory
branch – Optional[str] Branch to download file from. Defaults to repo default branch
local_path – Optional[str] Local file path to download file to. Will create a temp file if not supplied.
delimiter – Optional[str] The CSV delimiter to use to parse the data. Defaults to ‘,’

Returns:

Table: See Table for output options.

exception parsons.github.github.ParsonsGitHubError[source]¶

add_note(note, /)¶: Add a note to the exception

with_traceback(tb, /)¶: Set self.__traceback__ to tb and return self.