Bamboo: Add support for agents API (#717)

* Bamboo: add online agents filter

Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Check if agent is online

Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Add enable/disable agent

Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Add agent_remote


Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Get agent details

Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Get agent's capabilitis

Signed-off-by: Martin Rakovec <[email protected]>

* Bamboo: Fix blacks

Signed-off-by: Martin Rakovec <[email protected]>

Author: martinrakovec

atlassian/bamboo.py

@@ -357,7 +357,7 @@ def results(
             elements_key="results",
             element_key="result",
             label=label,
-            **params
+            **params,
         )
 
     def latest_results(
@@ -763,8 +763,74 @@ def get_build_queue(self, expand="queuedBuilds"):
     def server_info(self):
         return self.get(self.resource_url("info"))
 
-    def agent_status(self):
-        return self.get(self.resource_url("agent"))
+    def agent_status(self, online=False):
+        """
+        Provides a list of all agents.
+
+        :param online:  filter only online agents (default False = all)
+        :return:
+        """
+        return self.get(self.resource_url("agent"), params={"online": online})
+
+    def agent_is_online(self, agent_id):
+        """
+        Get agent online status.
+
+        :param agent_id:  Bamboo agent ID (integer number)
+        :return: True/False
+        """
+        response = self.get(self.resource_url(f"agent/{agent_id}/status"))
+        return response["online"]
+
+    def agent_enable(self, agent_id):
+        """
+        Enable agent
+
+        :param agent_id:  Bamboo agent ID (integer number)
+        :return: None
+        """
+        self.put(self.resource_url(f"agent/{agent_id}/enable"))
+
+    def agent_disable(self, agent_id):
+        """
+        Disable agent
+
+        :param agent_id:  Bamboo agent ID (integer number)
+        :return: None
+        """
+        self.put(self.resource_url(f"agent/{agent_id}/disable"))
+
+    def agent_remote(self, online=False):
+        """
+        Provides a list of all agent authentication statuses.
+
+        :param online: list only online agents (default False = all)
+        :return: list of agent-describing dictionaries
+        """
+        return self.get(self.resource_url("agent/remote"), params={"online": online})
+
+    def agent_details(self, agent_id, expand=None):
+        """
+        Provides details of an agent with given id.
+
+        :param agent_id:  Bamboo agent ID (integer number)
+        :param expand:    Expand fields (None, capabilities, executableEnvironments, executableJobs)
+        :return:
+        """
+        params = None
+        if expand:
+            params = {"expand": expand}
+        return self.get(self.resource_url(f"agent/{agent_id}"), params=params)
+
+    def agent_capabilities(self, agent_id, include_shared=True):
+        """
+        List agent's capabilities.
+
+        :param agent_id:        Bamboo agent ID (integer number)
+        :param include_shared:  Include shared capabilities
+        :return: agents
+        """
+        return self.get(self.resource_url(f"agent/{agent_id}/capability"), params={"includeShared": include_shared})
 
     def activity(self):
         return self.get("build/admin/ajax/getDashboardSummary.action")

docs/bamboo.rst

@@ -152,6 +152,35 @@ Users & Groups
     # Get users without Group
     get_users_not_in_group(group_name, filter_users='', start=0, limit=25)
 
+Agents
+------
+
+.. code-block:: python
+
+    # Get agents statuses
+    agent_status(online=False)
+
+    # Get remote agents. Currently (version 7.2.2) output is the same as for
+    # agent_status but uses different API
+    agent_remote(online=False)
+
+    # Check if agent is online
+    agent_is_online(agent_id=123456)
+
+    # Enable agent
+    agent_enable(agent_id=123456)
+
+    # Disable agent
+    agent_enable(agent_id=123456)
+
+    # Get agent details
+    agent_details(agent_id=123456)
+    agent_details(agent_id=123456, expand="capabilities,executableEnvironments,executableJobs")
+
+    # Get agent capabilities
+    agent_capabilities(agent_id=123456):
+    agent_capabilities(agent_id=123456, include_shared=False):
+
 Other actions
 -------------
 
@@ -163,9 +192,6 @@ Other actions
     # Get server information
     server_info()
 
-    # Get agents statuses
-    agent_status()
-
     # Get activity
     activity()