skip to navigation
skip to content 0.7.1

Python wrapper for the GitHub API(

Latest Version: 1.0.0a4

.. image:: is a comprehensive, actively developed and extraordinarily stable
wrapper around the GitHub API (v3).

See HISTORY.rst for any "breaking" changes.



$ pip install


- requests_ by Kenneth Reitz
- uritemplate.py_ by Ian Cordasco

.. _requests:


Please read the `CONTRIBUTING`_ document.



You can run either ``pip install -r requirements.txt`` to install the
following before testing or simply ``make test-deps``. It is suggested you do
this in a virtual enviroment. These need to be installed for the tests to run.

- expecter_ by Gary Bernhardt
- mock_ by Michael Foord
- coverage_ by Ned Batchelder

.. _expecter:
.. _coverage:
.. _mock:


Modified BSD license_

.. _license:


See the docs_ for more examples.

.. _docs:


Install the dependencies from requirements.txt e.g.:


pip install -r requirements.txt
# or make test-deps


make tests


Ian Cordasco (sigmavirus24)

Contact Options

- Feel free to use the ``_ tag on StackOverflow for any questions
you may have
- If you dislike StackOverflow it is preferred that you send an email to
- You may also contact (via email) the author directly with
questions/suggestions/comments or if you wish to include sensitive data.



0.7.1: 2013-09-30

- Add dependency on uritemplate.py_ to add URITemplates to different classes.
See the documentation for attributes which are templates.

- Fixed issue trying to parse ``html_url`` on Pull Requests courtesy of

- Remove ``expecter`` as a test dependency courtesy of @esacteksab.

- Fixed issue #141 trying to find an Event that doesn't exist.


0.7.0: 2013-05-19

- 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 <http:"" v3="" oauth="" #check-an-authorization="">`_.

- Add ``create_file``, ``update_file``, ``delete_file``,
``iter_contributor_statistics``, ``iter_commit_activity``,
``iter_code_frequency`` and ``weekly_commit_count`` to the ``Repository``

- 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:

- ``github3.GitHub`` can now be used as a context manager, e.g.,

with github.GitHub() as gh:
u = gh.user('sigmavirus24')

0.6.1: 2013-04-06

- Add equality for labels courtesy of Alejandro Gomez (@alejandrogomez)

0.6.0: 2013-04-05

- Add ``sort`` and ``order`` parameters to ``github3.GitHub.search_users`` and

- Add ``iter_commits`` to ``github3.gists.Gist`` as a means of re-requesting
just the history from GitHub and iterating over it.

- Add minimal logging (e.g., ``logging.getLogger('github3')``)

- Re-organize the library a bit. (Split up,, and a
few others into sub-modules for my sanity.)

- Calling ``refresh(True)`` on a ``github3.structs.GitHubIterator`` actually
works as expected now.

- API ``iter_`` methods now accept the ``etag`` argument as the
``GitHub.iter_`` methods do.

- Make ``github3.octocat`` and ``github3.github.GitHub.octocat`` both support
sending messages to make the Octocat say things. (Think cowsay)

- Remove vendored dependency of PySO8601.

- Split ``GitHub.iter_repos`` into ``GitHub.iter_user_repos`` and
``GitHub.iter_repos``. As a consequence ``github3.iter_repos`` is now

- ``IssueComment.update`` was corrected to match GitHub's documentation

- ``github3.login`` now accepts an optional ``url`` parameter for users of the
``GitHubEnterprise`` API, courtesy of Kristian Glass (@doismellburning)

- Several classes now allow their instances to be compared with ``==`` and
``!=``. In most cases this will check the unique id provided by GitHub. In
others, it will check SHAs and any other guaranteed immutable and unique
attribute. The class doc-strings all have information about this and details
about how equivalence is determined.

0.5.3: 2013-03-19

- Add missing optional parameter to Repository.contents. Thanks @tpetr

0.5.2: 2013-03-02

- Stop trying to decode the byte strings returned by ``b64decode``. Fixes #72

0.5.1: 2013-02-21

- Hot fix an issue when a user doesn't have a real name set

0.5: 2013-02-16

- 100% (mock) test coverage

- Add support for the announced_ meta_ endpoint.

- 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

- 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

- In github3.gists.Gist:

- the ``user`` attribute was changed by GitHub and is now the ``owner``

- the ``public`` attribute and the ``is_public`` method return the same
information. The method will be removed in the next version.

- the ``is_starred`` method now requires authentication

- the default ``refresh`` method is no longer over-ridden. In a change made
in before, a generic ``refresh`` method was added to most objects. This
was overridden in the Gist object and would cause otherwise unexpected

- ```` and ```` now
return the same information. In the next version, the former will be

- In github3.issues.Issue

- ``add_labels`` now returns the list of Labels on the issue instead of a

- ``remove_label`` now retuns a boolean.

- ``remove_all_labels`` and ``replace_labels`` now return lists. The former
should return an empty list on a successful call. The latter should
return a list of ``github3.issue.Label`` objects.

- 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.

.. _announced:
.. _meta:
.. _sortable stars:
.. _pengwynn/octokit:

0.4: 2013-01-16

- In github3.legacy.LegacyRepo

- ``has_{downloads,issues,wiki}`` are now attributes.
- ``is_private()`` and the ``private`` attribute return the same thing
``is_private()`` will be deprecated in the next release.

- In github3.repos.Repository

- ``is_fork()`` is now deprecated in favor of the ``fork`` attribute
- ``is_private()`` is now deprecated in favor of the ``private`` attribute

- In github3.repos.Hook

- ``is_active()`` is now deprecated in favor of the ``active`` attribute

- In github3.pulls.PullRequest

- ``is_mergeable()`` is now deprecated in favor of the ``mergeable``

- In github3.notifications.Thread

- ``is_unread()`` is now deprecated in favor of the ``unread``

- ``pubsubhubbub()`` is now present on the ``GitHub`` object and will be
removed from the ``Repository`` object in the next release

- 70% test coverage

0.3: 2013-01-01

- In github3.repos.Repository

- is_fork() and fork return the same thing
- is_private() and private return the same thing as well
- has_downloads, has_issues, has_wiki are now straight attributes

- In github3.repos.Hook

- is_active() and active return the same value

- In github3.pulls.PullRequest

- is_mergeable() and mergeable are now the same
- repository now returns a tuple of the login and name of the repository it
belongs to

- In github3.notifications.Thread

- is_unread() and unread are now the same

- In github3.gists

- GistFile.filename and return the same information
- Gist.history now lists the history of the gist
- GistHistory is an object representing one commit or version of the history
- You can retrieve gists at a specific version with GistHistory.get_gist()

- 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, '')



