Skip to content

Commit 4781fd7

Browse files
author
Gauvain Pocentek
committed
Improve the API documentation.
1 parent 3e8cf4e commit 4781fd7

File tree

5 files changed

+382
-60
lines changed

5 files changed

+382
-60
lines changed

‎docs/api/gitlab.rst‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,31 @@
1-
############################
2-
``gitlab`` API documentation
3-
############################
1+
gitlab package
2+
==============
3+
4+
Module contents
5+
---------------
46

57
.. automodule:: gitlab
68
:members:
79
:undoc-members:
810
:show-inheritance:
11+
:exclude-members: Hook, Project, UserProject, Group, Issue, Team, User,
12+
all_projects, owned_projects, search_projects
13+
14+
gitlab.exceptions module
15+
------------------------
16+
17+
.. automodule:: gitlab.exceptions
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
21+
22+
gitlab.objects module
23+
---------------------
24+
25+
.. automodule:: gitlab.objects
26+
:members:
27+
:undoc-members:
28+
:show-inheritance:
29+
:exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
30+
Label, Member, MergeRequest, Milestone, Note, Project,
31+
Snippet, Tag

‎docs/api/modules.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
.
2-
=
1+
gitlab
2+
======
33

44
.. toctree::
55
:maxdepth: 4

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Contents:
1515
cli
1616
api-usage
1717
upgrade-from-0.10
18-
api/gitlab
18+
api/modules
1919

2020

2121
Indices and tables

‎gitlab/__init__.py‎

Lines changed: 165 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@
1414
#
1515
# You should have received a copy of the GNU Lesser General Public License
1616
# along with this program. If not, see <http://www.gnu.org/licenses/>.
17-
"""Package for interfacing with GitLab-api """
17+
"""Wrapper for the GitLab API."""
18+
1819
from __future__ import print_function
1920
from __future__ import division
2021
from __future__ import absolute_import
@@ -50,16 +51,59 @@ def _sanitize_dict(src):
5051

5152

