Welcome to aiogithub’s documentation!¶

Contents:

Installation¶

Prerequisites¶

aiogithub requires Python 3.7 or newer.

Installation of development versions¶

Currently, only development versions are available. You can install the current development version by running:

pip install git+https://github.com/reupen/aiogithub.git#egg=aiogithub

Usage¶

Development status¶

This library is a work in progress. So far, select read operations have been implemented.

A note about asyncio¶

aiogithub is written on top of asyncio and aiohttp. You should have a basic grasp of asynchronous programming using asyncio in Python 3 before using this library.

In particular, using of the library generally occurs in an async def function. Calls to coroutine functions would normally be preceded with await, and async for would normally be used with asynchronous iterables.

A simple example¶

import asyncio

from aiogithub import GitHub

async def main():
    async with GitHub() as api:
        user = await api.get_user('reupen')
        print(user.login)
        # user is also a dict, so you can see the underlying data via print(user)

        # Get this user's repos. There's no need to worry about
        # pagination – you can simply iterate over list objects like
        # this and pages will be retrieved as needed:
        async for repo in user.get_repos():
            pass # Do something with each repo here

        # Or you can fetch the entire list like this:
        repos = await user.get_repos().all()
        # Do something with repos

asyncio.get_event_loop().run_until_complete(main())

The GitHub class¶

The GitHub class is the main entry point into aiogithub functionality. It is a wrapper around an aiohttp ClientSession object, which means that you automatically benefit from connection pooling. You should use the object as a context manager to make sure the session is closed as soon as you are done with it.

Authentication¶

You can make a limited number of requests to the GitHub API unauthenticated, but for most purposes you will want to be authenticated. To authenticate with GitHub using aiogithub, you should use a personal access token. You can generate a personal access token in your GitHub settings.

aiogithub will use the value of the the GITHUB_TOKEN environment variable to authenticate with GitHub if it is set. You can also pass a token to GitHub (which will override any value in the GITHUB_TOKEN environment variable)::

with GitHub(token='a_personal_access_token') as api:
    pass

Client¶

class aiogithub.GitHub(token: str = None, items_per_page=100, timeout_secs=10, max_paginated_items=1000, enable_preview_api=False)¶

Initialises a GitHub API client.

If no personal access token is provided, the client will check the GITHUB_TOKEN environment variable for a token and use that if present. If still without a token, the GitHub API will be used unauthenticated.

Parameters:	token – GitHub personal access token items_per_page – Items to request per page, must be between 1 and 100 timeout_secs – Timeout in seconds for HTTP requests max_paginated_items – Safety limit for when iterating through list results to avoid inadvertently making a huge number of requests

coroutine close() → None¶

coroutine get_branch(owner_name, repo_name, branch_name) → aiogithub.objects.branch.Branch¶: Gets a single branch of a repository.

coroutine get_current_user() → aiogithub.objects.user.AuthenticatedUser¶: Gets the current authenticated user.

coroutine get_issue(owner_name, repo_name, issue_number) → aiogithub.objects.issue.Issue¶: Gets a single issue of a repository.

coroutine get_organization(username, defer_fetch=False) → aiogithub.objects.organization.Organization¶

Gets a single organization.

Parameters:	username – The username/login of the organization to fetch the details of. defer_fetch – Whether to defer fetching of data about this organization.
Returns:	An object representing the organization.

coroutine get_pull_request(owner_name, repo_name, issue_number) → aiogithub.objects.pull_request.PullRequest¶: Gets a single pull request of a repository.

coroutine get_rate_limit() → aiogithub.objects.rate_limit.RateLimit¶: Gets the current rate limit values.

coroutine get_repo(owner_name, repo_name, defer_fetch=False) → aiogithub.objects.repo.Repo¶

Gets a single repository.

Parameters:	owner_name – The name of the user or organisation that owns the repository. repo_name – The name of the repository. defer_fetch – Whether to defer fetching of data about this repository.
Returns:	An object representing the repository.

