diff options
Diffstat (limited to 'pygithub3')
| -rw-r--r-- | pygithub3/core/result.py | 32 | ||||
| -rw-r--r-- | pygithub3/services/base.py | 20 | ||||
| -rw-r--r-- | pygithub3/services/repos/__init__.py | 9 | ||||
| -rw-r--r-- | pygithub3/services/repos/collaborators.py | 6 | ||||
| -rw-r--r-- | pygithub3/services/repos/commits.py | 14 | ||||
| -rw-r--r-- | pygithub3/services/repos/downloads.py | 58 | ||||
| -rw-r--r-- | pygithub3/services/repos/forks.py | 37 | ||||
| -rw-r--r-- | pygithub3/services/repos/keys.py | 64 | ||||
| -rw-r--r-- | pygithub3/services/repos/watchers.py | 60 | ||||
| -rw-r--r-- | pygithub3/services/users/__init__.py | 1 | ||||
| -rw-r--r-- | pygithub3/services/users/emails.py | 2 | ||||
| -rw-r--r-- | pygithub3/services/users/followers.py | 4 | ||||
| -rw-r--r-- | pygithub3/services/users/keys.py | 1 |
13 files changed, 266 insertions, 42 deletions
diff --git a/pygithub3/core/result.py b/pygithub3/core/result.py index 9e69e7d..5a2aa80 100644 --- a/pygithub3/core/result.py +++ b/pygithub3/core/result.py @@ -137,6 +137,38 @@ class Page(object): class Result(object): """ Result is a very lazy paginator. It only do a real request when is needed + + You have several ways to consume it + + #. Iterating over the result:: + + result = some_request() + for page in result: + for resource in page: + print resource + + #. With a generator:: + + result = some_request() + for resource in result.iterator(): + print resource + + #. As a list:: + + result = some_request() + print result.all() + + #. Also you can request some page manually + + .. autoattribute:: pygithub3.core.result.Result.pages + .. automethod:: pygithub3.core.result.Result.get_page + + Each ``Page`` is an iterator and contains resources:: + + result = some_request() + assert result.pages > 3 + page3 = result.get_page(3) + page3_resources = list(page3) """ def __init__(self, client, request, **kwargs): diff --git a/pygithub3/services/base.py b/pygithub3/services/base.py index 7fb6133..8602150 100644 --- a/pygithub3/services/base.py +++ b/pygithub3/services/base.py @@ -136,14 +136,9 @@ class Service(object): class MimeTypeMixin(object): """ - Mimetype support to Services that inherit this Mixin + Mimetype support to Services Adds 4 public functions to service: - - 1. set_raw_mimetype - 2. set_text_mimetype - 3. set_html_mimetype - 4. set_full_mimetype """ VERSION = 'beta' @@ -152,16 +147,21 @@ class MimeTypeMixin(object): self.mimetype = 'application/vnd.github.%s.%s+json' % ( self.VERSION, mimetype) - def set_raw_mimetype(self): + def set_raw(self): + """ Resource will have ``body`` attribute """ self.__set_mimetype('raw') - def set_text_mimetype(self): + def set_text(self): + """ Resource will have ``body_text`` attribute """ self.__set_mimetype('text') - def set_html_mimetype(self): + def set_html(self): + """ Resource will have ``body_html`` attribute """ self.__set_mimetype('html') - def set_full_mimetype(self): + def set_full(self): + """ Resource will have ``body`` ``body_text`` and ``body_html`` + attributes """ self.__set_mimetype('full') def _get_mimetype_as_header(self): diff --git a/pygithub3/services/repos/__init__.py b/pygithub3/services/repos/__init__.py index e1ed1d8..484dd49 100644 --- a/pygithub3/services/repos/__init__.py +++ b/pygithub3/services/repos/__init__.py @@ -33,7 +33,6 @@ class Repos(Service): authenticated user's repositories .. warning:: - If you aren't authenticated and call without user, it returns 403 :: @@ -87,7 +86,6 @@ class Repos(Service): :param str repo: Repository .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.get', user=user, repo=repo) @@ -101,11 +99,9 @@ class Repos(Service): :param str repo: Repository .. note:: - Remember :ref:`config precedence` .. warning:: - You must be authenticated :: @@ -130,7 +126,6 @@ class Repos(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ return self.__list_contributors(user, repo) @@ -148,7 +143,6 @@ class Repos(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.list_languages', @@ -163,7 +157,6 @@ class Repos(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.list_teams', user=user, repo=repo) @@ -177,7 +170,6 @@ class Repos(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.list_tags', user=user, repo=repo) @@ -191,7 +183,6 @@ class Repos(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.list_branches', diff --git a/pygithub3/services/repos/collaborators.py b/pygithub3/services/repos/collaborators.py index 5f0703a..f80a406 100644 --- a/pygithub3/services/repos/collaborators.py +++ b/pygithub3/services/repos/collaborators.py @@ -16,7 +16,6 @@ class Collaborators(Service): :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.collaborators.list', @@ -31,11 +30,9 @@ class Collaborators(Service): :param str repo: Repository .. note:: - Remember :ref:`config precedence` .. warning:: - You must be authenticated and have perms in repository """ request = self.make_request('repos.collaborators.add', @@ -50,7 +47,6 @@ class Collaborators(Service): :param str repo: Repository .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.collaborators.is_collaborator', @@ -65,11 +61,9 @@ class Collaborators(Service): :param str repo: Repository .. note:: - Remember :ref:`config precedence` .. warning:: - You must be authenticated and have perms in repository """ request = self.make_request('repos.collaborators.delete', diff --git a/pygithub3/services/repos/commits.py b/pygithub3/services/repos/commits.py index 23e6842..8eec3e7 100644 --- a/pygithub3/services/repos/commits.py +++ b/pygithub3/services/repos/commits.py @@ -25,7 +25,6 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.commits.get', @@ -38,9 +37,9 @@ class Commits(Service, MimeTypeMixin): :param str sha: Commit's sha :param str user: Username :param str repo: Repository + :returns: A :doc:`result` .. note:: - Remember :ref:`config precedence` If you call it without ``sha``, get all commit's comments of a @@ -64,9 +63,11 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` + .. warning:: + You must be authenticated + :: data = { @@ -91,7 +92,6 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.commits.get_comment', @@ -107,9 +107,11 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` + .. warning:: + You must be authenticated + :: commits_service.update_comment(dict(body='nice change'), 42, @@ -128,7 +130,6 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` :: @@ -148,7 +149,6 @@ class Commits(Service, MimeTypeMixin): :param str repo: Repository .. note:: - Remember :ref:`config precedence` """ request = self.make_request('repos.commits.delete_comment', diff --git a/pygithub3/services/repos/downloads.py b/pygithub3/services/repos/downloads.py index c455021..47c7785 100644 --- a/pygithub3/services/repos/downloads.py +++ b/pygithub3/services/repos/downloads.py @@ -7,24 +7,71 @@ from . import Service class Downloads(Service): + """ Consume `Downloads API + <http://developer.github.com/v3/repos/downloads>`_ """ def list(self, user=None, repo=None): + """ Get repository's downloads + + :param str user: Username + :param str repo: Repository + :returns: A :doc:`result` + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.downloads.list', user=user, repo=repo) return self._get_result(request) def get(self, id, user=None, repo=None): + """ Get a single download + + :param int id: Download id + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.downloads.get', id=id, user=user, repo=repo) return self._get(request) def create(self, data, user=None, repo=None): + """ Create a new download + + :param dict data: Input. See `github downloads doc`_ + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + It is a two step process. After you create the download, you must + call the ``upload`` function of ``Download`` resource with + ``file_path`` + + .. warning:: + In `alpha` state + + :: + + # Step 1 + download = downloads_service.create( + dict(name='new_download', size=1130), + user='octocat', repo='oct_repo') + + # Step 2 + download.upload('/home/user/file.ext') + """ request = self.make_request('repos.downloads.create', body=data, user=user, repo=repo) download = self._post(request) # TODO: improve it. e.g Manage all with file desc def upload(file_path): + """ """ body = download.ball_to_upload() body['file'] = (file_path, open(file_path, 'rb')) return requests.post(download.s3_url, files=body) @@ -32,7 +79,16 @@ class Downloads(Service): download.upload = upload return download - def delete(self, id=id, user=None, repo=None): + def delete(self, id, user=None, repo=None): + """ Delete a download + + :param int id: Download id + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.downloads.delete', id=id, user=user, repo=repo) self._delete(request) diff --git a/pygithub3/services/repos/forks.py b/pygithub3/services/repos/forks.py index 09f23c5..df51347 100644 --- a/pygithub3/services/repos/forks.py +++ b/pygithub3/services/repos/forks.py @@ -5,13 +5,48 @@ from . import Service class Forks(Service): + """ Consume `Forks API + <http://developer.github.com/v3/repos/forks>`_ """ def list(self, user=None, repo=None, sort='newest'): + """ Get repository's forks + + :param str user: Username + :param str repo: Repository + :param str sort: Order resources (optional). See `github forks doc`_ + :returns: A :doc:`result` + + .. note:: + Remember :ref:`config precedence` + + :: + + forks_service.list(user='octocat', repo='oct_repo', sort='oldest') + """ request = self.make_request('repos.forks.list', user=user, repo=repo) return self._get_result(request, sort=sort) def create(self, user=None, repo=None, org=None): + """ Fork a repository + + :param str user: Username + :param str repo: Repository + :param str org: Organization name (optional) + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated + + If you call it with ``org``, the repository will be forked into this + organization. + :: + + forks_service.create(user='octocat', repo='oct_repo') + forks_service.create(user='octocat', repo='oct_repo', + org='myorganization' + """ request = self.make_request('repos.forks.create', user=user, repo=repo) - #org = {'org': org} if org else {} org = org and {'org': org} or {} return self._post(request, **org) diff --git a/pygithub3/services/repos/keys.py b/pygithub3/services/repos/keys.py index 24a7cb3..1ade8a1 100644 --- a/pygithub3/services/repos/keys.py +++ b/pygithub3/services/repos/keys.py @@ -5,27 +5,91 @@ from . import Service class Keys(Service): + """ Consume `Deploy keys API + <http://developer.github.com/v3/repos/keys>`_ """ def list(self, user=None, repo=None): + """ Get repository's keys + + :param str user: Username + :param str repo: Repository + :returns: A :doc:`result` + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.keys.list', user=user, repo=repo) return self._get_result(request) def get(self, id, user=None, repo=None): + """ Get a single repository key + + :param int id: Repository key id + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.keys.get', id=id, user=user, repo=repo) return self._get(request) def create(self, data, user=None, repo=None): + """ Create a repository key + + :param dict data: Input. See `github keys doc`_ + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated and have perms in the repository + + :: + + keys_service.create(dict(title='new key', key='ssh-rsa AAA...'), + user='octocat', repo='oct_repo') + """ request = self.make_request('repos.keys.create', body=data, user=user, repo=repo) return self._post(request) def update(self, id, data, user=None, repo=None): + """ Update a repository key + + :param int id: Repository key id + :param dict data: Input. See `github keys doc`_ + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated and have perms in the repository + + :: + + keys_service.update(42, dict(title='new title'), + user='octocat', repo='oct_repo') + """ request = self.make_request('repos.keys.update', id=id, body=data, user=user, repo=repo) return self._patch(request) def delete(self, id, user=None, repo=None): + """ Delete a repository key + + :param int id: Repository key id + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.keys.delete', id=id, user=user, repo=repo) self._delete(request) diff --git a/pygithub3/services/repos/watchers.py b/pygithub3/services/repos/watchers.py index 8598590..7bcede5 100644 --- a/pygithub3/services/repos/watchers.py +++ b/pygithub3/services/repos/watchers.py @@ -5,27 +5,87 @@ from . import Service class Watchers(Service): + """ Consume `Watching API + <http://developer.github.com/v3/repos/watching>`_ """ def list(self, user=None, repo=None): + """ Get repository's watchers + + :param str user: Username + :param str repo: Repository + :returns: A :doc:`result` + + .. note:: + Remember :ref:`config precedence` + """ request = self.make_request('repos.watchers.list', user=user, repo=repo) return self._get_result(request) def list_repos(self, user=None): + """ Get repositories being watched by a user + + :param str user: Username + :returns: A :doc:`result` + + If you call it without user and you are authenticated, get the + repositories being watched by the authenticated user. + + .. warning:: + If you aren't authenticated and call without user, it returns 403 + + :: + + watchers_service.list_repos('copitux') + watchers_service.list_repos() + """ request = self.make_request('repos.watchers.list_repos', user=user) return self._get_result(request) def is_watching(self, user=None, repo=None): + """ Check if authenticated user is watching a repository + + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated + """ request = self.make_request('repos.watchers.is_watching', user=user, repo=repo) return self._bool(request) def watch(self, user=None, repo=None): + """ Watch a repository + + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated + """ request = self.make_request('repos.watchers.watch', user=user, repo=repo) self._put(request) def unwatch(self, user=None, repo=None): + """ Stop watching a repository + + :param str user: Username + :param str repo: Repository + + .. note:: + Remember :ref:`config precedence` + + .. warning:: + You must be authenticated + """ request = self.make_request('repos.watchers.unwatch', user=user, repo=repo) self._delete(request) diff --git a/pygithub3/services/users/__init__.py b/pygithub3/services/users/__init__.py index c448319..29a8e1c 100644 --- a/pygithub3/services/users/__init__.py +++ b/pygithub3/services/users/__init__.py @@ -25,7 +25,6 @@ class User(Service): authenticated user. .. warning:: - If you aren't authenticated and call without user, it returns 403 :: diff --git a/pygithub3/services/users/emails.py b/pygithub3/services/users/emails.py index 084a29c..09f6683 100644 --- a/pygithub3/services/users/emails.py +++ b/pygithub3/services/users/emails.py @@ -8,7 +8,6 @@ class Emails(Service): """ Consume `Emails API <http://developer.github.com/v3/users/emails/>`_ .. warning:: - You must be authenticated for all requests """ @@ -26,7 +25,6 @@ class Emails(Service): :param list emails: Emails to add .. note:: - It rejects non-valid emails :: diff --git a/pygithub3/services/users/followers.py b/pygithub3/services/users/followers.py index d6969e2..5a8176d 100644 --- a/pygithub3/services/users/followers.py +++ b/pygithub3/services/users/followers.py @@ -19,7 +19,6 @@ class Followers(Service): authenticated user's followers .. warning:: - If you aren't authenticated and call without user, it returns 403 :: @@ -40,7 +39,6 @@ class Followers(Service): authenticated user's followings .. warning:: - If you aren't authenticated and call without user, it returns 403 :: @@ -65,7 +63,6 @@ class Followers(Service): :param str user: Username .. warning:: - You must be authenticated """ request = self.make_request('users.followers.follow', user=user) @@ -77,7 +74,6 @@ class Followers(Service): :param str user: Username .. warning:: - You must be authenticated """ request = self.make_request('users.followers.unfollow', user=user) diff --git a/pygithub3/services/users/keys.py b/pygithub3/services/users/keys.py index 996233c..2884881 100644 --- a/pygithub3/services/users/keys.py +++ b/pygithub3/services/users/keys.py @@ -8,7 +8,6 @@ class Keys(Service): """ Consume `Keys API <http://developer.github.com/v3/users/keys/>`_ .. warning:: - You must be authenticated for all requests """ |