Release v0.7.0.
github3.py is wrapper for the GitHub API written in python. The design of github3.py is centered around having a logical organization of the methods needed to interact with the API. Let me demonstrate this with a code example.
Let’s get information about a user:
from github3 import login
gh = login('sigmavirus24', password='<password>')
sigmavirus24 = gh.user()
# <User [sigmavirus24:Ian Cordasco]>
print(sigmavirus24.name)
# Ian Cordasco
print(sigmavirus24.login)
# sigmavirus24
print(sigmavirus24.followers)
# 4
for f in gh.iter_followers():
print(str(f))
kennethreitz = gh.user('kennethreitz')
# <User [kennethreitz:Kenneth Reitz]>
print(kennethreitz.name)
print(kennethreitz.login)
print(kennethreitz.followers)
followers = [str(f) for f in gh.iter_followers('kennethreitz')]
For objects you’re not likely to see in practice. This is useful if you ever feel the need to contribute to the project.
$ pip install github3.py
# OR:
$ git clone git://github.com/sigmavirus24/github3.py.git github3.py
$ cd github3.py
$ python setup.py install
I’m maintaining two public copies of the project. The first can be found on GitHub and the second on BitBucket. I would prefer pull requests to take place on GitHub, but feel free to do them via BitBucket. Please make sure to add yourself to the list of contributors in AUTHORS.rst, especially if you’re going to be working on the list below.
In order of importance:
Documentation
I know I’m not the best at writing documentation so if you want to clarify or correct something, please do so.
Examples
Have a clever example that takes advantage of github3.py? Feel free to share it.
mkdir -p /path/to/virtualenv/github3.py
cd /path/to/virtualenv/github3.py
virtualenv .
cd /path/to/github3.py_repo/requirements.txt
pip install -r requirements.txt
# Or you could run make test-deps
make tests
Fix Issue.close, Issue.reopen, and Issue.assign. (Issue #106)
Add check_authorization to the GitHub class to cover the new part of the API.
Add create_file, update_file, delete_file, iter_contributor_statistics, iter_commit_activity, iter_code_frequency and weekly_commit_count to the Repository object.
Add update and delete methods to the Contents object.
Add is_following to the User object.
Add head, base parameters to Repository.iter_pulls.
The signature of Hook.edit has changed since that endpoint has changed as well. See: github/developer.github.com@b95f291a47954154a6a8cd7c2296cdda9b610164
github3.GitHub can now be used as a context manager, e.g.,
with github.GitHub() as gh:
u = gh.user('sigmavirus24')
100% (mock) test coverage
Add support for conditional refreshing, e.g.,
import github3
u = github3.user('sigmavirus24')
# some time later
u.refresh() # Will ALWAYS send a GET request and lower your ratelimit
u.refresh(True) # Will send the GET with a header such that if nothing
# has changed, it will not count against your ratelimit
# otherwise you'll get the updated user object.
Add support for conditional iterables. What this means is that you can do:
import github3
i = github3.iter_all_repos(10)
for repo in i:
# do stuff
i = github3.iter_all_repos(10, etag=i.etag)
And the second call will only give you the new repositories since the last request. This mimics behavior in pengwynn/octokit
Add support for sortable stars.
In github3.users.User, iter_keys now allows you to iterate over any user’s keys. No name is returned for each key. This is the equivalent of visiting: github.com/:user.keys
In github3.repos.Repository, pubsubhubbub has been removed. Use github3.github.Github.pubsubhubbub instead
In github3.api, iter_repo_issues‘s signature has been corrected.
Remove list_{labels, comments, events} methods from github3.issues.Issue
Remove list_{comments, commits, files} methods from github3.pulls.PullRequest
In github3.gists.Gist:
github3.events.Event.is_public() and github3.events.Event.public now return the same information. In the next version, the former will be removed.
In github3.issues.Issue
Now we won’t get spurious GitHubErrors on 404s, only on other expected errors whilst accessing the json in a response. All methods that return an object can now actually return None if it gets a 404 instead of just raising an exception. (Inspired by #49)
GitHubStatus API now works.
In github3.repos.Repository
In github3.repos.Hook
In github3.pulls.PullRequest
In github3.notifications.Thread
In github3.gists
github3.orgs.Organization.iter_repos now accepts all types
list_* methods on Organization objects that were missed are now deleted
Some objects now have __str__ methods. You can now do things like:
import github3
u = github3.user('sigmavirus24')
r = github3.repository(u, 'github3.py')
And
import github3
r = github3.repository('sigmavirus24', 'github3.py')
template = """Some kind of template where you mention this repository
{0}"""
print(template.format(r))
# Some kind of template where you mention this repository
# sigmavirus24/github3.py
Current list of objects with this feature:
60% test coverage with mock
Upgrade to requests 1.0.x
gotta hand it to @sigmavirus24 ... github3.py is really well written. It will soon be powering the github stuff on @workforpie
— Brad Montgomery # (@bkmontgomery) April 20, 2013
awesome github v3 api wrapper in python github.com/sigmavirus24/g#
— Mahdi Yusuf (@myusuf3) October 17, 2012
@sigmavirus24 github3 is awesome! Made my life much easier tonight, which is a very good thing.
— Mike Grouchy (@mgrouchy) March 26, 2013
@sigmavirus24 "There are so many Python client libraries for GitHub API, I tried all of them, and my conclusion is: github3.py is the best."
— Hong Minhee (@hongminhee) March 23, 2013
@sigmavirus24 I cannot wait to use your github package for #zci. Do you have it packaged for debian by any chance?
— Zygmunt Krynicki (@zygoon) March 26, 2013
Developing against github3.py's API is a joy, kudos to @sigmavirus24
— Alejandro Gomez (@dialelo) March 27, 2013