Skip to content

Commit 1b5c8f1

Browse files
author
Gauvain Pocentek
committed
Add docstrings to some methods
1 parent 2e5476e commit 1b5c8f1

File tree

2 files changed

+91
-4
lines changed

2 files changed

+91
-4
lines changed

‎docs/api/gitlab.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Module contents
88
:members:
99
:undoc-members:
1010
:show-inheritance:
11-
:exclude-members: Hook, Project, UserProject, Group, Issue, Team, User,
11+
:exclude-members: Hook, UserProject, Group, Issue, Team, User,
1212
all_projects, owned_projects, search_projects
1313

1414
gitlab.exceptions module
@@ -27,5 +27,5 @@ gitlab.objects module
2727
:undoc-members:
2828
:show-inheritance:
2929
:exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
30-
Label, Member, MergeRequest, Milestone, Note, Project,
31-
Snippet, Tag
30+
Label, Member, MergeRequest, Milestone, Note, Snippet,
31+
Tag

‎gitlab/objects.py

+88-1
Original file line numberDiff line numberDiff line change
@@ -619,6 +619,16 @@ def Member(self, id=None, **kwargs):
619619
**kwargs)
620620

621621
def transfer_project(self, id, **kwargs):
622+
"""Transfers a project to this new groups.
623+
624+
Attrs:
625+
id (int): ID of the project to transfer.
626+
627+
Raises:
628+
GitlabConnectionError: If the server cannot be reached.
629+
GitlabTransferProjectError: If the server fails to perform the
630+
request.
631+
"""
622632
url = '/groups/%d/projects/%d' % (self.id, id)
623633
r = self.gitlab._raw_post(url, None, **kwargs)
624634
raise_error_from_response(r, GitlabTransferProjectError, 201)
@@ -672,6 +682,7 @@ class ProjectBranch(GitlabObject):
672682
requiredCreateAttrs = ['branch_name', 'ref']
673683

674684
def protect(self, protect=True, **kwargs):
685+
"""Protects the project."""
675686
url = self._url % {'project_id': self.project_id}
676687
action = 'protect' if protect else 'unprotect'
677688
url = "%s/%s/%s" % (url, self.name, action)
@@ -684,6 +695,7 @@ def protect(self, protect=True, **kwargs):
684695
del self.protected
685696

686697
def unprotect(self, **kwargs):
698+
"""Unprotects the project."""
687699
self.protect(False, **kwargs)
688700

689701

@@ -701,11 +713,13 @@ class ProjectBuild(GitlabObject):
701713
canCreate = False
702714

703715
def cancel(self):
716+
"""Cancel the build."""
704717
url = '/projects/%s/builds/%s/cancel' % (self.project_id, self.id)
705718
r = self.gitlab._raw_post(url)
706719
raise_error_from_response(r, GitlabBuildCancelError, 201)
707720

708721
def retry(self):
722+
"""Retry the build."""
709723
url = '/projects/%s/builds/%s/retry' % (self.project_id, self.id)
710724
r = self.gitlab._raw_post(url)
711725
raise_error_from_response(r, GitlabBuildRetryError, 201)
@@ -724,6 +738,7 @@ class ProjectCommit(GitlabObject):
724738
shortPrintAttr = 'title'
725739

726740
def diff(self, **kwargs):
741+
"""Generate the commit diff."""
727742
url = ('/projects/%(project_id)s/repository/commits/%(commit_id)s/diff'
728743
% {'project_id': self.project_id, 'commit_id': self.id})
729744
r = self.gitlab._raw_get(url, **kwargs)
@@ -732,6 +747,18 @@ def diff(self, **kwargs):
732747
return r.json()
733748

734749
def blob(self, filepath, **kwargs):
750+
"""Generate the content of a file for this commit.
751+
752+
Args:
753+
filepath (str): Path of the file to request.
754+
755+
Returns:
756+
str: The content of the file
757+
758+
Raises:
759+
GitlabConnectionError: If the server cannot be reached.
760+
GitlabGetError: If the server fails to perform the request.
761+
"""
735762
url = ('/projects/%(project_id)s/repository/blobs/%(commit_id)s' %
736763
{'project_id': self.project_id, 'commit_id': self.id})
737764
url += '?filepath=%s' % filepath
@@ -741,6 +768,15 @@ def blob(self, filepath, **kwargs):
741768
return r.content
742769