import github3

r = github3.repository('sigmavirus24', '')

template = """Some kind of template where you mention this repository

# Some kind of template where you mention this repository
# sigmavirus24/

Current list of objects with this feature:

- github3.users.User (uses the login name)
- github3.users.Key (uses the key text)
- github3.users.Repository (uses the login/name pair)
- github3.users.RepoTag (uses the tag name)
- github3.users.Contents (uses the decoded content)

- 60% test coverage with mock
- Upgrade to requests 1.0.x

.. _types:

0.2: 2012-11-21


- ``GitHub.iter_subscribed`` --> ``GitHub.iter_subscriptions``
- Broken ``list_*`` functions in github3.api have been renamed to the correct
``iter_*`` methods on ``GitHub``.
- Removed ``list_*`` functions from ``Repository``, ``Gist``,
``Organization``, and ``User`` objects

- Added zen of GitHub method.
- More tests
- Changed the way ``Repository.edit`` works courtesy of Kristian Glass
- Changed ``Repository.contents`` behaviour when acting on a 404.
- 50% test coverage via mock tests

0.1: 2012-11-13

- Add API for GitHub Enterprise customers.

0.1b2: 2012-11-10

- Handle 500 errors better, courtesy of Kristian Glass (@doismellburning)
- Handle sending json with `%` symbols better, courtesy of Kristian Glass
- Correctly handle non-GitHub committers and authors courtesy of Paul Swartz
- Correctly display method signatures in documentation courtesy of (@seveas)

0.1b1: 2012-10-31

- unit tests implemented using mock instead of hitting the GitHub API (#37)
- removed ``list_*`` functions from GitHub object
- Notifications API coverage

0.1b0: 2012-10-06

- Support for the complete GitHub API (accomplished)

- Now also includes the Statuses API
- Also covers the auto_init parameters to the Repository creation
- Limited implementation of iterators in the place of list functions.

- 98% coverage by unit tests  
File Type Py Version Uploaded on Size (md5) Python Wheel 2.7 2013-10-01 114KB (md5) Source 2013-10-01 83KB