|
14 | 14 | # |
15 | 15 | # You should have received a copy of the GNU Lesser General Public License |
16 | 16 | # along with this program. If not, see <http://www.gnu.org/licenses/>. |
17 | | - |
| 17 | +""" Module for interfacing with GitLab-api """ |
18 | 18 | from __future__importprint_function,division,absolute_import |
19 | 19 |
|
20 | 20 | importsix |
@@ -124,28 +124,33 @@ def _raiseErrorFromResponse(response, error): |
124 | 124 |
|
125 | 125 |
|
126 | 126 | classGitlab(object): |
127 | | -"""Represents a GitLab server connection""" |
| 127 | +""" Represents a GitLab server connection |
| 128 | +
|
| 129 | + Args: |
| 130 | + url (str): the URL of the Gitlab server |
| 131 | + private_token (str): the user private token |
| 132 | + email (str): the user email/login |
| 133 | + password (str): the user password (associated with email) |
| 134 | + ssl_verify (bool): (Passed to requests-library) |
| 135 | + timeout (float or tuple(float,float)): (Passed to |
| 136 | + requests-library). Timeout to use for requests to gitlab server |
| 137 | + """ |
| 138 | + |
128 | 139 | def__init__(self,url,private_token=None, |
129 | 140 | email=None,password=None,ssl_verify=True,timeout=None): |
130 | | -"""Stores informations about the server |
131 | | -
|
132 | | - url: the URL of the Gitlab server |
133 | | - private_token: the user private token |
134 | | - email: the user email/login |
135 | | - password: the user password (associated with email) |
136 | | - ssl_verify: (Passed to requests-library) |
137 | | - timeout: (Passed to requests-library). Timeout to use for requests to |
138 | | - gitlab server. Float or tuple(Float,Float). |
139 | | - """ |
| 141 | + |
140 | 142 | self._url='%s/api/v3'%url |
| 143 | +#: Timeout to use for requests to gitlab server |
141 | 144 | self.timeout=timeout |
| 145 | +#: Headers that will be used in request to GitLab |
142 | 146 | self.headers= {} |
143 | 147 | self.setToken(private_token) |
| 148 | +#: the user email |
144 | 149 | self.email=email |
| 150 | +#: the user password (associated with email) |
145 | 151 | self.password=password |
| 152 | +#: (Passed to requests-library) |
146 | 153 | self.ssl_verify=ssl_verify |
147 | | -# Gitlab should handle UTF-8 |
148 | | -self.gitlab_encoding='UTF-8' |
149 | 154 |
|
150 | 155 | defauth(self): |
151 | 156 | """Performs an authentication using either the private token, or the |
@@ -497,16 +502,17 @@ def owned_projects(self, **kwargs): |
497 | 502 | returnself._list_projects("/projects/owned",**kwargs) |
498 | 503 |
|
499 | 504 | defGroup(self,id=None,**kwargs): |
500 | | -"""Creates/gets/lists group(s) known by the GitLab server. |
501 | | -
|
502 | | - If id is None, returns a list of groups. |
503 | | -
|
504 | | - If id is an integer, returns the matching group (or raises a |
505 | | - GitlabGetError if not found) |
506 | | -
|
507 | | - If id is a dict, creates a new object using attributes provided. The |
508 | | - object is NOT saved on the server. Use the save() method on the object |
509 | | - to write it on the server. |
| 505 | +"""Creates/gets/lists group(s) known by the GitLab server |
| 506 | +
|
| 507 | + Args: |
| 508 | + id: If id is None, returns a list of groups. |
| 509 | + id: If id is an integer, |
| 510 | + returns the matching group (or raises a GitlabGetError if not |
| 511 | + found). |
| 512 | + id: If id is a dict, creates a new object using attributes |
| 513 | + provided. The object is NOT saved on the server. Use the |
| 514 | + save() method on the object to write it on the server. |
| 515 | + kwargs: Arbitrary keyword arguments |
510 | 516 | """ |
511 | 517 | returnGroup._getListOrObject(self,id,**kwargs) |
512 | 518 |
|
@@ -562,21 +568,43 @@ def _sanitize_dict(src): |
562 | 568 |
|
563 | 569 |
|
564 | 570 | classGitlabObject(object): |
| 571 | +""" Baseclass for all classes that interface with GitLab |
| 572 | +
|
| 573 | + Args: |
| 574 | + gl (gitlab.Gitlab): GitLab server connection |
| 575 | + data: If data is integer or string type, get object from GitLab |
| 576 | + data: If data is dictionary, create new object locally. To save object |
| 577 | + in GitLab, call save-method |
| 578 | + kwargs: Arbitrary keyword arguments |
| 579 | + """ |
| 580 | +#: Url to use in GitLab for this object |
565 | 581 | _url=None |
566 | 582 | _returnClass=None |
567 | 583 | _constructorTypes=None |
568 | | -# Tells if _getListOrObject should return list or object when id is None |
| 584 | +#: Tells if _getListOrObject should return list or object when id is None |
569 | 585 | getListWhenNoId=True |
| 586 | + |
| 587 | +#: Tells if GitLab-api allows retrieving single objects |
570 | 588 | canGet=True |
| 589 | +#: Tells if GitLab-api allows listing of objects |
571 | 590 | canList=True |
| 591 | +#: Tells if GitLab-api allows creation of new objects |
572 | 592 | canCreate=True |
| 593 | +#: Tells if GitLab-api allows updating object |
573 | 594 | canUpdate=True |
| 595 | +#: Tells if GitLab-api allows deleting object |
574 | 596 | canDelete=True |
| 597 | +#: Attributes that are required for constructing url |
575 | 598 | requiredUrlAttrs= [] |
| 599 | +#: Attributes that are required when retrieving list of objects |
576 | 600 | requiredListAttrs= [] |
| 601 | +#: Attributes that are required when retrieving single object |
577 | 602 | requiredGetAttrs= [] |
| 603 | +#: Attributes that are required when deleting object |
578 | 604 | requiredDeleteAttrs= [] |
| 605 | +#: Attributes that are required when creating a new object |
579 | 606 | requiredCreateAttrs= [] |
| 607 | +#: Attributes that are optional when creating a new object |
580 | 608 | optionalCreateAttrs= [] |
581 | 609 | idAttr='id' |
582 | 610 | shortPrintAttr=None |
@@ -1199,6 +1227,19 @@ def archive(self, sha=None, **kwargs): |
1199 | 1227 | _raiseErrorFromResponse(r,GitlabGetError) |
1200 | 1228 |
|
1201 | 1229 | defcreate_file(self,path,branch,content,message,**kwargs): |
| 1230 | +""" Creates file in project repository |
| 1231 | +
|
| 1232 | + Args: |
| 1233 | + path (str): Full path to new file |
| 1234 | + branch (str): The name of branch |
| 1235 | + content (str): Content of the file |
| 1236 | + message (str): Commit message |
| 1237 | + kwargs: Arbitrary keyword arguments |
| 1238 | +
|
| 1239 | + Raises: |
| 1240 | + GitlabCreateError: Operation failed |
| 1241 | + GitlabConnectionError: Connection to GitLab-server failed |
| 1242 | + """ |
1202 | 1243 | url="/projects/%s/repository/files"%self.id |
1203 | 1244 | url+="?file_path=%s&branch_name=%s&content=%s&commit_message=%s"% \ |
1204 | 1245 | (path,branch,content,message) |
|