Metadata-Version: 2.0
Name: sqre-github3.py
Version: 1.0.0a4
Summary: Python wrapper for the GitHub API(http://developer.github.com/v3)
Home-page: https://github3py.readthedocs.io
Author: Ian Cordasco
Author-email: graffatcolmingov@gmail.com
License: 3-clause BSD
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: requests>=2.0
Requires-Dist: uritemplate>=3.0.0
Requires-Dist: pyOpenSSL>=0.13; python_version<="2.7"
Requires-Dist: ndg-httpsclient; python_version<="2.7"
Requires-Dist: pyasn1; python_version<="2.7"

.. 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 --pre github3.py

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

- requests_  by Kenneth Reitz
- uritemplate_ by Ian Cordasco

.. _requests: https://github.com/kennethreitz/requests
.. _uritemplate: 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 dev-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.

- betamax_
- coverage_ by Ned Batchelder
- mock_ by Michael Foord

.. _betamax: https://github.com/sigmavirus24/betamax
.. _coverage: http://nedbatchelder.com/code/coverage/
.. _mock: https://mock.readthedocs.io/en/latest/

License
-------

Modified BSD license_

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

Examples
--------

See the docs_ for more examples.

.. _docs: https://github3py.readthedocs.io/en/latest/index.html#more-examples

Testing
~~~~~~~

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

::

    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


.. vim: set tw=100

Unreleased
~~~~~~~~~~

- Add ``Organization#all_events``.
- Deprecate ``Organization#events`` in favor of ``Organization#public_events``.
- Fix test failtures on windows caused by unclosed file handles.
- Add ``Tag.tagger_as_User`` which attempts to return the tagger as as User.
- Add ``Repo.statuses`` and a corresponding ``repo.status.CombinedStatus`` to
  get a combined view of commit statuses for a given ref.

1.0.0a4: 2016-02-19
~~~~~~~~~~~~~~~~~~~

Features Added (since 1.0.0a3)
``````````````````````````````

- Add support for the Issue locking API currently in Preview Mode

Bugs Fixed (since 1.0.0a3)
``````````````````````````

- Fix the dependencies and requirements. In 1.0.0a3 we moved to using the
  ``setup.cfg`` file to define optional dependencies for wheels. By doing
  so we accidentally left out our actual hard dependencies.

1.0.0a3: 2016-02-11
~~~~~~~~~~~~~~~~~~~

Breaking Changes (since 1.0.0a2)
````````````````````````````````

- Move ``Users#add_email_addresses`` to ``GitHub#add_email_addresses``.

- Move ``Users#delete_email_addresses`` to ``GitHub#delete_email_addresses``.

- Remove ``Users#add_email_address`` and ``Users#delete_email_address``.

- Remove ``Repository#update_label``.

Features Added (since 1.0.0a2)
``````````````````````````````

- Support filtering organization members by whether they have 2FA enabled.

- Support filtering organization and team members by role.

- Add ``GitHub#all_organizations``.

- Add ``PullRequest#create_comment``.

- Add ``Repository#release_by_tag_name`` to retrieve a Release from a
  Repository by its associated tag name.

- Add ``Repository#latest_release`` to retrieve the latest Release for a
  Repository.

- Add ``GitHub#license`` to retrieve a ``github3.license.License`` by the
  license name.

- Add ``GitHub#licenses`` to iterate over all the licenses returned by
  GitHub's Licenses API.

- Add protection information to ``github3.repos.branch.Branch``.

- Add ``Branch#protect`` and ``Branch#unprotect`` to support updating a
  Branch's protection status.

- Vastly improved GitHub Enterprise support:

  - Add ``User#rename`` to rename a user in a GitHub Enterprise installation.

  - Add ``GitHub#create_user`` to create a user.

  - Add ``User#impersonate`` to create an impersonation token by an admin for
    a particular user.

  - Add ``User#revoke_impersonation`` to revoke all impersonation tokens for a
    user.

  - Add ``User#promote`` to promote a particular user to a site administrator.

  - Add ``User#demote`` to demote a site administrator to a simple user.

  - Add ``User#suspend`` to suspend a user's account.

  - Add ``User#unsuspend`` to reinstate a user's account.

- Add ``original_content`` attribute to a ``GistFile``

- Add ``GistFile#content`` to retrieve the contents of a file in a gist from
  the API.

- Add support for the alpha `bulk issue import API`_

.. _bulk issue import API:
    https://gist.github.com/jonmagic/5282384165e0f86ef105

Bugs Fixed (since 1.0.0a2)
``````````````````````````

- The ``context`` parameter to ``Repository#create_status`` now properly
  defaults to ``"default"``.

- Fix AttributeError when ``IssueEvent`` has assignee.

- Correctly set the ``message`` attribute on ``RepoCommit`` instances.

- Include ``browser_download_url`` on ``Asset`` instances.

- (Packaging related) Fix ``setup.py`` to use proper values for certain
  parameters.

- Fix ``ValueError`` for ``Repository#create_file``.

1.0.0a2: 2015-07-14
~~~~~~~~~~~~~~~~~~~

Breaking Changes (since 1.0.0a1)
````````````````````````````````

- When you download a release asset, instead of returning ``True`` or
  ``False``, it will return the name of the file in which it saved the asset.

- The ``download`` method on ``github3.pulls.PullFile`` instances has been
  removed.

- The ``contents`` method on ``github3.pulls.PullFile`` instances now return
  instances of ``github3.repos.contents.Contents``.

- Replace ``Repository#comments_on_commit`` with ``RepoCommit#comments``.

Features Added (since 1.0.0a1)
``````````````````````````````

- You can now download a file in a pull request to a file on disk.

- You can retrieve the contents of the file in a pull request as bytes.

- Add ``id`` attribute to ``github3.repos.milestone.Milestone``.

- Add support for sort, direction, and since parameters to the ``comments``
  method on ``github3.issues.Issue``.

- Add branch argument to update and delete methods on
  ``github3.repos.contents.Contents``.

- Add ``permissions`` attribute to ``github3.repos.repo.Repository`` object to
  retrieve the permissions for a specific repository.

- Allow a deployment to be retrieved by its id.

- Add the ``delete`` method to the ``github3.repos.release.Asset`` class.

Bugs Fixed (since 1.0.0a1)
``````````````````````````

- Pull request files can now be downloaded even when the repository is
  private.

- Fix exception when merging a pull request with an empty commit message.

- Add missing Issue events.

- Coerce review comment positions to integers.


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``        ``RepoCommit#comments``
``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()


