github3.py

Release v1.0.0a1.

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.

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_count)
# 4

for f in gh.followers():
    print(str(f))

kennethreitz = gh.user('kennethreitz')
# <User [kennethreitz:Kenneth Reitz]>

print(kennethreitz.name)
print(kennethreitz.login)
print(kennethreitz.followers_count)

followers = [str(f) for f in gh.followers('kennethreitz')]

Modules

Internals

For objects you’re not likely to see in practice. This is useful if you ever feel the need to contribute to the project.

Installation

$ pip install github3.py
# OR:
$ git clone git://github.com/sigmavirus24/github3.py.git github3.py
$ cd github3.py
$ python setup.py install

Dependencies

Contributing

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.

Contributor Friendly Work

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.

Running the Unittests

The tests are generally run using tox. Tox can be installed lke so:

pip install tox

We test against PyPy and the following versions of Python:

  • 2.6
  • 2.7
  • 3.2
  • 3.3
  • 3.4

If you simply run tox it will run tests against all of these versions of python and run flake8 against the codebase as well. If you want to run against one specific version, you can do:

tox -e py34

And if you want to run tests against a specific file, you can do:

tox -e py34 -- tests/uni/test_github.py

To run the tests, tox uses py.test so you can pass any options or parameters to py.test after specifying --. For example, you can get more verbose output by doing:

tox -e py34 -- -vv

Contact

  • Twitter: @sigmavirus24
  • Private email: graffatcolmingov [at] gmail
  • Mailing list: github3.py [at] librelist.com

Latest Version’s Changes

1.0.0a1: 2014-12-07

1.0.0 is a huge release. It includes a great deal of changes to github3.py. It is suggested you read the following release notes very carefully.

Breaking Changes

  • Organization#add_member has been changed. The second parameter has been changed to team_id and now expects an integer.
  • Organization#add_repository has been changed. The second parameter has been changed to team_id and now expects an integer.
  • All methods and functions starting with iter_ have been renamed.
