github3.py 0.7.1

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