@@ -51,13 +51,26 @@ class GitlabAuthenticationError(Exception):
5151
5252
5353class Gitlab (object ):
54+ """Represents a GitLab server connection"""
5455def __init__ (self ,url ,private_token = None ,email = None ,password = None ):
56+ """Stores informations about the server
57+
58+ url: the URL of the Gitlab server
59+ private_token: the user private token
60+ email: the user email/login
61+ password: the user password (associated with email)
62+ """
5563self .url = '%s/api/v3' % url
5664self .private_token = private_token
5765self .email = email
5866self .password = password
5967
6068def auth (self ):
69+ """Perform an authentication using either the private token, or the
70+ email/password pair.
71+
72+ The user attribute will hold a CurrentUser object on success.
73+ """
6174r = False
6275if self .private_token :
6376r = self .token_auth ()
@@ -86,12 +99,15 @@ def token_auth(self):
8699return False
87100
88101def setUrl (self ,url ):
102+ """Updates the gitlab URL"""
89103self .url = '%s/api/v3' % url
90104
91105def setToken (self ,token ):
106+ """Set the private token for authentication"""
92107self .private_token = token
93108
94109def setCredentials (self ,email ,password ):
110+ """Set the email/login and password for authentication"""
95111self .email = email
96112self .password = password
97113
@@ -226,15 +242,49 @@ def getListOrObject(self, cls, id, **kwargs):
226242return cls (self ,id ,** kwargs )
227243
228244def Project (self ,id = None ):
245+ """Creates/gets/lists project(s) known by the GitLab server.
246+
247+ If id is None, returns a list of projects.
248+
249+ If id is an integer, returns the matching project (or raise a
250+ GitlabGetError if not found)
251+
252+ If id is a dict, create a new object using attributes provided. The
253+ object is NOT saved on the server. Use the save() method on the object
254+ to write it on the server.
255+ """
229256return self .getListOrObject (Project ,id )
230257
231258def Group (self ,id = None ):
259+ """Creates/gets/lists groups(s) known by the GitLab server.
260+
261+ If id is None, returns a list of projects.
262+
263+ If id is an integer, returns the matching project (or raise a
264+ GitlabGetError if not found)
265+
266+ If id is a dict, create a new object using attributes provided. The
267+ object is NOT saved on the server. Use the save() method on the object
268+ to write it on the server.
269+ """
232270return self .getListOrObject (Group ,id )
233271
234- def Issue (self ,id = None ):
235- return self .getListOrObject (Issue ,id )
272+ def Issue (self ):
273+ """Lists issues(s) known by the GitLab server."""
274+ return self .getListOrObject (Issue ,None )
236275
237276def User (self ,id = None ):
277+ """Creates/gets/lists users(s) known by the GitLab server.
278+
279+ If id is None, returns a list of projects.
280+
281+ If id is an integer, returns the matching project (or raise a
282+ GitlabGetError if not found)
283+
284+ If id is a dict, create a new object using attributes provided. The
285+ object is NOT saved on the server. Use the save() method on the object
286+ to write it on the server.
287+ """
238288return self .getListOrObject (User ,id )
239289
240290