Old name New name
github3.iter_all_repos github3.all_repositories
github3.iter_all_users github3.all_users
github3.iter_events github3.all_events
github3.iter_followers github3.followers_of
github3.iter_following github3.followed_by
github3.iter_repo_issues github3.issues_on
github3.iter_orgs github3.organizations_with
github3.iter_user_repos github3.repositories_by
github3.iter_starred github3.starred_by
github3.iter_subscriptions github3.subscriptions_for
Deployment#iter_statuses Deployment#statuses
Gist#iter_comments Gist#comments
Gist#iter_commits Gist#commits
Gist#iter_files Gist#files
Gist#iter_forks Gist#forks
GitHub#iter_all_repos GitHub#all_repositories
GitHub#iter_all_users GitHub#all_users
GitHub#iter_authorizations GitHub#authorizations
GitHub#iter_emails GitHub#emails
GitHub#iter_events GitHub#events
GitHub#iter_followers GitHub#{followers,followers_of}
GitHub#iter_following GitHub#{following,followed_by}
GitHub#iter_gists GitHub#{gists,gists_by,public_gists}
GitHub#iter_notifications GitHub#notifications
GitHub#iter_org_issues GitHub#organization_issues
GitHub#iter_issues GitHub#issues
GitHub#iter_user_issues GitHub#user_issues
GitHub#iter_repo_issues GitHub#issues_on
GitHub#iter_keys GitHub#keys
GitHub#iter_orgs GitHub#{organizations,organizations_with}
GitHub#iter_repos GitHub#reposistories
GitHub#iter_user_repos GitHub#repositories_by
GitHub#iter_user_teams GitHub#user_teams
Issue#iter_comments Issue#comments
Issue#iter_events Issue#events
Issue#iter_labels Issue#labels
Milestone#iter_labels Milestone#labels
Organization#iter_members Organization#members
Organization#iter_public_members Organization#public_members
Organization#iter_repos Organization#repositories
Organization#iter_teams Organization#teams
PullRequest#iter_comments PullRequest#review_comments
PullRequest#iter_commits PullRequest#commits
PullRequest#iter_files PullRequest#files
PullRequest#iter_issue_comments PullRequest#issue_comments
Team#iter_members Team#members
Team#iter_repos Team#repositories
Repository#iter_assignees Repository#assignees
Repository#iter_branches Repository#branches
Repository#iter_code_frequency Repository#code_frequency
Repository#iter_collaborators Repository#collaborators
Repository#iter_comments Repository#comments
Repository#iter_comments_on_commit Repository#comments_on_commit
Repository#iter_commit_activity Repository#commit_activity
Repository#iter_commits Repository#commits
Repository#iter_contributor_statistics Repository#contributor_statistics
Repository#iter_contributors Repository#contributors
Repository#iter_forks Repository#forks
Repository#iter_hooks Repository#hooks
Repository#iter_issues Repository#issues
Repository#iter_issue_events Repository#issue_events
Repository#iter_keys Repository#keys
Repository#iter_labels Repository#labels
Repository#iter_languages Repository#languages
Repository#iter_milestones Repository#milestones
Repository#iter_network_events Repository#network_events
Repository#iter_notifications Repository#notifications
Repository#iter_pages_builds Repository#pages_builds
Repository#iter_pulls Repository#pull_requests
Repository#iter_refs Repository#refs
Repository#iter_releases Repository#releases
Repository#iter_stargazers Repository#stargazers
Repository#iter_subscribers Repository#subscribers
Repository#iter_statuses Repository#statuses
Repository#iter_tags Repository#tags
Repository#iter_teams Repository#teams
Repository#iter_teams Repository#teams
User#iter_events User#events
User#iter_followers User#followers
User#iter_following User#following
User#iter_keys User#keys
User#iter_org_events User#organization_events
User#iter_received_events User#received_events
User#iter_orgs User#organizations
User#iter_starred User#starred_repositories
User#iter_subscriptions User#subscriptions
  • github3.login has been simplified and split into two functions:
    • github3.login serves the majority use case and only provides an authenticated GitHub object.
    • github3.enterprise_login allows GitHub Enterprise users to log into their service.
  • GitHub#iter_followers was split into two functions:
    • GitHub#followers_of which iterates over all of the followers of a user whose username you provide
    • GitHub#followers which iterates over all of the followers of the authenticated user
  • GitHub#iter_following was split into two functions:
    • GitHub#followed_by which iterates over all of the users followed by the username you provide
    • GitHub#following which iterates over all of the users followed by the authenticated user
  • GitHub#iter_gists was split into three functions:
    • GitHub#public_gists which iterates over all of the public gists on GitHub
    • GitHub#gists_for which iterates over all the public gists of a specific user
    • GitHub#gists which iterates over the authenticated users gists
  • GitHub#iter_orgs was split into two functions:
    • GitHub#organizations which iterates over the authenticated user’s organization memberships
    • GitHub#organizations_with which iterates over the given user’s organization memberships
  • GitHub#iter_subscriptions was split into two functions:
    • GitHub#subscriptions_for which iterates over an arbitrary user’s subscriptions
    • GitHub#subscriptions which iterates over the authenticated user’s subscriptions
  • GitHub#iter_starred was split into two functions:
    • GitHub#starred_by which iterates over an arbitrary user’s stars
    • GitHub#starred which iterates over the authenticated user’s stars
  • GitHub#user was split into two functions:
    • GitHub#user which retrieves an arbitrary user’s information
    • GitHub#me which retrieves the authenticated user’s information
  • GitHub#update_user has been renamed to GitHub#update_me and only uses 1 API call now. It was renamed to reflect the addition of GitHub#me.
  • The legacy watching API has been removed:
    • GitHub#subscribe
    • GitHub#unsubscribe
    • GitHub#is_subscribed
  • GitHub#create_repo was renamed to GitHub#create_repository
  • GitHub#delete_key was removed. To delete a key retrieve it with GitHub#key and then call Key#delete.
  • Repository#set_subscription was split into two simpler functions
    • Repository#subscribe subscribes the authenticated user to the repository’s notifications
    • Repository#ignore ignores notifications from the repository for the authenticated user
  • Repository#contents was split into two simpler functions
    • Repository#file_contents returns the contents of a file object
    • Repository#directory_contents returns the contents of files in a directory.
  • Organization#add_repo and Team#add_repo have been renamed to Organization#add_repository and Team#add_repository respectively.
  • Organization#create_repo has been renamed to Organization#create_repository. It no longer accepts has_downloads. It now accepts license_template.
  • Organization#remove_repo has been renamed to Organization#remove_repository. It now accepts team_id instead of team.
  • github3.ratelimit_remaining was removed
  • GitHub instances can no longer be used as context managers
  • The pull request API has changed.
    • The links attribute now contains the raw _links attribute from the API.
    • The merge_commit_sha attribute has been removed since it was deprecated in the GitHub API.
    • To present a more consistent universal API, certain attributes have been renamed.
