|
| 1 | +=========================== |
| 2 | + Using the Repository APIs |
| 3 | +=========================== |
| 4 | + |
| 5 | +Now that we have:doc:`learned<getting-started>` how to set up a client for |
| 6 | +use with our APIs, let's begin to review how github3.py implements the |
| 7 | +`Repositories API`_. |
| 8 | + |
| 9 | + |
| 10 | +Retrieving Repositories |
| 11 | +======================= |
| 12 | + |
| 13 | +Once you've:ref:`logged in<logging-in>` you will have an instance of |
| 14 | +:class:`~github3.github.GitHub` or:class:`~github3.github.GitHubEnterprise`. |
| 15 | +Let's assume either one is bound to a variable called ``github``. To retrieve |
| 16 | +a single:class:`repository <github3.repos.repo.Repository>` that we know the |
| 17 | +owner and name of, we would do the following: |
| 18 | + |
| 19 | +..code-block::python |
| 20 | +
|
| 21 | + repository= github.repository(owner, repository_name) |
| 22 | +
|
| 23 | +For example, let's retrieve the repository of the ``uritemplate`` package that |
| 24 | +github3.py relies on: |
| 25 | + |
| 26 | +..code-block::python |
| 27 | +
|
| 28 | + uritemplate= github.repository('python-hyper','uritemplate') |
| 29 | +
|
| 30 | +It's also possible for us to retrieve multiple repositories owned by the same |
| 31 | +user or organization: |
| 32 | + |
| 33 | +..code-block::python |
| 34 | +
|
| 35 | +for short_repositoryin github.repositories_by('python-hyper'): |
| 36 | +... |
| 37 | +
|
| 38 | +When listing repositories, like listing other objects, the GitHub API doesn't |
| 39 | +return the full representation of the object. In this case, github3.py returns |
| 40 | +a different object to represent a:class:`short repository |
| 41 | +<github3.repos.repo.ShortRepository>`. This object has fewer attributes, but |
| 42 | +can be converted into a full repository like so: |
| 43 | + |
| 44 | +..code-block::python |
| 45 | +
|
| 46 | +for short_repositoryin github.repositories_by('python-hyper'): |
| 47 | + full_repository= short_repository.refresh() |
| 48 | +
|
| 49 | +We now have two separate objects for the repository based on how GitHub |
| 50 | +represents them. Both objects have the same methods attached to them. There's |
| 51 | +just a different set of attributes on each. |
| 52 | + |
| 53 | + |
| 54 | +Interacting with Repositories |
| 55 | +============================= |
| 56 | + |
| 57 | +Repositories are central to many things in GitHub as well as in the API and as |
| 58 | +result they have many attributes and methods. It's possible to list branches, |
| 59 | +collaborators, commits, contributors, deployments, forks, issues, projects, |
| 60 | +pull requests, refs, and more. |
| 61 | + |
| 62 | +For example, we could build a tiny function that checks if a contributor has |
| 63 | +deleted their fork: |
| 64 | + |
| 65 | +..code-block::python |
| 66 | +
|
| 67 | + uritemplate= github.repository('python-hyper','uritemplate') |
| 68 | + contributors_without_forks= (set(uritemplate.contributors())- |
| 69 | +set(fork.ownerfor forkin uritemplate.forks())) |
| 70 | +print(f'The following contributors deleted their forks of{uritemplate!r}') |
| 71 | +for contributorinsorted(contributors_without_forks,key=lambdac: c.login): |
| 72 | +print(f' *{contributor.login}') |
| 73 | +
|
| 74 | +The output should look like |
| 75 | + |
| 76 | +..code-block::text |
| 77 | +
|
| 78 | + The following contributors deleted their forks of <Repository [python-hyper/uritemplate]> |
| 79 | + * eugene-eeo |
| 80 | + * jpotts18 |
| 81 | + * sigmavirus24 |
| 82 | + * thierryba |
| 83 | +
|
| 84 | +
|
| 85 | +
|
| 86 | +.. links |
| 87 | +.. _Repositories API: |
| 88 | +https://github.com/sigmavirus24/github3.py/pull/836 |