5253
class Gitlab(object):
53-
"""Represents a GitLab server connection
54+
"""Represents a GitLab server connection.
5455
5556
Args:
56-
url (str): the URL of the Gitlab server
57-
private_token (str): the user private token
58-
email (str): the user email/login
59-
password (str): the user password (associated with email)
60-
ssl_verify (bool): (Passed to requests-library)
61-
timeout (float or tuple(float,float)): (Passed to
62-
requests-library). Timeout to use for requests to gitlab server
57+
url (str): The URL of the GitLab server.
58+
private_token (str): The user private token
59+
email (str): The user email or login.
60+
password (str): The user password (associated with email).
61+
ssl_verify (bool): Whether SSL certificates should be validated.
62+
timeout (float or tuple(float,float)): Timeout to use for requests to
63+
the GitLab server.
64+
65+
Attributes:
66+
user_keys (UserKeyManager): Manager for GitLab users' SSH keys.
67+
users (UserManager): Manager for GitLab users
68+
group_members (GroupMemberManager): Manager for GitLab group members
69+
groups (GroupManager): Manager for GitLab members
70+
hooks (HookManager): Manager for GitLab hooks
71+
issues (IssueManager): Manager for GitLab issues
72+
project_branches (ProjectBranchManager): Manager for GitLab projects
73+
branches
74+
project_commits (ProjectCommitManager): Manager for GitLab projects
75+
commits
76+
project_keys (ProjectKeyManager): Manager for GitLab projects keys
77+
project_events (ProjectEventManager): Manager for GitLab projects
78+
events
79+
project_forks (ProjectForkManager): Manager for GitLab projects forks
80+
project_hooks (ProjectHookManager): Manager for GitLab projects hooks
81+
project_issue_notes (ProjectIssueNoteManager): Manager for GitLab notes
82+
on issues
83+
project_issues (ProjectIssueManager): Manager for GitLab projects
84+
issues
85+
project_members (ProjectMemberManager): Manager for GitLab projects
86+
members
87+
project_notes (ProjectNoteManager): Manager for GitLab projects notes
88+
project_tags (ProjectTagManager): Manager for GitLab projects tags
89+
project_mergerequest_notes (ProjectMergeRequestNoteManager): Manager
90+
for GitLab notes on merge requests
91+
project_mergerequests (ProjectMergeRequestManager): Manager for GitLab
92+
projects merge requests
93+
project_milestones (ProjectMilestoneManager): Manager for GitLab
94+
projects milestones
95+
project_labels (ProjectLabelManager): Manager for GitLab projects
96+
labels
97+
project_files (ProjectFileManager): Manager for GitLab projects files
98+
project_snippet_notes (ProjectSnippetNoteManager): Manager for GitLab
99+
note on snippets
100+
project_snippets (ProjectSnippetManager): Manager for GitLab projects
101+
snippets
102+
user_projects (UserProjectManager): Manager for GitLab projects users
103+
projects (ProjectManager): Manager for GitLab projects
104+
team_members (TeamMemberManager): Manager for GitLab teams members
105+
team_projects (TeamProjectManager): Manager for GitLab teams projects
106+
teams (TeamManager): Manager for GitLab teams
63107
"""
64108

65109
def __init__(self, url, private_token=None,
@@ -71,11 +115,11 @@ def __init__(self, url, private_token=None,
71115
#: Headers that will be used in request to GitLab
72116
self.headers = {}
73117
self.set_token(private_token)
74-
#: the user email
118+
#: The user email
75119
self.email = email
76-
#: the user password (associated with email)
120+
#: The user password (associated with email)
77121
self.password = password
78-
#: (Passed to requests-library)
122+
#: Whether SSL certificates should be validated
79123
self.ssl_verify = ssl_verify
80124

81125
self.user_keys = UserKeyManager(self)
@@ -110,6 +154,18 @@ def __init__(self, url, private_token=None,
110154

111155
@staticmethod
112156
def from_config(gitlab_id=None, config_files=None):
157+
"""Create a Gitlab connection from configuration files.
158+
159+
Args:
160+
gitlab_id (str): ID of the configuration section.
161+
config_files list[str]: List of paths to configuration files.
162+
163+
Returns:
164+
(gitlab.Gitlab): A Gitlab connection.
165+
166+
Raises:
167+
gitlab.config.GitlabDataError: If the configuration is not correct.
168+
"""
113169
config = gitlab.config.GitlabConfigParser(gitlab_id=gitlab_id,
114170
config_files=config_files)
115171
return Gitlab(config.url, private_token=config.token,
@@ -120,28 +176,38 @@ def auth(self):
120176
121177
Uses either the private token, or the email/password pair.
122178
123-
The user attribute will hold a CurrentUser object on success.
179+
The `user` attribute will hold a `gitlab.objects.CurrentUser` object on
180+
success.
124181
"""
125182
if self.private_token:
126183
self.token_auth()
127184
else:
128185
self.credentials_auth()
129186

130187
def credentials_auth(self):
188+
"""Performs an authentication using email/password."""
131189
if not self.email or not self.password:
132190
raise GitlabAuthenticationError("Missing email/password")
133191

134192
data = json.dumps({'email': self.email, 'password': self.password})
135193
r = self._raw_post('/session', data, content_type='application/json')
136194
raise_error_from_response(r, GitlabAuthenticationError, 201)
137195
self.user = CurrentUser(self, r.json())
196+
"""(gitlab.objects.CurrentUser): Object representing the user currently
197+
logged.
198+
"""
138199
self.set_token(self.user.private_token)
139200

140201
def token_auth(self):
202+
"""Performs an authentication using the private token."""
141203
self.user = CurrentUser(self)
142204

143205
def set_url(self, url):
144-
"""Updates the gitlab URL."""
206+
"""Updates the GitLab URL.
207+
208+
Args:
209+
url (str): Base URL of the GitLab server.
210+
"""
145211
self._url = '%s/api/v3' % url
146212

147213
def _construct_url(self, id_, obj, parameters):
@@ -167,15 +233,24 @@ def _create_headers(self, content_type=None, headers={}):
167233
return request_headers
168234

169235
def set_token(self, token):
170-
"""Sets the private token for authentication."""
236+
"""Sets the private token for authentication.
237+
238+
Args:
239+
token (str): The private token.
240+
"""
171241
self.private_token = token if token else None
172242
if token:
173243
self.headers["PRIVATE-TOKEN"] = token
174244
elif "PRIVATE-TOKEN" in self.headers:
175245
del self.headers["PRIVATE-TOKEN"]
176246