Old name New attribute name
PullFile.additions additions_count
PullFile.deletions deletions_count
PullFile.changes changes_count
PullRequest.additions additions_count
PullRequest.comments comments_count
PullRequest.commits commits_count
PullRequest.deletions deletions_count
PullRequest.review_comments review_comments_count
  • The Gist API has changed.

    • The forks and files attributes that used to keep count of the number of forks and files have been removed.
    • The comments attribute which provided the number of comments on a gist, has been renamed to comments_count.
    • The is_public method has been removed since it just returned the Gist.public attribute.
  • Most instances of login as a parameter have been changed to username for clarity and consistency. This affects the following methods:

    • github3.authorize
    • github3.repositories_by
    • github3.user
    • GitHub
    • GitHub#authorize
    • GitHub#follow
    • GitHub#is_following
    • GitHub#is_starred
    • GitHub#issue
    • GitHub#followers_of
    • GitHub#followed_by
    • GitHub#gists_by
    • GitHub#issues_on
    • GitHub#organizations_with
    • GitHub#starred_by
    • GitHub#subscriptions_for
    • GitHub#user
    • GitHubEnterprise
    • Issue#assign
    • Organization#add_member
    • Organization#is_member
    • Organization#is_public_member
    • Organization#remove_member
    • Repository#add_collaborator
    • Repository#is_assignee
    • Repository#is_collaborator
    • Repository#remove_collaborator
    • Team#add_member
    • Team#is_member
    • User#is_assignee_on
    • User#is_following
  • Repository.stargazers is now Repository.stargazers_count (conforming with the attribute name returned by the API).

  • The Issue API has changed in order to provide a more consistent attribute API. Issue.comments is now Issue.comments_count and returns the number of comments on an issue.

  • The Issue.labels attribute has also been renamed. It is now available from Issue.original_labels. This will provide the user with the list of Label objects that was returned by the API. To retrieve an updated list of labels, the user can now use Issue#labels, e.g.

    i = github3.issue('sigmavirus24', 'github3.py', 30)
    labels = list(i.labels())
    
  • The Organization and User APIs have changed to become more consistent with the rest of the library and GitHub API. The following attribute names have been changed

Old name New attribute name
Organization.followers followers_count
Organization.following following_count
Organization.public_repos public_repos_count
User.followers followers_count
User.following following_count
User.public_repos public_repos_count
  • The Release.assets attribute has been renamed to Release.original_assets. To retrieve up-to-date assets, use the Release#assets method.
  • The Authorization API has changed. The update method has been split into three methods: add_scopes, remove_scopes, replace_scopes. This highlights the fact that Authorization#update used to require more than one request.
  • Event#is_public has been removed. Simply check the event’s public attribute instead.
  • Repository#delete_file and Repository#update_file have been removed. Simply delete or update a file using the Contents API.
  • Content#delete now returns a dictionary that matches the JSON returned by the API. It contains the Contents and the Commit associated with the deletion.
  • Content#update now returns a dictionary that matches the JSON returned by the API. It contains the Contents and the Commit associated with the deletion.
  • Issue.pull_request has been renamed to Issue.pull_request_urls

New Features

  • Most objects now have a session attribute. This is a subclass of a Session object from requests. This can now be used in conjunction with a third-party caching mechanism. The suggested caching library is cachecontrol.

  • All object’s url attribute are now available.

  • You can now retrieve a repository by its id with GitHub#repository_with_id.

  • You can call the pull_request method on an Issue now to retrieve the associated pull request:

    import github3
    
    i = github3.issue('sigmavirus24', 'github3.py', 301)
    pr = i.pull_request()
    

The full history of the project is available as well.

Testimonials