Skip to content

Commit 5d7ee35

Browse files
copituxcopitux
committed
Complete services.repos doc
Also add Mimetypes doc
1 parent 614ed5b commit 5d7ee35

File tree

17 files changed

+289
-79
lines changed

17 files changed

+289
-79
lines changed

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ You must apologize my English level. I'm trying to do my best
3838
installation
3939
github
4040
services
41-
resources
4241
result
42+
resources
4343

4444
.. _Github API v3 documentation: http://developer.github.com

‎docs/repos.rst‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@ Some request always need ``user`` and ``repo`` parameters, both, to identify
2222
a `repository`. Because there are a lot of requests which need that parameters,
2323
you can :ref:`config each service` with ``user`` and ``repo`` globally.
2424

25-
So several requests follow a simple precedence ``user_in_arg > user_in_config``
25+
So several requests follow a simple precedence
26+
``user_in_arg > user_in_config | repo_in_arg > repo_in_config``
2627

2728
You can see it better with an example: ::
2829

@@ -127,10 +128,16 @@ Watchers
127128
.. autoclass:: pygithub3.services.repos.Watchers
128129
:members:
129130

131+
.. _Hooks service:
132+
133+
Hooks
134+
---------
135+
130136
.. _github repos doc: http://developer.github.com/v3/repos
131-
.. _github collaborators doc: http://developer.github.com/v3/repos
132-
.. _github commits doc: http://developer.github.com/v3/repos
133-
.. _github downloads doc: http://developer.github.com/v3/repos
134-
.. _github forks doc: http://developer.github.com/v3/repos
135-
.. _github watching doc: http://developer.github.com/v3/repos
136-
.. _github hooks doc: http://developer.github.com/v3/repos
137+
.. _github collaborators doc: http://developer.github.com/v3/repos/collaborators
138+
.. _github commits doc: http://developer.github.com/v3/repos/commits
139+
.. _github downloads doc: http://developer.github.com/v3/repos/downloads
140+
.. _github forks doc: http://developer.github.com/v3/repos/forks
141+
.. _github keys doc: http://developer.github.com/v3/repos/keys
142+
.. _github watching doc: http://developer.github.com/v3/repos/watching
143+
.. _github hooks doc: http://developer.github.com/v3/repos/hooks

‎docs/result.rst‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,31 +7,3 @@ Some requests returns multiple :doc:`resources`, for that reason the
77

88
.. autoclass:: pygithub3.core.result.Result
99

10-
You have several ways to consume it
11-
12-
1. Iterating over the result::
13-
14-
result = some_request()
15-
for page in result:
16-
for resource in page:
17-
print resource
18-
19-
2. With a generator::
20-
21-
result = some_request()
22-
for resource in result.iterator():
23-
print resource
24-
25-
3. As a list::
26-
27-
result = some_request()
28-
print result.all()
29-
30-
4. Also you can request some page manually
31-
32-
.. autoattribute:: pygithub3.core.result.Result.pages
33-
.. automethod:: pygithub3.core.result.Result.get_page
34-
35-
Each ``Page`` is an iterator and contains resources
36-
37-

‎docs/services.rst‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,16 @@ service has her client which is configurated with this variables).
4040
.. autoclass:: pygithub3.services.base.Service
4141
:members:
4242

43-
.. _mimetypes:
43+
.. _mimetypes-section:
4444

4545
MimeTypes
4646
----------
4747

48+
Some services supports `mimetypes`_
49+
50+
With them the :doc:`resources` will have ``body``, ``body_text``, ``body_html``
51+
attributes or all of them.
52+
4853
.. autoclass:: pygithub3.services.base.MimeTypeMixin
4954
:members:
5055

@@ -56,3 +61,5 @@ List of services
5661

5762
users
5863
repos
64+
65+
.. _mimetypes: http://developer.github.com/v3/mime