177247
def set_credentials(self, email, password):
178-
"""Sets the email/login and password for authentication."""
248+
"""Sets the email/login and password for authentication.
249+
250+
Args:
251+
email (str): The user email or login.
252+
password (str): The user password.
253+
"""
179254
self.email = email
180255
self.password = password
181256

@@ -233,6 +308,19 @@ def _raw_delete(self, path, content_type=None, **kwargs):
233308
"Can't connect to GitLab server (%s)" % self._url)
234309

235310
def list(self, obj_class, **kwargs):
311+
"""Request the listing of GitLab resources.
312+
313+
Args:
314+
obj_class (object): The class of resource to request.
315+
**kwargs: Additional arguments to send to GitLab.
316+
317+
Returns:
318+
list(obj_class): A list of objects of class `obj_class`.
319+
320+
Raises:
321+
GitlabConnectionError: If the server cannot be reached.
322+
GitlabListError: If the server fails to perform the request.
323+
"""
236324
missing = []
237325
for k in itertools.chain(obj_class.requiredUrlAttrs,
238326
obj_class.requiredListAttrs):
@@ -288,6 +376,20 @@ def list(self, obj_class, **kwargs):
288376
return results
289377

290378
def get(self, obj_class, id=None, **kwargs):
379+
"""Request a GitLab resources.
380+
381+
Args:
382+
obj_class (object): The class of resource to request.
383+
id: The object ID.
384+
**kwargs: Additional arguments to send to GitLab.
385+
386+
Returns:
387+
obj_class: An object of class `obj_class`.
388+
389+
Raises:
390+
GitlabConnectionError: If the server cannot be reached.
391+
GitlabGetError: If the server fails to perform the request.
392+
"""
291393
missing = []
292394
for k in itertools.chain(obj_class.requiredUrlAttrs,
293395
obj_class.requiredGetAttrs):
@@ -319,6 +421,19 @@ def get(self, obj_class, id=None, **kwargs):
319421
return r.json()
320422

321423
def delete(self, obj, **kwargs):
424+
"""Delete an object on the GitLab server.
425+
426+
Args:
427+
obj (object): The object to delete.
428+
**kwargs: Additional arguments to send to GitLab.
429+
430+
Returns:
431+
bool: True if the operation succeeds.
432+
433+
Raises:
434+
GitlabConnectionError: If the server cannot be reached.
435+
GitlabDeleteError: If the server fails to perform the request.
436+
"""
322437
params = obj.__dict__.copy()
323438
params.update(kwargs)
324439
missing = []
@@ -353,6 +468,23 @@ def delete(self, obj, **kwargs):
353468
return True
354469

355470
def create(self, obj, **kwargs):
471+
"""Create an object on the GitLab server.
472+
473+
The object class and attributes define the request to be made on the
474+
GitLab server.
475+
476+
Args:
477+
obj (object): The object to create.
478+
**kwargs: Additional arguments to send to GitLab.
479+
480+
Returns:
481+
str: A json representation of the object as returned by the GitLab
482+
server
483+
484+
Raises:
485+
GitlabConnectionError: If the server cannot be reached.
486+
GitlabCreateError: If the server fails to perform the request.
487+
"""
356488
params = obj.__dict__.copy()
357489
params.update(kwargs)
358490
missing = []
@@ -383,6 +515,23 @@ def create(self, obj, **kwargs):
383515
return r.json()
384516

385517
def update(self, obj, **kwargs):
518+
"""Update an object on the GitLab server.
519+
520+
The object class and attributes define the request to be made on the
521+
GitLab server.
522+
523+
Args:
524+
obj (object): The object to create.
525+
**kwargs: Additional arguments to send to GitLab.
526+
527+
Returns:
528+
str: A json representation of the object as returned by the GitLab
529+
server
530+
531+
Raises:
532+
GitlabConnectionError: If the server cannot be reached.
533+
GitlabUpdateError: If the server fails to perform the request.
534+
"""
386535
params = obj.__dict__.copy()
387536
params.update(kwargs)
388537
missing = []

0 commit comments

Comments
 (0)