get_repos(since=None) → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶: Gets all repos.

coroutine get_user(username, defer_fetch=False) → aiogithub.objects.user.User¶

Gets a single user.

Parameters:	username – The name of the user to fetch the details of. defer_fetch – Whether to defer fetching of data about this user.
Returns:	An object representing the user.

get_users(since=None) → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶: Gets all users.

last_rate_limit¶

The rate limits that were sent by GitHub in the most recent request.

Type:	Optional[dict]

Response classes¶

class aiogithub.objects.BaseObject(document)¶

Bases: dict

Base class for all data objects

class aiogithub.objects.BaseResponseObject(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseObject

Base class for objects where the contained data corresponds to a response payload of a particular GitHub API URL

coroutine fetch_data()¶

limits¶

class aiogithub.objects.PaginatedListProxy(client, url, element_type, fetch_params)¶

Bases: collections.abc.AsyncIterable, typing.Generic

Public interface to paginated objects

coroutine all()¶

Returns all items in the collection. This will fetch all result pages that haven’t already been fetched.

Use limit() when listing large data sets (e.g. all public users) to avoid making a large number of HTTP requests and exhausting your API limits.

limit(max_items)¶

Limits the number of items returned by all() or when iterating through the collection elements (using async for).

Use when listing large data sets (e.g. all public users) to avoid making a large number of HTTP requests and exhausting your API limits.

User classes¶

class aiogithub.objects.PartialUser(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

get_events() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.event.Event][aiogithub.objects.event.Event]¶

get_followers() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_following() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_received_events() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.event.Event][aiogithub.objects.event.Event]¶

get_repos() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

get_starred() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

get_subscriptions() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

gravatar_id¶

Type:	Optional[str]

html_url¶

Type:	Optional[str]

id¶

Type:	Optional[int]

login¶

Type:	str

site_admin¶

Type:	Optional[str]

type¶

Type:	Optional[str]

class aiogithub.objects.User(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.user.PartialUser

bio¶

Type:	Optional[str]

blog¶

Type:	Optional[str]

company¶

Type:	Optional[str]

created_at¶

Type:	Optional[datetime]

email¶

Type:	Optional[str]

followers¶

Type:	Optional[int]

following¶

Type:	Optional[int]

hireable¶

Type:	Optional[bool]

location¶

Type:	Optional[str]

public_gists¶

Type:	Optional[int]

public_repos¶

Type:	Optional[int]

updated_at¶

Type:	Optional[datetime]

class aiogithub.objects.AuthenticatedUser(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.user.User

collaborators¶

Type:	int

disk_usage¶

Type:	int

owned_private_repos¶

Type:	int

plan¶

Type:	dict

private_gists¶

Type:	int

total_private_repos¶

Type:	int

Organization classes¶

class aiogithub.objects.PartialOrganization(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

avatar_url¶

description¶

get_events() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.event.Event][aiogithub.objects.event.Event]¶

get_followers() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_following() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_gists() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.gist.Gist][aiogithub.objects.gist.Gist]¶

get_hooks() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.response.BaseObject][aiogithub.objects.response.BaseObject]¶

get_issues() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.issue.Issue][aiogithub.objects.issue.Issue]¶

get_members() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.PartialUser][aiogithub.objects.user.PartialUser]¶

get_public_members() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.PartialUser][aiogithub.objects.user.PartialUser]¶

get_repos() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

id¶

login¶

class aiogithub.objects.Organization(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.organization.PartialOrganization

blog¶

company¶

created_at¶

email¶

followers¶

following¶

html_url¶

location¶

name¶

public_gists¶

public_repos¶

type¶

updated_at¶

Repo classes¶

class aiogithub.objects.PartialRepo(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

clone_url¶

description¶

fork¶

full_name¶

get_assignees() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_blobs() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.response.BaseResponseObject][aiogithub.objects.response.BaseResponseObject]¶

coroutine get_branch(branch) → aiogithub.objects.branch.Branch¶

get_branches() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.branch.Branch][aiogithub.objects.branch.Branch]¶