‎pygithub3/core/result.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,38 @@ def __repr__(self):
137137
class Result(object):
138138
"""
139139
Result is a very lazy paginator. It only do a real request when is needed
140+
141+
You have several ways to consume it
142+
143+
#. Iterating over the result::
144+
145+
result = some_request()
146+
for page in result:
147+
for resource in page:
148+
print resource
149+
150+
#. With a generator::
151+
152+
result = some_request()
153+
for resource in result.iterator():
154+
print resource
155+
156+
#. As a list::
157+
158+
result = some_request()
159+
print result.all()
160+
161+
#. Also you can request some page manually
162+
163+
.. autoattribute:: pygithub3.core.result.Result.pages
164+
.. automethod:: pygithub3.core.result.Result.get_page
165+
166+
Each ``Page`` is an iterator and contains resources::
167+
168+
result = some_request()
169+
assert result.pages > 3
170+
page3 = result.get_page(3)
171+
page3_resources = list(page3)
140172
"""
141173

142174
def __init__(self, client, request, **kwargs):

‎pygithub3/services/base.py‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -136,14 +136,9 @@ def _get_result(self, request, **kwargs):
136136

137137
class MimeTypeMixin(object):
138138
"""
139-
Mimetype support to Services that inherit this Mixin
139+
Mimetype support to Services
140140
141141
Adds 4 public functions to service:
142-
143-
1. set_raw_mimetype
144-
2. set_text_mimetype
145-
3. set_html_mimetype
146-
4. set_full_mimetype
147142
"""
148143

149144
VERSION = 'beta'
@@ -152,16 +147,21 @@ def __set_mimetype(self, mimetype):
152147
self.mimetype = 'application/vnd.github.%s.%s+json' % (
153148
self.VERSION, mimetype)
154149

155-
def set_raw_mimetype(self):
150+
def set_raw(self):
151+
""" Resource will have ``body`` attribute """
156152
self.__set_mimetype('raw')
157153

158-
def set_text_mimetype(self):
154+
def set_text(self):
155+
""" Resource will have ``body_text`` attribute """
159156
self.__set_mimetype('text')
160157

161-
def set_html_mimetype(self):
158+
def set_html(self):
159+
""" Resource will have ``body_html`` attribute """
162160
self.__set_mimetype('html')
163161

164-
def set_full_mimetype(self):
162+
def set_full(self):
163+
""" Resource will have ``body`` ``body_text`` and ``body_html``
164+
attributes """
165165
self.__set_mimetype('full')
166166

167167
def _get_mimetype_as_header(self):

‎pygithub3/services/repos/__init__.py‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ def list(self, user=None, type='all'):
3333
authenticated user's repositories
3434
3535
.. warning::
36-
3736
If you aren't authenticated and call without user, it returns 403
3837
3938
::
@@ -87,7 +86,6 @@ def get(self, user=None, repo=None):
8786
:param str repo: Repository
8887
8988
.. note::
90-
9189
Remember :ref:`config precedence`
9290
"""
9391
request = self.make_request('repos.get', user=user, repo=repo)
@@ -101,11 +99,9 @@ def update(self, data, user=None, repo=None):
10199
:param str repo: Repository
102100
103101
.. note::
104-
105102
Remember :ref:`config precedence`
106103
107104
.. warning::
108-
109105
You must be authenticated
110106
111107
::
@@ -130,7 +126,6 @@ def list_contributors(self, user=None, repo=None):
130126
:returns: A :doc:`result`
131127
132128
.. note::
133-
134129
Remember :ref:`config precedence`
135130
"""
136131
return self.__list_contributors(user, repo)
@@ -148,7 +143,6 @@ def list_languages(self, user=None, repo=None):
148143
:returns: A :doc:`result`
149144
150145
.. note::
151-
152146
Remember :ref:`config precedence`
153147
"""
154148
request = self.make_request('repos.list_languages',
@@ -163,7 +157,6 @@ def list_teams(self, user=None, repo=None):
163157
:returns: A :doc:`result`
164158
165159
.. note::
166-
167160
Remember :ref:`config precedence`
168161
"""
169162
request = self.make_request('repos.list_teams', user=user, repo=repo)
@@ -177,7 +170,6 @@ def list_tags(self, user=None, repo=None):
177170
:returns: A :doc:`result`
178171
179172
.. note::
180-
181173
Remember :ref:`config precedence`
182174
"""
183175
request = self.make_request('repos.list_tags', user=user, repo=repo)
@@ -191,7 +183,6 @@ def list_branches(self, user=None, repo=None):
191183
:returns: A :doc:`result`
192184
193185
.. note::
194-
195186
Remember :ref:`config precedence`
196187
"""
197188
request = self.make_request('repos.list_branches',

‎pygithub3/services/repos/collaborators.py‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ def list(self, user=None, repo=None):
1616
:returns: A :doc:`result`
1717
1818
.. note::
19-
2019
Remember :ref:`config precedence`
2120
"""
2221
request = self.make_request('repos.collaborators.list',
@@ -31,11 +30,9 @@ def add(self, collaborator, user=None, repo=None):
3130
:param str repo: Repository
3231
3332
.. note::
34-
3533
Remember :ref:`config precedence`
3634
3735
.. warning::
38-
3936
You must be authenticated and have perms in repository
4037
"""
4138
request = self.make_request('repos.collaborators.add',
@@ -50,7 +47,6 @@ def is_collaborator(self, collaborator, user=None, repo=None):
5047
:param str repo: Repository
5148
5249
.. note::
53-
5450
Remember :ref:`config precedence`
5551
"""
5652
request = self.make_request('repos.collaborators.is_collaborator',
@@ -65,11 +61,9 @@ def delete(self, collaborator, user=None, repo=None):
6561
:param str repo: Repository
6662
6763
.. note::
68-
6964
Remember :ref:`config precedence`
7065
7166
.. warning::
72-
7367
You must be authenticated and have perms in repository
7468
"""
7569
request = self.make_request('repos.collaborators.delete',

‎pygithub3/services/repos/commits.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ def get(self, sha, user=None, repo=None):
2525
:param str repo: Repository
2626
2727
.. note::
28-
2928
Remember :ref:`config precedence`
3029
"""
3130
request = self.make_request('repos.commits.get',
@@ -38,9 +37,9 @@ def list_comments(self, sha=None, user=None, repo=None):
3837
:param str sha: Commit's sha
3938
:param str user: Username
4039
:param str repo: Repository
40+
:returns: A :doc:`result`
4141
4242
.. note::
43-
4443
Remember :ref:`config precedence`
4544
4645
If you call it without ``sha``, get all commit's comments of a
@@ -64,9 +63,11 @@ def create_comment(self, data, sha, user=None, repo=None):
6463
:param str repo: Repository
6564
6665
.. note::
67-
6866
Remember :ref:`config precedence`
6967
68+
.. warning::
69+
You must be authenticated
70+
7071
::
7172
7273
data = {
@@ -91,7 +92,6 @@ def get_comment(self, cid, user=None, repo=None):
9192
:param str repo: Repository
9293
9394
.. note::
94-
9595
Remember :ref:`config precedence`
9696
"""
9797
request = self.make_request('repos.commits.get_comment',
@@ -107,9 +107,11 @@ def update_comment(self, data, cid, user=None, repo=None):
107107
:param str repo: Repository
108108
109109
.. note::
110-
111110
Remember :ref:`config precedence`
112111
112+
.. warning::
113+
You must be authenticated
114+
113115
::
114116
115117
commits_service.update_comment(dict(body='nice change'), 42,
@@ -128,7 +130,6 @@ def compare(self, base, head, user=None, repo=None):
128130
:param str repo: Repository
129131
130132
.. note::
131-
132133
Remember :ref:`config precedence`
133134
134135
::
@@ -148,7 +149,6 @@ def delete_comment(self, cid, user=None, repo=None):
148149
:param str repo: Repository
149150
150151
.. note::
151-
152152
Remember :ref:`config precedence`
153153
"""
154154
request = self.make_request('repos.commits.delete_comment',

0 commit comments

Comments
 (0)