Add IAM class method to Cloudant class

Author: smithsz

src/cloudant/__init__.py

@@ -63,15 +63,29 @@ def cloudant(user, passwd, **kwargs):
     cloudant_session.disconnect()
 
 @contextlib.contextmanager
-def cloudant_iam(api_key, account_name, **kwargs):
+def cloudant_iam(account_name, api_key, **kwargs):
     """
-    Provides a context manager to create a Cloudant session and provide access
-    to databases, docs etc.
+    Provides a context manager to create a Cloudant session using IAM
+    authentication and provide access to databases, docs etc.
 
-    :param api_key: IAM authentication API key.
     :param account_name: Cloudant account name.
+    :param api_key: IAM authentication API key.
+
+    For example:
+
+    .. code-block:: python
+
+        # cloudant context manager
+        from cloudant import cloudant_iam
+
+        with cloudant_iam(ACCOUNT_NAME, API_KEY) as client:
+            # Context handles connect() and disconnect() for you.
+            # Perform library operations within this context.  Such as:
+            print client.all_dbs()
+            # ...
+
     """
-    cloudant_session = Cloudant(account_name, api_key, use_iam=True, **kwargs)
+    cloudant_session = Cloudant.iam(account_name, api_key, **kwargs)
 
     cloudant_session.connect()
     yield cloudant_session

src/cloudant/client.py

@@ -29,7 +29,6 @@
 from ._common_util import (
     USER_AGENT,
     append_response_error_content,
-    InfiniteSession,
     ClientSession,
     CloudFoundryService,
     CookieSession,
@@ -68,6 +67,10 @@ class CouchDB(dict):
         `Requests library timeout argument
         <http://docs.python-requests.org/en/master/user/quickstart/#timeouts>`_.
         but will apply to every request made using this client.
+    :param bool use_iam: Keyword argument, if set to True performs
+        IAM authentication with server. Default is False.
+        Use :func:`~cloudant.client.CouchDB.iam` to construct an IAM
+        authenticated client.
     """
     _DATABASE_CLASS = CouchDatabase
 
@@ -147,16 +150,8 @@ def session(self):
         """
         if self.admin_party:
             return None
-<<<<<<< HEAD
-        sess_url = '/'.join((self.server_url, '_session'))
-        resp = self.r_session.get(sess_url)
-        resp.raise_for_status()
-        sess_data = resp.json()
-        return sess_data
-=======
 
         return self.r_session.info()
->>>>>>> Add IAM authentication support
 
     def session_cookie(self):
         """
@@ -175,21 +170,8 @@ def session_login(self):
         """
         if self.admin_party:
             return
-<<<<<<< HEAD
-        sess_url = '/'.join((self.server_url, '_session'))
-        resp = self.r_session.post(
-            sess_url,
-            data={
-                'name': user,
-                'password': passwd
-            },
-            headers={'Content-Type': 'application/x-www-form-urlencoded'}
-        )
-        resp.raise_for_status()
-=======
 
         self.r_session.login()
->>>>>>> Add IAM authentication support
 
     def session_logout(self):
         """
@@ -198,14 +180,8 @@ def session_logout(self):
         """
         if self.admin_party:
             return
-<<<<<<< HEAD
-        sess_url = '/'.join((self.server_url, '_session'))
-        resp = self.r_session.delete(sess_url)
-        resp.raise_for_status()
-=======
 
         self.r_session.logout()
->>>>>>> Add IAM authentication support
 
     def basic_auth_str(self):
         """
@@ -805,3 +781,13 @@ def bluemix(cls, vcap_services, instance_name=None, **kwargs):
                         service.password,
                         url=service.url,
                         **kwargs)
+
+    @classmethod
+    def iam(cls, account_name, api_key, **kwargs):
+        """
+        Create a Cloudant client that uses IAM authentication.
+
+        :param account_name: Cloudant account name.
+        :param api_key: IAM authentication API key.
+        """
+        return cls(None, api_key, account=account_name, use_iam=True, **kwargs)