get_collaborators() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

get_comments() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.comment.Comment][aiogithub.objects.comment.Comment]¶

get_commits() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.commit.Commit][aiogithub.objects.commit.Commit]¶

get_contributors() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

get_events() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.event.Event][aiogithub.objects.event.Event]¶

get_forks() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.repo.Repo][aiogithub.objects.repo.Repo]¶

get_issues() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.issue.Issue][aiogithub.objects.issue.Issue]¶

get_pull_requests() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.pull_request.PullRequest][aiogithub.objects.pull_request.PullRequest]¶

get_stargazers() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.User][aiogithub.objects.user.User]¶

git_url¶

homepage¶

html_url¶

id¶

mirror_url¶

name¶

owner¶

private¶

ssh_url¶

svn_url¶

class aiogithub.objects.Repo(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.repo.PartialRepo

created_at¶

default_branch¶

forks_count¶

has_downloads¶

has_issues¶

has_pages¶

has_wiki¶

language¶

open_issues_count¶

permissions¶

pushed_at¶

size¶

stargazers_count¶

updated_at¶

watchers_count¶

class aiogithub.objects.Branch(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

commit¶

links¶

name¶

class aiogithub.objects.Commit(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

author¶

commit¶

committer¶

files¶

get_comments() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.comment.Comment][aiogithub.objects.comment.Comment]¶

html_url¶

parents¶

sha¶

stats¶

Pull request classes¶

class aiogithub.objects.PullRequest(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

assignee¶

assignees¶

base¶

body¶

closed_at¶

created_at¶

diff_url¶

get_comments() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.comment.Comment][aiogithub.objects.comment.Comment]¶

get_commits() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.commit.Commit][aiogithub.objects.commit.Commit]¶

coroutine get_issue() → aiogithub.objects.issue.Issue¶

get_requested_reviewers() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.user.PartialUser][aiogithub.objects.user.PartialUser]¶

coroutine get_review_comment() → aiogithub.objects.review_comment.ReviewComment¶

get_review_comments() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.review_comment.ReviewComment][aiogithub.objects.review_comment.ReviewComment]¶

get_reviews() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.review.Review][aiogithub.objects.review.Review]¶

head¶

html_url¶

id¶

locked¶

merged_at¶

milestone¶

number¶

patch_url¶

requested_reviewers¶

state¶

title¶

updated_at¶

user¶

class aiogithub.objects.ReviewComment(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

body¶

commit_id¶

created_at¶

diff_hunk¶

coroutine get_pull_request() → aiogithub.objects.pull_request.PullRequest¶

html_url¶

id¶

original_commit_id¶

original_position¶

path¶

position¶

updated_at¶

user¶

Issue classes¶

class aiogithub.objects.Issue(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

assignee¶

assignees¶

body¶

closed_at¶

comments¶

created_at¶

get_comments() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.comment.Comment][aiogithub.objects.comment.Comment]¶

get_events() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.event.IssueEvent][aiogithub.objects.event.IssueEvent]¶

get_labels() → aiogithub.objects.response.PaginatedListProxy[aiogithub.objects.response.BaseResponseObject][aiogithub.objects.response.BaseResponseObject]¶

coroutine get_repo() → aiogithub.objects.repo.Repo¶

html_url¶

id¶

labels¶

locked¶

milestone¶

number¶

state¶

title¶

updated_at¶

user¶

class aiogithub.objects.IssueEvent(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

actor¶

commit_id¶

created_at¶

event¶

id¶

issue¶

class aiogithub.objects.Comment(client, document=None, limits=None, links=None, fetch_params=None)¶

Bases: aiogithub.objects.response.BaseResponseObject

body¶

created_at¶

html_url¶

id¶

updated_at¶

user¶

Indexes and tables¶

Module Index