Bamboo: normalize documentaton of that bamboo module

Author: gonchik

atlassian/bamboo.py

@@ -97,13 +97,22 @@ def base_list_call(
 
     """ Projects & Plans """
 
+
     def projects(
         self,
         expand=None,
         favourite=False,
         clover_enabled=False,
         max_results=25,
     ):
+        """
+        Get all Projects
+        :param expand:
+        :param favourite:
+        :param clover_enabled:
+        :param max_results:
+        :return:
+        """
         return self.base_list_call(
             "project",
             expand=expand,
@@ -115,6 +124,14 @@ def projects(
         )
 
     def project(self, project_key, expand=None, favourite=False, clover_enabled=False):
+        """
+        Get a single project by the key
+        :param project_key:
+        :param expand:
+        :param favourite:
+        :param clover_enabled:
+        :return:
+        """
         resource = "project/{}".format(project_key)
         return self.base_list_call(
             resource=resource,
@@ -125,8 +142,21 @@ def project(self, project_key, expand=None, favourite=False, clover_enabled=Fals
             max_results=25,
         )
 
+    def get_project(self, project_key):
+        """Method used to retrieve information for project specified as project key.
+        Possible expand parameters: plans, list of plans for project. plans.plan, list of plans with plan details
+        (only plans visible - READ permission for user)"""
+        resource = "project/{}?showEmpty".format(project_key)
+        return self.get(self.resource_url(resource))
+
+    def delete_project(self, project_key):
+        """Marks project for deletion. Project will be deleted by a batch job."""
+        resource = "project/{}".format(project_key)
+        return self.delete(self.resource_url(resource))
+
     def project_plans(self, project_key, start_index=0, max_results=25):
         """
+        Get all build plans in a project
         Returns a generator with the plans in a given project.
         :param project_key: project key
         :param start_index:
@@ -153,6 +183,15 @@ def plans(
         start_index=0,
         max_results=25,
     ):
+        """
+        Get all build plans
+        :param expand:
+        :param favourite:
+        :param clover_enabled:
+        :param start_index:
+        :param max_results:
+        :return:
+        """
         return self.base_list_call(
             "plan",
             expand=expand,
@@ -234,6 +273,14 @@ def enable_plan(self, plan_key):
     """ Branches """
 
     def search_branches(self, plan_key, include_default_branch=True, max_results=25, start=0):
+        """
+        Search Branches
+        :param plan_key:
+        :param include_default_branch:
+        :param max_results:
+        :param start:
+        :return:
+        """
         params = {
             "max-result": max_results,
             "start-index": start,
@@ -256,7 +303,16 @@ def plan_branches(
         clover_enabled=False,
         max_results=25,
     ):
-        """api/1.0/plan/{projectKey}-{buildKey}/branch"""
+        """
+        Get all plan Branches
+        api/1.0/plan/{projectKey}-{buildKey}/branch
+        :param plan_key:
+        :param expand:
+        :param favourite:
+        :param clover_enabled:
+        :param max_results:
+        :return:
+        """
         resource = "plan/{}/branch".format(plan_key)
         return self.base_list_call(
             resource,
@@ -617,11 +673,29 @@ def comments(
         start_index=0,
         max_results=25,
     ):
+        """
+        Get comments for a specific build
+        :param project_key:
+        :param plan_key:
+        :param build_number:
+        :param start_index:
+        :param max_results:
+        :return:
+        """
         resource = "result/{}-{}-{}/comment".format(project_key, plan_key, build_number)
         params = {"start-index": start_index, "max-results": max_results}
         return self.get(self.resource_url(resource), params=params)
 
     def create_comment(self, project_key, plan_key, build_number, comment, author=None):
+        """
+        Create a comment for a specific build
+        :param project_key:
+        :param plan_key:
+        :param build_number:
+        :param comment:
+        :param author:
+        :return:
+        """
         resource = "result/{}-{}-{}/comment".format(project_key, plan_key, build_number)
         comment_data = {
             "author": author if author else self.username,
@@ -637,15 +711,40 @@ def labels(
         start_index=0,
         max_results=25,
     ):
+        """
+        Get labels for a build
+        :param project_key:
+        :param plan_key:
+        :param build_number:
+        :param start_index:
+        :param max_results:
+        :return:
+        """
         resource = "result/{}-{}-{}/label".format(project_key, plan_key, build_number)
         params = {"start-index": start_index, "max-results": max_results}
         return self.get(self.resource_url(resource), params=params)
 
     def create_label(self, project_key, plan_key, build_number, label):
+        """
+        Create a label for a specific build
+        :param project_key:
+        :param plan_key:
+        :param build_number:
+        :param label:
+        :return:
+        """
         resource = "result/{}-{}-{}/label".format(project_key, plan_key, build_number)
         return self.post(self.resource_url(resource), data={"name": label})
 
     def delete_label(self, project_key, plan_key, build_number, label):
+        """
+        Delete a label for a specific build
+        :param project_key:
+        :param plan_key:
+        :param build_number:
+        :param label:
+        :return:
+        """
         resource = "result/{}-{}-{}/label/{}".format(project_key, plan_key, build_number, label)
         return self.delete(self.resource_url(resource))
 
@@ -671,34 +770,43 @@ def get_projects(self):
             for project in r["projects"]["project"]:
                 yield project
 
-    def get_project(self, project_key):
-        """Method used to retrieve information for project specified as project key.
-        Possible expand parameters: plans, list of plans for project. plans.plan, list of plans with plan details
-        (only plans visible - READ permission for user)"""
-        resource = "project/{}?showEmpty".format(project_key)
-        return self.get(self.resource_url(resource))
-
-    def delete_project(self, project_key):
-        """Marks project for deletion. Project will be deleted by a batch job."""
-        resource = "project/{}".format(project_key)
-        return self.delete(self.resource_url(resource))
-
     """ Deployments """
 
     def deployment_projects(self):
+        """
+        Returns all deployment projects.
+        :return:
+        """
         resource = "deploy/project/all"
         for project in self.get(self.resource_url(resource)):
             yield project
 
     def deployment_project(self, project_id):
+        """
+        Returns a deployment project.
+        :param project_id:
+        :return:
+        """
         resource = "deploy/project/{}".format(project_id)
         return self.get(self.resource_url(resource))
 
     def delete_deployment_project(self, project_id):
+        """
+        Deletes a deployment project.
+        :param project_id:
+        :return:
+        """
         resource = "deploy/project/{}".format(project_id)
         return self.delete(self.resource_url(resource))
 
     def deployment_environment_results(self, env_id, expand=None, max_results=25):
+        """
+        Get deployment environment results
+        :param env_id:
+        :param expand:
+        :param max_results:
+        :return:
+        """
         resource = "deploy/environment/{environmentId}/results".format(environmentId=env_id)
         params = {"max-result": max_results, "start-index": 0}
         size = 1
@@ -844,23 +952,6 @@ def get_users_not_in_group(self, group_name, filter_users="", start=0, limit=25)
         url = "rest/api/latest/admin/groups/{}/more-non-members".format(group_name)
         return self.get(url, params=params)
 
-    def get_build_queue(self, expand="queuedBuilds"):
-        """
-        Lists all the builds waiting in the build queue, adds or removes a build from the build queue.
-        May be used also to resume build on manual stage or rerun failed jobs.
-        :return:
-        """
-        params = {"expand": expand}
-        return self.get("rest/api/latest/queue", params=params)
-
-    def get_deployment_queue(self, expand="queuedDeployments"):
-        """
-        Provide list of deployment results scheduled for execution and waiting in queue.
-        :return:
-        """
-        params = {"expand": expand}
-        return self.get("rest/api/latest/queue/deployment", params=params)
-
     def get_deployment_users(self, deployment_id, filter_name=None, start=0, limit=25):
         """
         Retrieve a list of users with their explicit permissions to given resource.
@@ -1022,6 +1113,23 @@ def grant_group_to_environment(self, environment_id, group, permissions):
     def server_info(self):
         return self.get(self.resource_url("info"))
 
+    def get_build_queue(self, expand="queuedBuilds"):
+        """
+        Lists all the builds waiting in the build queue, adds or removes a build from the build queue.
+        May be used also to resume build on manual stage or rerun failed jobs.
+        :return:
+        """
+        params = {"expand": expand}
+        return self.get("rest/api/latest/queue", params=params)
+
+    def get_deployment_queue(self, expand="queuedDeployments"):
+        """
+        Provide list of deployment results scheduled for execution and waiting in queue.
+        :return:
+        """
+        params = {"expand": expand}
+        return self.get("rest/api/latest/queue/deployment", params=params)
+
     def agent_status(self, online=False):
         """
         Provides a list of all agents.
@@ -1128,6 +1236,20 @@ def chart(
         start_index=9,
         max_results=25,
     ):
+        """
+        Get chart data
+        :param report_key:
+        :param build_keys:
+        :param group_by_period:
+        :param date_filter:
+        :param date_from:
+        :param date_to:
+        :param width:
+        :param height:
+        :param start_index:
+        :param max_results:
+        :return:
+        """
         params = {
             "reportKey": report_key,
             "buildKeys": build_keys,
@@ -1173,6 +1295,7 @@ def health_check(self):
             response = self.get("rest/supportHealthCheck/1.0/check/")
         return response
 
+    """Elastic Bamboo"""
     def get_elastic_instance_logs(self, instance_id):
         """
         Get logs from an EC2 instance
@@ -1201,7 +1324,7 @@ def create_elastic_configuration(self, json):
 
     def get_elastic_configuration(self, configuration_id):
         """
-        Get informatin of an elastic configuration
+        Get information of an elastic configuration
         :param configuration_id:
         :return:
         """
@@ -1264,7 +1387,7 @@ def get_plugin_info(self, plugin_key):
 
     def get_plugin_license_info(self, plugin_key):
         """
-        Provide plugin license info
+        Provide plugin license information
         :return a json specific License query
         """
         url = "rest/plugins/1.0/{plugin_key}-key/license".format(plugin_key=plugin_key)
@@ -1324,6 +1447,10 @@ def delete_plugin(self, plugin_key):
         return self.delete(url)
 
     def check_plugin_manager_status(self):
+        """
+        Check plugin manager status
+        :return:
+        """
         url = "rest/plugins/latest/safe-mode"
         return self.request(method="GET", path=url, headers=self.safe_mode_headers)