Skip to content

Commit 614ed5b

Browse files
copituxcopitux
committed
WIP on services.repos doc
+services.repos.collaborators doc +services.repos.commits doc
1 parent 397238b commit 614ed5b

File tree

5 files changed

+190
-12
lines changed

5 files changed

+190
-12
lines changed

‎docs/repos.rst‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,20 +82,23 @@ Collaborators
8282
--------------
8383

8484
.. autoclass:: pygithub3.services.repos.Collaborators
85+
:members:
8586

8687
.. _Commits service:
8788

8889
Commits
8990
----------
9091

9192
.. autoclass:: pygithub3.services.repos.Commits
93+
:members:
9294

9395
.. _Downloads service:
9496

9597
Downloads
9698
------------
9799

98100
.. autoclass:: pygithub3.services.repos.Downloads
101+
:members:
99102

100103

101104
.. _Forks service:
@@ -104,6 +107,7 @@ Forks
104107
---------
105108

106109
.. autoclass:: pygithub3.services.repos.Forks
110+
:members:
107111

108112

109113
.. _RepoKeys service:
@@ -112,6 +116,7 @@ Keys
112116
----------
113117

114118
.. autoclass:: pygithub3.services.repos.Keys
119+
:members:
115120

116121

117122
.. _Watchers service:
@@ -120,5 +125,12 @@ Watchers
120125
---------
121126

122127
.. autoclass:: pygithub3.services.repos.Watchers
128+
:members:
123129

124-
.. _github repo doc: http://developer.github.com/v3/repos
130+
.. _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

‎docs/services.rst‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Services
55
start
66

77
Overview
8-
..........
8+
----------
99

1010
You can access to the API requests through the different services.
1111

@@ -28,7 +28,7 @@ from the rest**.
2828
.. _config each service:
2929

3030
Config each service
31-
.....................................
31+
----------------------
3232

3333
Each service can be configurated with some variables (behind the scenes, each
3434
service has her client which is configurated with this variables).
@@ -40,8 +40,16 @@ service has her client which is configurated with this variables).
4040
.. autoclass:: pygithub3.services.base.Service
4141
:members:
4242

43+
.. _mimetypes:
44+
45+
MimeTypes
46+
----------
47+
48+
.. autoclass:: pygithub3.services.base.MimeTypeMixin
49+
:members:
50+
4351
List of services
44-
..................
52+
-------------------
4553

4654
.. toctree::
4755
:maxdepth: 2

‎pygithub3/services/repos/__init__.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def list(self, user=None, type='all'):
2626
""" Get user's repositories
2727
2828
:param str user: Username
29-
:param str type: Filter by type (optional). See `github repo doc`_
29+
:param str type: Filter by type (optional). See `github repos doc`_
3030
:returns: A :doc:`result`
3131
3232
If you call it without user and you are authenticated, get the
@@ -48,7 +48,7 @@ def list_by_org(self, org, type='all'):
4848
""" Get organization's repositories
4949
5050
:param str org: Organization name
51-
:param str type: Filter by type (optional). See `github repo doc`_
51+
:param str type: Filter by type (optional). See `github repos doc`_
5252
:returns: A :doc:`result`
5353
5454
::
@@ -61,7 +61,7 @@ def list_by_org(self, org, type='all'):
6161
def create(self, data, in_org=None):
6262
""" Create a new repository
6363
64-
:param dict data: Input. See `github repo doc`_
64+
:param dict data: Input. See `github repos doc`_
6565
:param str in_org: Organization where create the repository (optional)
6666
6767
.. warning::
@@ -96,7 +96,7 @@ def get(self, user=None, repo=None):
9696
def update(self, data, user=None, repo=None):
9797
""" Update a single repository
9898
99-
:param dict data: Input. See `github repo doc`_
99+
:param dict data: Input. See `github repos doc`_
100100
:param str user: Username
101101
:param str repo: Repository
102102

‎pygithub3/services/repos/collaborators.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,73 @@
55

66

77
class Collaborators(Service):
8+
""" Consume `Repo Collaborators API
9+
<http://developer.github.com/v3/repos/collaborators>`_ """
810

911
def list(self, user=None, repo=None):
12+
""" Get repository's collaborators
13+
14+
:param str user: Username
15+
:param str repo: Repository
16+
:returns: A :doc:`result`
17+
18+
.. note::
19+
20+
Remember :ref:`config precedence`
21+
"""
1022
request = self.make_request('repos.collaborators.list',
1123
user=user, repo=repo)
1224
return self._get_result(request)
1325

1426
def add(self, collaborator, user=None, repo=None):
27+
""" Add collaborator to a repository
28+
29+
:param str collaborator: Collaborator's username
30+
:param str user: Username
31+
:param str repo: Repository
32+
33+
.. note::
34+
35+
Remember :ref:`config precedence`
36+
37+
.. warning::
38+
39+
You must be authenticated and have perms in repository
40+
"""
1541
request = self.make_request('repos.collaborators.add',
1642
collaborator=collaborator, user=user, repo=repo)
1743
return self._put(request)
1844

1945
def is_collaborator(self, collaborator, user=None, repo=None):
46+
""" Check if a user is collaborator on repository
47+
48+
:param str collaborator: Collaborator's username
49+
:param str user: Username
50+
:param str repo: Repository
51+
52+
.. note::
53+
54+
Remember :ref:`config precedence`
55+
"""
2056
request = self.make_request('repos.collaborators.is_collaborator',
2157
collaborator=collaborator, user=user, repo=repo)
2258
return self._bool(request)
2359

