Using the Repository APIs

Now that we have learned how to set up a client for use with our APIs, let’s begin to review how github3.py implements the Repositories API.

Retrieving Repositories

Once you’ve logged in you will have an instance of GitHub or GitHubEnterprise. Let’s assume either one is bound to a variable called github. To retrieve a single repository that we know the owner and name of, we would do the following:

repository = github.repository(owner, repository_name)

For example, let’s retrieve the repository of the uritemplate package that github3.py relies on:

uritemplate = github.repository('python-hyper', 'uritemplate')

It’s also possible for us to retrieve multiple repositories owned by the same user or organization:

for short_repository in github.repositories_by('python-hyper'):
    ...

When listing repositories, like listing other objects, the GitHub API doesn’t return the full representation of the object. In this case, github3.py returns a different object to represent a short repository. This object has fewer attributes, but can be converted into a full repository like so:

for short_repository in github.repositories_by('python-hyper'):
    full_repository = short_repository.refresh()

We now have two separate objects for the repository based on how GitHub represents them. Both objects have the same methods attached to them. There’s just a different set of attributes on each.

Interacting with Repositories

Repositories are central to many things in GitHub as well as in the API and as result they have many attributes and methods. It’s possible to list branches, collaborators, commits, contributors, deployments, forks, issues, projects, pull requests, refs, and more.

For example, we could build a tiny function that checks if a contributor has deleted their fork:

uritemplate = github.repository('python-hyper', 'uritemplate')
contributors_without_forks = (set(uritemplate.contributors()) -
                              set(fork.owner for fork in uritemplate.forks()))
print(f'The following contributors deleted their forks of {uritemplate!r}')
for contributor in sorted(contributors_without_forks, key=lambda c: c.login):
    print(f'  * {contributor.login}')

The output should look like

The following contributors deleted their forks of <Repository [python-hyper/uritemplate]>
  * eugene-eeo
  * jpotts18
  * sigmavirus24
  * thierryba