743770
def builds(self, **kwargs):
771+
"""List the build for this commit.
772+
773+
Returns:
774+
list(ProjectBuild): A list of builds.
775+
776+
Raises:
777+
GitlabConnectionError: If the server cannot be reached.
778+
GitlabListError: If the server fails to perform the request.
779+
"""
744780
url = '/projects/%s/repository/commits/%s/builds' % (self.project_id,
745781
self.id)
746782
r = self.gitlab._raw_get(url, **kwargs)
@@ -924,6 +960,19 @@ class ProjectTag(GitlabObject):
924960
shortPrintAttr = 'name'
925961

926962
def set_release_description(self, description):
963+
"""Set the release notes on the tag.
964+
965+
If the release doesn't exist yet, it will be created. If it already
966+
exists, its description will be updated.
967+
968+
Args:
969+
description (str): Description of the release.
970+
971+
Raises:
972+
GitlabConnectionError: If the server cannot be reached.
973+
GitlabCreateError: If the server fails to create the release.
974+
GitlabUpdateError: If the server fails to update the release.
975+
"""
927976
url = '/projects/%s/repository/tags/%s/release' % (self.project_id,
928977
self.name)
929978
if self.release is None:
@@ -1032,7 +1081,7 @@ class ProjectFile(GitlabObject):
10321081
getRequiresId = False
10331082

10341083
def decode(self):
1035-
"""Returns the decoded content.
1084+
"""Returns the decoded content of the file.
10361085
10371086
Returns:
10381087
(str): the decoded content.
@@ -1246,6 +1295,19 @@ def Tag(self, id=None, **kwargs):
12461295
**kwargs)
12471296

12481297
def tree(self, path='', ref_name='', **kwargs):
1298+
"""Return a list of files in the repository.
1299+
1300+
Args:
1301+
path (str): Path of the top folder (/ by default)
1302+
ref_name (str): Reference to a commit or branch
1303+
1304+
Returns:
1305+
str: The json representation of the tree.
1306+
1307+
Raises:
1308+
GitlabConnectionError: If the server cannot be reached.
1309+
GitlabGetError: If the server fails to perform the request.
1310+
"""
12491311
url = "/projects/%s/repository/tree" % (self.id)
12501312
params = []
12511313
if path:
@@ -1259,13 +1321,38 @@ def tree(self, path='', ref_name='', **kwargs):
12591321
return r.json()
12601322

12611323
def blob(self, sha, filepath, **kwargs):
1324+
"""Return the content of a file for a commit.
1325+
1326+
Args:
1327+
sha (str): ID of the commit
1328+
filepath (str): Path of the file to return
1329+
1330+
Returns:
1331+
str: The file content
1332+
1333+
Raises:
1334+
GitlabConnectionError: If the server cannot be reached.
1335+
GitlabGetError: If the server fails to perform the request.
1336+
"""
12621337
url = "/projects/%s/repository/blobs/%s" % (self.id, sha)
12631338
url += '?filepath=%s' % (filepath)
12641339
r = self.gitlab._raw_get(url, **kwargs)
12651340
raise_error_from_response(r, GitlabGetError)
12661341
return r.content
12671342

12681343
def archive(self, sha=None, **kwargs):
1344+
"""Return a tarball of the repository.
1345+
1346+
Args:
1347+
sha (str): ID of the commit (default branch by default).
1348+
1349+
Returns:
1350+
str: The binary data of the archive.
1351+
1352+
Raises:
1353+
GitlabConnectionError: If the server cannot be reached.
1354+
GitlabGetError: If the server fails to perform the request.
1355+
"""
12691356
url = '/projects/%s/repository/archive' % self.id
12701357
if sha:
12711358
url += '?sha=%s' % sha

0 commit comments

Comments
 (0)