Skip to main content
Help us improve Python packaging – donate today!

Python wrapper for the GitHub API(http://developer.github.com/v3)

Project Description

.. image::
https://raw.github.com/sigmavirus24/github3.py/develop/images/gh3-logo.png

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

See HISTORY.rst for any "breaking" changes.

Installation
------------

::

$ pip install github3.py

Dependencies
------------

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

.. _requests: https://github.com/kennethreitz/requests
.. _uritemplate.py: https://github.com/sigmavirus24/uritemplate

Contributing
------------

Please read the `CONTRIBUTING`_ document.

.. _CONTRIBUTING: https://github.com/sigmavirus24/github3.py/blob/develop/CONTRIBUTING.rst

Testing
~~~~~~~

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: https://github.com/garybernhardt/expecter
.. _coverage: http://nedbatchelder.com/code/coverage/
.. _mock: http://mock.readthedocs.org/en/latest/

License
-------

Modified BSD license_

.. _license: https://github.com/sigmavirus24/github3.py/blob/develop/LICENSE

Examples
--------

See the docs_ for more examples.

.. _docs: http://github3py.readthedocs.org/en/latest/index.html#more-examples

Testing
~~~~~~~

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

::

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

::

make tests

Author
------

Ian Cordasco (sigmavirus24)

Contact Options
---------------

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

.. _github3.py: http://stackoverflow.com/questions/tagged/github3.py


History/Changelog
=================

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

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

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

.. _uritemplate.py: https://github.com/sigmavirus24/uritemplate

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://developer.github.com/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``
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')

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
``github3.GitHub.search_repos``.

- 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 repos.py, issues.py, gists.py 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
``github3.iter_user_repos``

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

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

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

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

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

- ``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: https://github.com/blog/1402-upcoming-changes-to-github-services
.. _meta: http://developer.github.com/v3/meta/
.. _sortable stars:
http://developer.github.com/changes/2013-2-13-sortable-stars/
.. _pengwynn/octokit: https://github.com/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``
attribute

- 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 GistFile.name 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, '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:

- 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: http://developer.github.com/v3/repos/#list-organization-repositories

0.2: 2012-11-21
---------------

- MAJOR API CHANGES:

- ``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
(@doismellburning)
- 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
(@paulswartz)
- 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
methodology
- Limited implementation of iterators in the place of list functions.

- 98% coverage by unit tests

Release history Release notifications

History Node

1.1.0

History Node

1.0.2

History Node

1.0.1

History Node

1.0.0

History Node

1.0.0a4

History Node

1.0.0a3

History Node

1.0.0a2

History Node

1.0.0a1

History Node

0.9.6

History Node

0.9.5

History Node

0.9.4

History Node

0.9.3

History Node

0.9.2

History Node

0.9.1

History Node

0.9.0

History Node

0.8.2

History Node

0.8.1

History Node

0.8.0

This version
History Node

0.7.1

History Node

0.7.0

History Node

0.6.1

History Node

0.6.0

History Node

0.5.3

History Node

0.5.2

History Node

0.5.1

History Node

0.5

History Node

0.4

History Node

0.3

History Node

0.2

History Node

0.1

History Node

0.1b2

History Node

0.1b1

History Node

0.1b0

History Node

0.1a8

History Node

0.1a7

History Node

0.1a6

History Node

0.1a5

History Node

0.1a4

History Node

0.1a3

History Node

0.1a2

History Node

0.1a1

History Node

0.1a

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
github3.py-0.7.1-py2.py3-none-any.whl (117.1 kB) Copy SHA256 hash SHA256 Wheel 2.7 Oct 1, 2013
github3.py-0.7.1.tar.gz (85.5 kB) Copy SHA256 hash SHA256 Source None Oct 1, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page