Add new module Cloud Admin (#1033)

* add Cloud Admin module

* formatting

* add examples

* fix comment syntax

Author: YugoHino

atlassian/__init__.py

@@ -1,20 +1,22 @@
 from .bamboo import Bamboo
 from .bitbucket import Bitbucket
 from .bitbucket import Bitbucket as Stash
+from .cloud_admin import CloudAdminOrgs, CloudAdminUsers
 from .confluence import Confluence
 from .crowd import Crowd
+from .insight import Insight
 from .jira import Jira
 from .marketplace import MarketPlace
 from .portfolio import Portfolio
 from .service_desk import ServiceDesk
 from .xray import Xray
-from .insight import Insight
-
 
 __all__ = [
     "Confluence",
     "Jira",
     "Bitbucket",
+    "CloudAdminOrgs",
+    "CloudAdminUsers",
     "Portfolio",
     "Bamboo",
     "Stash",

atlassian/cloud_admin.py

@@ -0,0 +1,32 @@
+# coding=utf-8
+import logging
+
+from .rest_client import AtlassianRestAPI
+
+log = logging.getLogger(__name__)
+
+ADMIN_URL = "https://api.atlassian.com"
+
+
+class CloudAdminOrgs(AtlassianRestAPI):
+    def __init__(self, admin_api_key, *args, **kwargs):
+        kwargs["token"] = admin_api_key
+        kwargs["api_root"] = "admin"
+        kwargs["api_version"] = "v1"
+        super(CloudAdminOrgs, self).__init__(url=ADMIN_URL, *args, **kwargs)
+
+    def get_organizations(self):
+        url = self.resource_url("orgs")
+        return self.get(url)
+
+
+class CloudAdminUsers(AtlassianRestAPI):
+    def __init__(self, admin_api_key, *args, **kwargs):
+        kwargs["token"] = admin_api_key
+        kwargs["api_root"] = "users"
+        kwargs["api_version"] = None
+        super(CloudAdminUsers, self).__init__(ADMIN_URL, *args, **kwargs)
+
+    def get_profile(self, account_id):
+        url = self.resource_url("{}/manage/profile".format(account_id))
+        return self.get(url)

atlassian/rest_client.py

@@ -4,9 +4,10 @@
 
 import requests
 from oauthlib.oauth1 import SIGNATURE_RSA
+from requests import HTTPError
 from requests_oauthlib import OAuth1, OAuth2
 from six.moves.urllib.parse import urlencode
-from requests import HTTPError
+
 from atlassian.request_utils import get_default_logger
 
 log = get_default_logger(__name__)
@@ -94,7 +95,7 @@ def _create_token_session(self, token):
         self._update_header("Authorization", "Bearer {token}".format(token=token))
 
     def _create_kerberos_session(self, _):
-        from requests_kerberos import HTTPKerberosAuth, OPTIONAL
+        from requests_kerberos import OPTIONAL, HTTPKerberosAuth
 
         self._session.auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)
 
@@ -392,9 +393,12 @@ def raise_for_status(self, response):
         if 400 <= response.status_code < 600:
             try:
                 j = response.json()
-                error_msg = "\n".join(
-                    j.get("errorMessages", list()) + [k + ": " + v for k, v in j.get("errors", dict()).items()]
-                )
+                if self.url == "https://api.atlassian.com":
+                    error_msg = "\n".join([k + ": " + v for k, v in j.items()])
+                else:
+                    error_msg = "\n".join(
+                        j.get("errorMessages", list()) + [k + ": " + v for k, v in j.get("errors", dict()).items()]
+                    )
             except Exception:
                 response.raise_for_status()
             else:

docs/cloud_admin.rst

@@ -0,0 +1,19 @@
+Cloud Admin module
+==================
+
+CloudAdminOrgs
+--------------
+
+.. code-block:: python
+
+    # Returns a list of your organizations
+    cloud_admin_orgs.get_organizations()
+
+
+CloudAdminUsers
+---------------
+
+.. code-block:: python
+
+    # Returns information about a single Atlassian account by ID
+    cloud_admin_users.get_profile(account_id)

docs/index.rst

@@ -219,6 +219,21 @@ And to Bitbucket Cloud:
         password=bitbucket_app_password,
         cloud=True)
 
+Getting started with Cloud Admin module
+---------------------------------------
+
+Add a connection:
+
+.. code-block:: python
+
+    from atlassian import CloudAdminOrgs, CloudAdminUsers
+
+    cloud_admin_orgs = CloudAdminOrgs(
+        admin-api-key=admin-api-key)
+
+    cloud_admin_users = CloudAdminUsers(
+        admin-api-key=admin-api-key)
+
 .. toctree::
    :maxdepth: 2
 
@@ -229,6 +244,7 @@ And to Bitbucket Cloud:
    bamboo
    service_desk
    xray
+   cloud_admin
 
 .. |Build Status| image:: https://github.com/atlassian-api/atlassian-python-api/workflows/Test/badge.svg?branch=master
    :target: https://pypi.python.org/pypi/atlassian-python-api

examples/cloud_admin/cloud_admin_orgs_get_organizations.py

@@ -0,0 +1,8 @@
+# coding=utf-8
+from atlassian import CloudAdminOrgs
+
+# How to get organizations
+
+cloud_admin_orgs = CloudAdminOrgs(admin_api_key="admin_api_key")
+
+cloud_admin_orgs.get_organizations()

examples/cloud_admin/cloud_admin_users_get_profile.py

@@ -0,0 +1,8 @@
+# coding=utf-8
+from atlassian import CloudAdminUsers
+
+# How to get user profile
+
+cloud_admin_users = CloudAdminUsers(admin_api_key="admin_api_key")
+
+cloud_admin_users.get_organizations(account_id="account_id")