diff --git a/.gitignore b/.gitignore index b869b6c70..ef65ff3bf 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,5 @@ venv*/ build/ *.egg .env +.ipynb_checkpoints +.cache/ diff --git a/.travis.yml b/.travis.yml index a7cd99b97..b5e8c177c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,10 +1,10 @@ language: python + before_script: - pip install tox -- pip install -U requests"$REQUESTS_VERSION" # test script -script: tox -e ${TOX_ENV} +script: tox notifications: on_success: change on_failure: always @@ -12,23 +12,38 @@ notifications: env: global: - TRAVIS_GH3="True" - matrix: - - TOX_ENV=py26 REQUESTS_VERSION="==2.0.1" - - TOX_ENV=py27 REQUESTS_VERSION="==2.0.1" - - TOX_ENV=py32 REQUESTS_VERSION="==2.0.1" - - TOX_ENV=py33 REQUESTS_VERSION="==2.0.1" - - TOX_ENV=py34 REQUESTS_VERSION="==2.0.1" - - TOX_ENV=pypy REQUESTS_VERSION="==2.0.1" - - TOX_ENV=py26 REQUESTS_VERSION="" - - TOX_ENV=py27 REQUESTS_VERSION="" - - TOX_ENV=py32 REQUESTS_VERSION="" - - TOX_ENV=py33 REQUESTS_VERSION="" - - TOX_ENV=py34 REQUESTS_VERSION="" - - TOX_ENV=pypy REQUESTS_VERSION="" - - TOX_ENV=py27-flake8 - - TOX_ENV=py34-flake8 matrix: + include: + - python: 2.7 + env: TOXENV=py27 REQUESTS_VERSION="===2.0.1" + - python: 3.3 + env: TOXENV=py33 REQUESTS_VERSION="===2.0.1" + - python: 3.4 + env: TOXENV=py34 REQUESTS_VERSION="===2.0.1" + - python: 3.5 + env: TOXENV=py35 REQUESTS_VERSION="===2.0.1" + - python: pypy + env: TOXENV=pypy REQUESTS_VERSION="===2.0.1" + - python: 2.7 + env: TOXENV=py27 REQUESTS_VERSION="" + - python: 3.3 + env: TOXENV=py33 REQUESTS_VERSION="" + - python: 3.4 + env: TOXENV=py34 REQUESTS_VERSION="" + - python: 3.5 + env: TOXENV=py35 REQUESTS_VERSION="" + - python: pypy + env: TOXENV=pypy REQUESTS_VERSION="" + - env: TOXENV=py27-flake8 + - env: TOXENV=py34-flake8 + - env: TOXENV=docstrings + - env: TOXENV=notebooks + - env: TOXENV=readme + - env: TOXENV=docs + fast_finish: true allow_failures: - - env: TOX_ENV=py27-flake8 - - env: TOX_ENV=py34-flake8 + - env: TOXENV=docstrings + - env: TOXENV=notebooks + +sudo: false diff --git a/AUTHORS.rst b/AUTHORS.rst index 789c50409..524ff846d 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -3,11 +3,15 @@ Development Lead - Ian Cordasco +- Matt Chung (@itsmemattchung) + Maintainer(s) ````````````` - Barry Morrison (@esacteksab) +- Matt Chung (@itsmemattchung) + Requests ```````` @@ -80,3 +84,60 @@ Contributors - Marc Abramowitz (@msabramo) - Adrian Moisey (@adrianmoisey) + +- Bryce Boe (@bboe) + +- Ryan Weald (@rweald) + +- Lars Holm Nielsen (@larshankat) + +- Ryan Pitts (@ryanpitts) + +- Jürgen Hermann (@jhermann) + +- Antoine Giraudmaillet (@antoine-g) + +- Paulus Schoutsen (@balloob) + +- Nolan Bruabker (@nrb) + +- Marcin Wielgoszewski (@mwielgoszewski) + +- Omri Harel (@omriharel) + +- Noel Lee (@noellee) + +- Sourav Singh(@souravsingh) + +- Matt Chung (@itsmemattchung) + +- Chris Thompson (@notyetsecure) + +- Bastien Gandouet (@b4stien) + +- Usman Ehtesham Gul (@ueg1990) + +- Derek Gustafson (@degustaf) + +- Christophe Lecointe (@christophelec) + +- Abhijeet Kasurde (@akasurde) + +- Matthew Krueger (@mlkrueger1987) + +- Dejan Svetec (@dsvetec) + +- Billy Keyes (@bluekeyes) + +- Evan Borgstrom (@borgstrom) + +- Goodwillcoding (@goodwillcoding) + +- Andreas Backx (@AndreasBackx) + +- Alexander Koshelev + +- Gabi Davar (@mindw) + +- Björn Kautler (@Vampire) + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..01b8644f1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,22 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic addresses, without explicit permission +* Other unethical or unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team. + +This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 083e4bbb4..590b20309 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -61,7 +61,7 @@ Guidelines for Contributing to github3.py .. _easy: https://github.com/sigmavirus24/github3.py/issues?labels=Easy&page=1&state=open .. _Pair with Ian: https://github.com/sigmavirus24/github3.py/issues?labels=Pair+with+Ian&page=1&state=open .. _AUTHORS.rst: ./AUTHORS.rst -.. _cordial: http://kennethreitz.com/be-cordial-or-be-on-your-way.html +.. _cordial: http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way .. _pep-0008: http://www.python.org/dev/peps/pep-0008/ .. _docstrings: http://www.python.org/dev/peps/pep-0257/ .. _flake8: http://pypi.python.org/pypi/flake8 diff --git a/HISTORY.rst b/HISTORY.rst index 83387d0dd..25f913cc4 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,5 +1,4 @@ -History/Changelog ------------------ +.. vim: set tw=100 0.9.3: 2014-11-04 ~~~~~~~~~~~~~~~~~ @@ -70,10 +69,10 @@ History/Changelog - Allow users to pass a two-factor authentication callback to ``GitHub#authorize``. -.. _single authorization: https://github3py.readthedocs.org/en/latest/github.html#github3.github.GitHub.revoke_authorization -.. _all authorizations: https://github3py.readthedocs.org/en/latest/github.html#github3.github.GitHub.revoke_authorizations -.. _ping: https://github3py.readthedocs.org/en/latest/repos.html?highlight=ping#github3.repos.hook.Hook.ping -.. _Repository's collaborators: https://github3py.readthedocs.org/en/latest/repos.html#github3.repos.repo.Repository.iter_collaborators +.. _single authorization: https://github3py.readthedocs.io/en/latest/github.html#github3.github.GitHub.revoke_authorization +.. _all authorizations: https://github3py.readthedocs.io/en/latest/github.html#github3.github.GitHub.revoke_authorizations +.. _ping: https://github3py.readthedocs.io/en/latest/repos.html?highlight=ping#github3.repos.hook.Hook.ping +.. _Repository's collaborators: https://github3py.readthedocs.io/en/latest/repos.html#github3.repos.repo.Repository.iter_collaborators .. _pagination changes: https://developer.github.com/changes/2014-03-18-paginating-method-changes/ .. _stargarzers_url: https://github.com/sigmavirus24/github3.py/pull/240 diff --git a/LATEST_VERSION_NOTES.rst b/LATEST_VERSION_NOTES.rst new file mode 100644 index 000000000..115613222 --- /dev/null +++ b/LATEST_VERSION_NOTES.rst @@ -0,0 +1,533 @@ +.. 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() diff --git a/MANIFEST.in b/MANIFEST.in index 151251949..ddef6cac4 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,6 +1,7 @@ include README.rst include LICENSE include HISTORY.rst +include LATEST_VERSION_NOTES.rst include AUTHORS.rst include CONTRIBUTING.rst include tox.ini @@ -9,5 +10,6 @@ prune *.pyc recursive-include docs *.rst *.py Makefile recursive-include tests *.py *.json recursive-include tests/json * +recursive-include tests/unit/json * recursive-include images *.png prune docs/_build diff --git a/Makefile b/Makefile index ae1930c49..0b95d7ee5 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,9 @@ # Makefile for github3.py # -# Copyright 2012, Ian Cordasco +# Copyright 2015, Ian Cordasco COVERAGE_INCLUDE := github3/*.py -TEST_RUNNER := python setup.py test +TEST_RUNNER := tox .DEFAULT_GOAL := tests @@ -23,4 +23,4 @@ htmlcov: .coverage coverage html --omit=github3/packages/* docs: docs/*.rst - make -C docs/ html + tox -e docs diff --git a/README.rst b/README.rst index 23ab0d68e..c6bdb1b80 100644 --- a/README.rst +++ b/README.rst @@ -11,16 +11,16 @@ Installation :: - $ pip install github3.py + $ pip install --pre github3.py Dependencies ------------ - requests_ by Kenneth Reitz -- uritemplate.py_ by Ian Cordasco +- uritemplate_ by Ian Cordasco .. _requests: https://github.com/kennethreitz/requests -.. _uritemplate.py: https://github.com/sigmavirus24/uritemplate +.. _uritemplate: https://github.com/sigmavirus24/uritemplate Contributing ------------ @@ -42,7 +42,7 @@ this in a virtual enviroment. These need to be installed for the tests to run. .. _betamax: https://github.com/sigmavirus24/betamax .. _coverage: http://nedbatchelder.com/code/coverage/ -.. _mock: http://mock.readthedocs.org/en/latest/ +.. _mock: https://mock.readthedocs.io/en/latest/ License ------- @@ -56,7 +56,7 @@ Examples See the docs_ for more examples. -.. _docs: http://github3py.readthedocs.org/en/latest/index.html#more-examples +.. _docs: https://github3py.readthedocs.io/en/latest/index.html#more-examples Testing ~~~~~~~ diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 000000000..20a61a011 --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,35 @@ +version: build-{build}-{branch} + +environment: + matrix: + # http://www.appveyor.com/docs/installed-software#python lists available + # versions + - PYTHON: "C:\\Python27" + TOXENV: py27 + - PYTHON: "C:\\Python27-x64" + TOXENV: py27 + - PYTHON: "C:\\Python33" + TOXENV: py33 + - PYTHON: "C:\\Python33-x64" + TOXENV: py33 + - PYTHON: "C:\\Python34" + TOXENV: py34 + - PYTHON: "C:\\Python34-x64" + TOXENV: py34 + - PYTHON: "C:\\Python35" + TOXENV: py35 + - PYTHON: "C:\\Python35-x64" + TOXENV: py35 + +init: + - "echo %PYTHON%" + +install: + - "set PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%" + - python --version + - python -m pip install -U pip setuptools tox + +build: false + +test_script: + - tox -v diff --git a/dev-requirements.txt b/dev-requirements.txt index 6ab032431..8160ae0f4 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -1,7 +1,8 @@ -requests>=2.0.0,<=3.0.0 -uritemplate.py==0.2.0 +. #coverage==3.5.2 mock==1.0.1 pytest>=2.3.5 wheel==0.21.0 -git+git://github.com/sigmavirus24/betamax +betamax>=0.5.0 +betamax_matchers>=0.2.0 +tox>=2.5.0 diff --git a/docs/Makefile b/docs/Makefile index bf49b5422..ac7d83f05 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = sphinx-build +SPHINXBUILD = $(shell which sphinx-build) PAPER = BUILDDIR = _build diff --git a/docs/api.rst b/docs/api.rst index 5032ca58e..6fb2a46e8 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -61,47 +61,51 @@ Or you can simply use the following functions ------ -.. autofunction:: github3.iter_all_repos +.. autofunction:: github3.issues_on ------ -.. autofunction:: github3.iter_all_users +.. autofunction:: github3.all_repositories ------ -.. autofunction:: github3.iter_events +.. autofunction:: github3.all_users ------ -.. autofunction:: github3.iter_followers +.. autofunction:: github3.all_events ------ -.. autofunction:: github3.iter_following +.. autofunction:: github3.followers_of ------ -.. autofunction:: github3.iter_gists +.. autofunction:: github3.followed_by ------ -.. autofunction:: github3.iter_orgs +.. autofunction:: github3.public_gists ------ -.. autofunction:: github3.iter_user_repos +.. autofunction:: github3.gists_by ------ -.. autofunction:: github3.iter_repo_issues +.. autofunction:: github3.organizations_with ------ -.. autofunction:: github3.iter_starred +.. autofunction:: github3.repositories_by ------ -.. autofunction:: github3.iter_subscriptions +.. autofunction:: github3.starred_by + +------ + +.. autofunction:: github3.subscriptions_for ------ @@ -121,7 +125,7 @@ Or you can simply use the following functions ------ -.. autofunction:: github3.ratelimit_remaining +.. autofunction:: github3.rate_limit ------ @@ -143,7 +147,6 @@ Or you can simply use the following functions .. autofunction:: github3.search_users - ------ .. autofunction:: github3.user diff --git a/docs/conf.py b/docs/conf.py index 0262cdbe8..3d1ec55c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -96,7 +96,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' +#html_theme = 'nature' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/events.rst b/docs/events.rst index c97c6962a..04dbed79e 100644 --- a/docs/events.rst +++ b/docs/events.rst @@ -34,4 +34,4 @@ Having individual handlers as we have now which modify the payload to use our objects when available is more sensible. .. links -.. _type: http://developer.github.com/v3/events/types +.. _type: https://developer.github.com/v3/activity/events/types diff --git a/docs/examples/github.rst b/docs/examples/github.rst index 2277b6c11..0d7845904 100644 --- a/docs/examples/github.rst +++ b/docs/examples/github.rst @@ -1,4 +1,4 @@ -.. _github: +.. _github_examples: GitHub Examples =============== @@ -166,6 +166,6 @@ Note that you **can not** change your login name via the API. This is the same as:: - me = g.user() + me = g.me() # or me = g.user(your_user_name) if me.update(new_name, blog, company, bio=bio): print('Profile updated.') diff --git a/docs/examples/issue.rst b/docs/examples/issue.rst index 631a160ea..61b6cdba1 100644 --- a/docs/examples/issue.rst +++ b/docs/examples/issue.rst @@ -49,3 +49,32 @@ Or how to do the same by wrapping the lines in your terminal. .. literalinclude:: source/wrap_text.py :language: python + +Importing an issue +------------------ + +Not only can you create new issues, but you can import existing ones. When importing, you preserve the timestamp creation date; you can preserve the timestamp(s) for comment(s) too. + +:: + + import github3 + gh = github3.login(token=token) + issue = { + 'title': 'Documentation issue', + 'body': 'Missing links in index.html', + 'created_at': '2011-03-11T17:00:40Z' + } + + repository = gh.repository(user, repo) + repository.import_issue(**issue) + +Status of imported issue +~~~~~~~~~~~~~~~~~~~~~~~~ + +Here's how to check the status of the imported issue. + +:: + + import github3 + issue = repository.imported_issue(issue_num) + print issue.status diff --git a/docs/examples/two_factor_auth.rst b/docs/examples/two_factor_auth.rst index 7a7d9edd1..b003160c4 100644 --- a/docs/examples/two_factor_auth.rst +++ b/docs/examples/two_factor_auth.rst @@ -33,5 +33,5 @@ For example: g = github3.login('sigmavirus24', 'my_password', two_factor_callback=my_two_factor_function) -Then each the API tells github3.py it requires a Two Factor Authentication +Then each time the API tells github3.py it requires a Two Factor Authentication code, github3.py will call ``my_two_factor_function`` which prompt you for it. diff --git a/docs/github.rst b/docs/github.rst index 0601d7269..5555cb80c 100644 --- a/docs/github.rst +++ b/docs/github.rst @@ -14,7 +14,7 @@ you're looking for anonymous functions, you're most likely looking for the Examples -------- -Examples utilizing this object can be found here_. +Examples utilizing this object can be found :ref:`here `. GitHub Object ------------- @@ -22,13 +22,11 @@ GitHub Object .. autoclass:: GitHub :inherited-members: -.. links -.. _here: examples/githubex.html GitHubEnterprise Object ----------------------- -This has all of the same attributes ass the :class:`GitHub ` object so +This has all of the same attributes as the :class:`GitHub ` object so for brevity's sake, I'm not listing all of it's inherited members. .. autoclass:: GitHubEnterprise diff --git a/docs/index.rst b/docs/index.rst index cfb3f5f5e..4b8829aad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,17 +16,17 @@ Let's get information about a user:: gh = login('sigmavirus24', password='') - sigmavirus24 = gh.user() + sigmavirus24 = gh.me() # print(sigmavirus24.name) # Ian Cordasco print(sigmavirus24.login) # sigmavirus24 - print(sigmavirus24.followers) + print(sigmavirus24.followers_count) # 4 - for f in gh.iter_followers(): + for f in gh.followers(): print(str(f)) kennethreitz = gh.user('kennethreitz') @@ -34,9 +34,9 @@ Let's get information about a user:: print(kennethreitz.name) print(kennethreitz.login) - print(kennethreitz.followers) + print(kennethreitz.followers_count) - followers = [str(f) for f in gh.iter_followers('kennethreitz')] + followers = [str(f) for f in gh.followers('kennethreitz')] More Examples ~~~~~~~~~~~~~ @@ -111,19 +111,19 @@ Dependencies ~~~~~~~~~~~~ - requests_ by Kenneth Reitz -- uritemplate.py_ by Ian Cordasco +- uritemplate_ by Ian Cordasco .. _requests: https://github.com/kennethreitz/requests -.. _uritemplate.py: https://github.com/sigmavirus24/uritemplate +.. _uritemplate: https://github.com/sigmavirus24/uritemplate 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 +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. .. links @@ -137,27 +137,44 @@ In order of importance: Documentation - I know I'm not the best at writing documentation so if you want to clarify + 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 + 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:: - mkdir -p /path/to/virtualenv/github3.py - cd /path/to/virtualenv/github3.py - virtualenv . - cd /path/to/github3.py_repo/ - pip install -r dev-requirements.txt - # Or you could run make test-deps - make tests + 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 .. toctree:: @@ -173,57 +190,66 @@ Contact .. _sigmavirus24: https://twitter.com/sigmavirus24 -.. include:: ../HISTORY.rst +Latest Version's Changes +------------------------ + +.. include:: ../LATEST_VERSION_NOTES.rst + +The full history of the project is available as well. + +.. toctree:: + + project_changelog Testimonials ------------ .. raw:: html -