2460
def delete(self, collaborator, user=None, repo=None):
61+
""" Remove collaborator from repository
62+
63+
:param str collaborator: Collaborator's username
64+
:param str user: Username
65+
:param str repo: Repository
66+
67+
.. note::
68+
69+
Remember :ref:`config precedence`
70+
71+
.. warning::
72+
73+
You must be authenticated and have perms in repository
74+
"""
2575
request = self.make_request('repos.collaborators.delete',
2676
collaborator=collaborator, user=user, repo=repo)
2777
self._delete(request)

‎pygithub3/services/repos/commits.py‎

Lines changed: 112 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,44 +5,152 @@
55

66

77
class Commits(Service, MimeTypeMixin):
8+
""" Consume `Commits API
9+
<http://developer.github.com/v3/repos/commits>`_
810
9-
""" TODO: Pagination structure differs from usual
10-
def list(self, user=None, repo=None, sha='', path=''):
11-
request = self.make_request('repos.commits.list', user=user, repo=repo)
12-
return self._get_result(request, sha=sha, path=path)
11+
.. note::
12+
This service support :ref:`mimetypes` configuration
1313
"""
1414

15+
#TODO: Pagination structure differs from usual
16+
#def list(self, user=None, repo=None, sha='', path=''):
17+
#request = self.make_request('repos.commits.list', user=user, repo=repo)
18+
#return self._get_result(request, sha=sha, path=path)
19+
1520
def get(self, sha, user=None, repo=None):
21+
""" Get a single commit
22+
23+
:param str sha: Commit's sha
24+
:param str user: Username
25+
:param str repo: Repository
26+
27+
.. note::
28+
29+
Remember :ref:`config precedence`
30+
"""
1631
request = self.make_request('repos.commits.get',
1732
sha=sha, user=user, repo=repo)
1833
return self._get(request)
1934

2035
def list_comments(self, sha=None, user=None, repo=None):
36+
""" Get commit's comments
37+
38+
:param str sha: Commit's sha
39+
:param str user: Username
40+
:param str repo: Repository
41+
42+
.. note::
43+
44+
Remember :ref:`config precedence`
45+
46+
If you call it without ``sha``, get all commit's comments of a
47+
repository
48+
::
49+
50+
commits_service.list_comments('6dcb09', user='octocat',
51+
repo='oct_repo')
52+
commits_service.list_comments(user='octocat', repo='oct_repo')
53+
"""
2154
request = self.make_request('repos.commits.list_comments',
2255
sha=sha, user=user, repo=repo)
2356
return self._get_result(request, **self._get_mimetype_as_header())
2457

2558
def create_comment(self, data, sha, user=None, repo=None):
59+
""" Create a commit comment
60+
61+
:param dict data: Input. See `github commits doc`_
62+
:param str sha: Commit's sha
63+
:param str user: Username
64+
:param str repo: Repository
65+
66+
.. note::
67+
68+
Remember :ref:`config precedence`
69+
70+
::
71+
72+
data = {
73+
"body": "Nice change",
74+
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
75+
"line": 1,
76+
"path": "file1.txt",
77+
"position": 4
78+
}
79+
commits_service.create_comment(data, '6dcb09', user='octocat',
80+
repo='oct_repo')
81+
"""
2682
request = self.make_request('repos.commits.create_comment',
2783
sha=sha, user=user, repo=repo, body=data)
2884
return self._post(request, **self._get_mimetype_as_header())
2985

3086
def get_comment(self, cid, user=None, repo=None):
87+
""" Get a single commit comment
88+
89+
:param int cid: Commit comment id
90+
:param str user: Username
91+
:param str repo: Repository
92+
93+
.. note::
94+
95+
Remember :ref:`config precedence`
96+
"""
3197
request = self.make_request('repos.commits.get_comment',
3298
comment_id=cid, user=user, repo=repo)
3399
return self._get(request, **self._get_mimetype_as_header())
34100

35101
def update_comment(self, data, cid, user=None, repo=None):
102+
""" Update a single commit comment
103+
104+
:param dict data: Input. See `github commits doc`_
105+
:param int cid: Commit comment id
106+
:param str user: Username
107+
:param str repo: Repository
108+
109+
.. note::
110+
111+
Remember :ref:`config precedence`
112+
113+
::
114+
115+
commits_service.update_comment(dict(body='nice change'), 42,
116+
user='octocat', repo='oct_repo')
117+
"""
36118
request = self.make_request('repos.commits.update_comment',
37119
comment_id=cid, user=user, repo=repo, body=data)
38120
return self._patch(request, **self._get_mimetype_as_header())
39121

40122
def compare(self, base, head, user=None, repo=None):
123+
""" Compare two commits
124+
125+
:param str base: Base commit sha
126+
:param str head: Head commit sha
127+
:param str user: Username
128+
:param str repo: Repository
129+
130+
.. note::
131+
132+
Remember :ref:`config precedence`
133+
134+
::
135+
136+
commits_service.compare('6dcb09', 'master', user='octocat',
137+
repo='oct_repo')
138+
"""
41139
request = self.make_request('repos.commits.compare',
42140
base=base, head=head, user=user, repo=repo)
43141
return self._get(request)
44142

45143
def delete_comment(self, cid, user=None, repo=None):
144+
""" Delete a single commit comment
145+
146+
:param int cid: Commit comment id
147+
:param str user: Username
148+
:param str repo: Repository
149+
150+
.. note::
151+
152+
Remember :ref:`config precedence`
153+
"""
46154
request = self.make_request('repos.commits.delete_comment',
47155
comment_id=cid, user=user, repo=repo)
48156
self._delete(request)

0 commit comments

Comments
 (0)