Add status checking (fixes #3). Add settable timeouts on all calls. Move to a4.

* The status API endpoint is deduced from the usermanagement endpoint.
* The default timeout is 60 seconds.
* Added a live testing suite keyed on availability of credentials and configuration parameters in a "local" directory.

Author: brotskydotcom

setup.py

@@ -20,9 +20,8 @@
 
 from setuptools import setup, find_packages
 
-
 setup(name='umapi-client',
-      version='2.0a2',
+      version='2.0a4',
       description='Client for the User Management API (UMAPI) from Adobe - see https://adobe.ly/2h1pHgV',
       long_description=('The User Management API (aka the UMAPI) is an Adobe-hosted network service '
                         'which provides Adobe Enterprise customers the ability to manage their users.  This '
@@ -43,16 +42,17 @@
       license='MIT',
       packages=find_packages(),
       install_requires=[
-        'requests>=2.4.2',
-        'cryptography',
-        'PyJWT',
-        'six',
+          'requests>=2.4.2',
+          'cryptography',
+          'PyJWT',
+          'six',
       ],
       setup_requires=[
-        'pytest-runner',
+          'pytest-runner',
       ],
       tests_require=[
-        'pytest',
-        'mock',
+          'pytest',
+          'mock',
+          'PyYAML',
       ],
       zip_safe=False)

tests/test_connections.py

@@ -23,9 +23,31 @@
 
 import mock
 import pytest
+import requests
 
 from conftest import mock_connection_params, MockResponse
-from umapi_client import Connection, UnavailableError, ServerError, RequestError
+from umapi_client import Connection, UnavailableError, ServerError, RequestError, ClientError
+
+
+def test_status_success():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.return_value = MockResponse(200, body={"build": "2559", "version": "2.1.54", "state":"LIVE"})
+        conn = Connection(**mock_connection_params)
+        assert conn.status() == {"build": "2559", "version": "2.1.54", "state":"LIVE"}
+
+
+def test_status_failure():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.return_value = MockResponse(404, text="404 Not Found")
+        conn = Connection(**mock_connection_params)
+        pytest.raises (ClientError, conn.status)
+
+
+def test_status_timeout():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.side_effect = requests.Timeout
+        conn = Connection(**mock_connection_params)
+        pytest.raises(UnavailableError, conn.status)
 
 
 def test_get_success():
@@ -42,6 +64,20 @@ def test_post_success():
         assert conn.make_call("", [3, 5]).json() == ["test", "body"]
 
 
+def test_get_timeout():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.side_effect = requests.Timeout
+        conn = Connection(**mock_connection_params)
+        pytest.raises(UnavailableError, conn.make_call, "")
+
+
+def test_post_timeout():
+    with mock.patch("umapi_client.connection.requests.post") as mock_post:
+        mock_post.side_effect = requests.Timeout
+        conn = Connection(**mock_connection_params)
+        pytest.raises(UnavailableError, conn.make_call, "", [3, 5])
+
+
 def test_get_retry_header_1():
     with mock.patch("umapi_client.connection.requests.get") as mock_get:
         mock_get.return_value = MockResponse(429, headers={"Retry-After": "1"})

tests/test_live.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2016 Adobe Systems Incorporated.  All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import logging
+import re
+import os
+
+import pytest
+import yaml
+import six
+
+import umapi_client
+
+# this test relies on a sensitive configuraition
+config_file_name = "local/live_configuration.yaml"
+pytestmark = pytest.mark.skipif(not os.access(config_file_name, os.R_OK),
+                                reason="Live config file '{}' not found.".format(config_file_name))
+
+logging.basicConfig(level=logging.INFO,
+                    format='%(asctime)s: %(levelname)s: %(message)s',
+                    datefmt='%m/%d/%Y %I:%M:%S %p')
+
+
+@pytest.fixture(scope="module")
+def config():
+    with open(config_file_name, "r") as f:
+        config = yaml.load(f)
+    creds = config["test_org"]
+    conn = umapi_client.Connection(org_id=creds["org_id"], auth_dict=creds)
+    return conn, config
+
+
+def test_status(config):
+    conn, _ = config
+    status = conn.status()
+    assert status["state"] == "LIVE"
+
+
+def test_list_users(config):
+    conn, _ = config
+    users = umapi_client.UsersQuery(connection=conn, in_domain="")
+    for user in users:
+        email = user.get("email", "")
+        if re.match(r".*@adobe.com$", str(email).lower()):
+            assert str(user["type"]) == "adobeID"
+
+
+def test_get_user(config):
+    conn, params = config
+    user_query = umapi_client.UserQuery(conn, params["test_user"]["email"])
+    user = user_query.result()
+    for k, v in six.iteritems(params["test_user"]):
+        assert user[k].lower() == v.lower()

tests/test_queries.py

@@ -23,7 +23,7 @@
 import mock
 
 from conftest import mock_connection_params, MockResponse
-from umapi_client import Connection, QueryMultiple, ClientError
+from umapi_client import Connection, QueryMultiple, QuerySingle, ClientError
 
 
 def test_query_single_success():
@@ -68,6 +68,13 @@ def test_query_multiple_empty():
         assert conn.query_multiple("object") == ([], True)
 
 
+def test_query_multiple_not_found():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.return_value = MockResponse(404, text="404 Object not found")
+        conn = Connection(**mock_connection_params)
+        assert conn.query_multiple("object") == ([], True)
+
+
 def test_query_multiple_paged():
     with mock.patch("umapi_client.connection.requests.get") as mock_get:
         mock_get.side_effect = [MockResponse(200, {"result": "success",
@@ -87,6 +94,38 @@ def test_query_multiple_paged():
                                                     True)
 
 
+def test_qs_success():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.return_value = MockResponse(200, {"result": "success",
+                                                   "object": {"user": "[email protected]", "type": "adobeID"}})
+        conn = Connection(**mock_connection_params)
+        qs = QuerySingle(conn, "object", ["[email protected]"])
+        assert qs.result() == {"user": "[email protected]", "type": "adobeID"}
+
+
+def test_qs_not_found():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.return_value = MockResponse(404, text="404 Object not found")
+        conn = Connection(**mock_connection_params)
+        qs = QuerySingle(conn, "object", ["[email protected]"])
+        assert qs.result() == {}
+
+
+def test_qs_reload():
+    with mock.patch("umapi_client.connection.requests.get") as mock_get:
+        mock_get.side_effect = [MockResponse(200, {"result": "success",
+                                                   "object": {"user": "[email protected]", "type": "adobeID"}}),
+                                MockResponse(200, {"result": "success",
+                                                   "object": {"user": "[email protected]", "type": "adobeID"}})]
+        conn = Connection(**mock_connection_params)
+        qs = QuerySingle(conn, "object", ["[email protected]"])
+        assert qs.result() == {"user": "[email protected]", "type": "adobeID"}
+        # second verse, same as the first
+        assert qs.result() == {"user": "[email protected]", "type": "adobeID"}
+        qs.reload()
+        assert qs.result() == {"user": "[email protected]", "type": "adobeID"}
+
+
 def test_qm_iterate_complete():
     with mock.patch("umapi_client.connection.requests.get") as mock_get:
         mock_get.side_effect = [MockResponse(200, {"result": "success",

umapi_client/__init__.py

@@ -19,5 +19,5 @@
 # SOFTWARE.
 
 from .connection import Connection
-from .api import Action, UserAction, QueryMultiple
+from .api import Action, UserAction, QueryMultiple, UsersQuery, GroupsQuery, QuerySingle, UserQuery
 from .error import ClientError, RequestError, ServerError, UnavailableError

umapi_client/api.py

@@ -142,7 +142,6 @@ class QueryMultiple:
     """
     A QueryMultiple runs a query against a connection.  The results can be iterated or fetched in bulk.
     """
-
     def __init__(self, connection, object_type, url_params=None, query_params=None):
         # type: (Connection, str, list, dict) -> None
         """
@@ -234,16 +233,18 @@ class UsersQuery(QueryMultiple):
     Query for users meeting (optional) criteria
     """
 
-    def __init__(self, connection, in_group="", in_domain=""):
+    def __init__(self, connection, in_group="", in_domain="", identity_type=""):
         """
         Create a query for all users, or for those in a group or domain or both
         :param connection: Connection to run the query against
         :param in_group: (optional) name of the group to restrict the query to
         :param in_domain: (optional) name of the domain to restrict the query to
         """
         groups = [in_group] if in_group else []
-        domains = {"domain": in_domain} if in_domain else {}
-        QueryMultiple.__init__(self, connection=connection, object_type="user", url_params=groups, query_params=domains)
+        params = {}
+        if in_domain: params["domain"] = str(in_domain)
+        if identity_type: params["type"] = str(identity_type)
+        QueryMultiple.__init__(self, connection=connection, object_type="user", url_params=groups, query_params=params)
 
 
 class GroupsQuery(QueryMultiple):
@@ -257,3 +258,59 @@ def __init__(self, connection):
         :param connection: Connection to run the query against
         """
         QueryMultiple.__init__(self, connection=connection, object_type="group")
+
+class QuerySingle:
+    """
+    Look for a single object
+    """
+    def __init__(self, connection, object_type, url_params=None, query_params=None):
+        # type: (Connection, str, list, dict) -> None
+        """
+        Provide the connection and query parameters when you create the query.
+
+        :param connection: The Connection to run the query against
+        :param object_type: The type of object being queried (e.g., "user" or "group")
+        :param url_params: Query qualifiers that go in the URL path (e.g., a group name when querying users)
+        :param query_params: Query qualifiers that go in the query string (e.g., a domain name)
+        """
+        self.conn = connection
+        self.object_type = object_type
+        self.url_params = url_params if url_params else []
+        self.query_params = query_params if query_params else {}
+        self._result = None
+
+    def reload(self):
+        """
+        Rerun the query (lazily).
+        The result will contain a value on the server side that have changed since the last run.
+        :return: None
+        """
+        self._result = None
+
+    def _fetch_result(self):
+        """
+        Fetch the queried object.
+        """
+        self._result = self.conn.query_single(self.object_type, self.url_params, self.query_params)
+
+    def result(self):
+        """
+        Fetch the result, if we haven't already or if reload has been called.
+        :return: the result object of the query.
+        """
+        if self._result is None:
+            self._fetch_result()
+        return self._result
+
+class UserQuery(QuerySingle):
+    """
+    Query for a single user
+    """
+
+    def __init__(self, connection, email):
+        """
+        Create a query for the user with the given email
+        :param connection: Connection to run the query against
+        :param email: email of user to query for
+        """
+        QuerySingle.__init__(self, connection=connection, object_type="user", url_params=[str(email)])

umapi_client/connection.py

@@ -49,6 +49,7 @@ def __init__(self,
                  retry_max_attempts=4,
                  retry_first_delay=15,
                  retry_random_delay=5,
+                 timeout_seconds=60.0,
                  **kwargs):
         """
         Open a connection for the given parameters that has the given options.
@@ -87,6 +88,7 @@ def __init__(self,
         self.retry_max_attempts = retry_max_attempts
         self.retry_first_delay = retry_first_delay
         self.retry_random_delay = retry_random_delay
+        self.timeout = float(timeout_seconds) if float(timeout_seconds) > 0.0 else 60.0
         if auth:
             self.auth = auth
         elif auth_dict:
@@ -104,6 +106,22 @@ def _get_auth(self, ims_host, ims_endpoint_jwt,
         token = AccessRequest("https://" + ims_host + ims_endpoint_jwt, api_key, client_secret, jwt())
         return Auth(api_key, token())
 
+    def status(self):
+        """
+        Check whether the UMAPI service is up, and return data about version and build.
+        :return: dictionary of status data, or raise UnavailableError.
+        """
+        components = urlparse.urlparse(self.endpoint)
+        try:
+            result = requests.get(components[0] + "://" + components[1] + "/status", timeout=self.timeout)
+        except Exception as e:
+            if self.logger: self.logger.error("Failed to connect to server: %s", e)
+            raise UnavailableError(1, int(self.timeout), None)
+        if result.status_code == 200:
+            return result.json()
+        else:
+            raise ClientError("Response status was {:d}".format(result.status_code), result)
+
     def query_single(self, object_type, url_params, query_params=None):
         # type: (str, list, dict) -> dict
         """
@@ -225,18 +243,22 @@ def make_call(self, path, body=None):
         if body:
             request_body = json.dumps(body)
             def call():
-                return requests.post(self.endpoint + path, auth=self.auth, data=request_body)
+                return requests.post(self.endpoint + path, auth=self.auth, data=request_body, timeout=self.timeout)
         else:
             def call():
-                return requests.get(self.endpoint + path, auth=self.auth)
+                return requests.get(self.endpoint + path, auth=self.auth, timeout=self.timeout)
 
         total_time = wait_time = 0
         for num_attempts in range(1, self.retry_max_attempts + 1):
             if wait_time > 0:
                 sleep(wait_time)
                 total_time += wait_time
                 wait_time = 0
-            result = call()
+            try:
+                result = call()
+            except requests.Timeout:
+                total_time += int(self.timeout)
+                raise UnavailableError(num_attempts, total_time, None)
             if result.status_code == 200:
                 return result
             elif result.status_code in [429, 502, 503, 504]: