Added exception classes for client, database, design document, document, feed, index, and replicator modules

- Added the appropriate status code to the exception with any additional values
- New message module for CloudantException and ResultException messages

Author: emlaver

src/cloudant/_messages.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+# Copyright (c) 2016 IBM. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Module that contains exception messages for the Cloudant Python client
+library.
+"""
+CLIENT = {
+    100: 'A general Cloudant client exception was raised.',
+    101: 'Value must be set to a Database object. Found type: {0}.',
+    102: 'You must provide a url or an account.',
+    404: 'Database {0} does not exist. Verify that the client is valid and try again.',
+    409: 'Database {0} already exists.'
+}
+
+DATABASE = {
+    100: 'A general Cloudant database exception was raised.',
+    101: 'Unexpected index type. Found: {0}.',
+    400: 'Invalid database name during creation. Found: {0}',
+    401: 'Unauthorized to create database {0}.',
+    409: 'Document with id {0} already exists.'
+}
+
+DESIGN_DOCUMENT = {
+    100: 'A general Cloudant design document exception was raised.',
+    101: 'Cannot add a MapReduce view to a design document for query indexes.',
+    102: 'Cannot update a query index view using this method.',
+    103: 'Cannot delete a query index view using this method.',
+    104: 'View {0} must be of type View.',
+    105: 'View {0} must be of type QueryIndexView.',
+    106: 'Function for search index {0} must be of type string.',
+    107: 'Definition for query text index {0} must be of type dict.'
+}
+
+DOCUMENT = {
+    100: 'A general Cloudant document exception was raised.',
+    101: 'A document id is required to fetch document contents. '
+         'Add an _id key and value to the document and re-try.',
+    102: 'The field {0} is not a list.',
+    103: 'Attempting to delete a doc with no _rev. Try running .fetch and re-try.'
+}
+
+FEED = {
+    100: 'A general Cloudant feed exception was raised.',
+    101: 'Infinite _db_updates feed not supported for CouchDB.'
+}
+
+INDEX = {
+    100: 'A general Cloudant index exception was raised.',
+    101: 'Creating the \"special\" index is not allowed.',
+    102: 'Deleting the \"special\" index is not allowed.'
+}
+
+REPLICATOR = {
+    100: 'A general Cloudant replicator exception was raised.',
+    101: 'You must specify either a source_db Database object or a manually composed'
+         ' \'source\' string/dict.',
+    102: 'You must specify either a target_db Database object or a manually composed'
+         ' \'target\' string/dict.',
+    404: 'Replication with id {0} not found.'
+}
+
+RESULT = {
+    100: 'A general result exception was raised.',
+    101: 'Failed to interpret the argument {0} as a valid key value or as a valid slice.',
+    102: 'Cannot use {0} when performing key access or key slicing. Found {1}.',
+    103: 'Cannot use {0} for iteration. Found {1}.',
+    104: 'Invalid page_size: {0}'
+}

src/cloudant/client.py

@@ -24,7 +24,7 @@
 from ._2to3 import bytes_, unicode_
 from .database import CloudantDatabase, CouchDatabase
 from .feed import Feed, InfiniteFeed
-from .error import CloudantException, CloudantArgumentError
+from .error import CloudantArgumentError, CloudantClientException
 from ._common_util import (
     USER_AGENT,
     append_response_error_content,
@@ -198,37 +198,34 @@ def create_database(self, dbname, **kwargs):
         Creates a new database on the remote server with the name provided
         and adds the new database object to the client's locally cached
         dictionary before returning it to the caller.  The method will
-        optionally throw a CloudantException if the database exists remotely.
+        optionally throw a CloudantClientException if the database
+        exists remotely.
 
         :param str dbname: Name used to create the database.
         :param bool throw_on_exists: Boolean flag dictating whether or
-            not to throw a CloudantException when attempting to create a
-            database that already exists.
+            not to throw a CloudantClientException when attempting to
+            create a database that already exists.
 
         :returns: The newly created database object
         """
         new_db = self._DATABASE_CLASS(self, dbname)
         if new_db.exists():
             if kwargs.get('throw_on_exists', True):
-                raise CloudantException(
-                    "Database {0} already exists".format(dbname)
-                )
+                raise CloudantClientException(409, dbname)
         new_db.create()
         super(CouchDB, self).__setitem__(dbname, new_db)
         return new_db
 
     def delete_database(self, dbname):
         """
-        Removes the named database remotely and locally. The method will throw a
-        CloudantException if the database does not exist.
+        Removes the named database remotely and locally. The method will throw
+        a CloudantClientException if the database does not exist.
 
         :param str dbname: Name of the database to delete.
         """
         db = self._DATABASE_CLASS(self, dbname)
         if not db.exists():
-            raise CloudantException(
-                "Database {0} does not exist".format(dbname)
-            )
+            raise CloudantClientException(404, dbname)
         db.delete()
         if dbname in list(self.keys()):
             super(CouchDB, self).__delitem__(dbname)
@@ -378,8 +375,7 @@ def __setitem__(self, key, value, remote=False):
             create the database remotely or not.  Defaults to False.
         """
         if not isinstance(value, self._DATABASE_CLASS):
-            msg = "Value must be set to a Database object"
-            raise CloudantException(msg)
+            raise CloudantClientException(101, type(value).__name__)
         if remote and not value.exists():
             value.create()
         super(CouchDB, self).__setitem__(key, value)
@@ -426,7 +422,7 @@ def __init__(self, cloudant_user, auth_token, **kwargs):
                 self._client_user_header['X-Cloudant-User'] = x_cloudant_user
 
         if self.server_url is None:
-            raise CloudantException('You must provide a url or an account.')
+            raise CloudantClientException(102)
 
         if kwargs.get('connect', False):
             self.connect()
@@ -537,7 +533,7 @@ def _usage_endpoint(self, endpoint, year=None, month=None):
             between 1 and 12. Optional parameter. Defaults to None.
             If used, it must be accompanied by ``year``.
         """
-        err = None
+        err = False
         if year is None and month is None:
             resp = self.r_session.get(endpoint)
         else:
@@ -548,14 +544,14 @@ def _usage_endpoint(self, endpoint, year=None, month=None):
                             endpoint, str(int(year)), str(int(month)))
                     )
                 else:
-                    err = ('Invalid year and/or month supplied.  '
-                           'Found: year - {0}, month - {1}').format(year, month)
+                    err = True
             except (ValueError, TypeError):
-                err = ('Invalid year and/or month supplied.  '
-                       'Found: year - {0}, month - {1}').format(year, month)
+                err = True
 
         if err:
-            raise CloudantArgumentError(err)
+            msg = ('Invalid year and/or month supplied.  '
+                   'Found: year - {0}, month - {1}').format(year, month)
+            raise CloudantArgumentError(msg)
         else:
             resp.raise_for_status()
             return resp.json()

src/cloudant/database.py

@@ -34,7 +34,7 @@
 from .view import View
 from .index import Index, TextIndex, SpecialIndex
 from .query import Query
-from .error import CloudantException, CloudantArgumentError
+from .error import CloudantArgumentError, CloudantDatabaseException
 from .result import Result, QueryResult
 from .feed import Feed, InfiniteFeed
 
@@ -158,9 +158,7 @@ def create_document(self, data, throw_on_exists=False):
         else:
             doc = Document(self, docid)
         if throw_on_exists and doc.exists():
-            raise CloudantException(
-                'Error - Document with id {0} already exists.'.format(docid)
-            )
+            raise CloudantDatabaseException(409, docid)
         doc.update(data)
         doc.create()
         super(CouchDatabase, self).__setitem__(doc['_id'], doc)
@@ -346,11 +344,8 @@ def create(self):
         if resp.status_code == 201 or resp.status_code == 202:
             return self
 
-        raise CloudantException(
-            "Unable to create database {0}: Reason: {1}".format(
-                self.database_url, resp.text
-            ),
-            code=resp.status_code
+        raise CloudantDatabaseException(
+            resp.status_code, self.database_url, resp.text
         )
 
     def delete(self):
@@ -747,10 +742,7 @@ def get_revision_limit(self):
         try:
             ret = int(resp.text)
         except ValueError:
-            resp.status_code = 400
-            raise CloudantException(
-                'Error - Invalid Response Value: {}'.format(resp.json())
-            )
+            raise CloudantDatabaseException(400, resp.json())
 
         return ret
 
@@ -1090,7 +1082,7 @@ def get_query_indexes(self, raw_result=False):
                     **data.get('def', {})
                 ))
             else:
-                raise CloudantException('Unexpected index content: {0} found.')
+                raise CloudantDatabaseException(101, data.get('type'))
         return indexes
 
     def create_query_index(

src/cloudant/design_document.py

@@ -19,7 +19,7 @@
 from ._common_util import QUERY_LANGUAGE, codify
 from .document import Document
 from .view import View, QueryIndexView
-from .error import CloudantArgumentError, CloudantException
+from .error import CloudantArgumentError, CloudantDesignDocumentException
 
 class DesignDocument(Document):
     """
@@ -285,9 +285,7 @@ def add_view(self, view_name, map_func, reduce_func=None, **kwargs):
             msg = "View {0} already exists in this design doc".format(view_name)
             raise CloudantArgumentError(msg)
         if self.get('language', None) == QUERY_LANGUAGE:
-            msg = ('Cannot add a MapReduce view to a '
-                   'design document for query indexes.')
-            raise CloudantException(msg)
+            raise CloudantDesignDocumentException(101)
 
         view = View(self, view_name, map_func, reduce_func, **kwargs)
         self.views.__setitem__(view_name, view)
@@ -361,8 +359,7 @@ def update_view(self, view_name, map_func, reduce_func=None, **kwargs):
             msg = "View {0} does not exist in this design doc".format(view_name)
             raise CloudantArgumentError(msg)
         if isinstance(view, QueryIndexView):
-            msg = 'Cannot update a query index view using this method.'
-            raise CloudantException(msg)
+            raise CloudantDesignDocumentException(102)
 
         view = View(self, view_name, map_func, reduce_func, **kwargs)
         self.views.__setitem__(view_name, view)
@@ -432,8 +429,7 @@ def delete_view(self, view_name):
         if view is None:
             return
         if isinstance(view, QueryIndexView):
-            msg = 'Cannot delete a query index view using this method.'
-            raise CloudantException(msg)
+            raise CloudantDesignDocumentException(103)
 
         self.views.__delitem__(view_name)
 
@@ -517,34 +513,22 @@ def save(self):
             if self.get('language', None) != QUERY_LANGUAGE:
                 for view_name, view in self.iterviews():
                     if isinstance(view, QueryIndexView):
-                        msg = 'View {0} must be of type View.'.format(view_name)
-                        raise CloudantException(msg)
+                        raise CloudantDesignDocumentException(104, view_name)
             else:
                 for view_name, view in self.iterviews():
                     if not isinstance(view, QueryIndexView):
-                        msg = (
-                            'View {0} must be of type QueryIndexView.'
-                        ).format(view_name)
-                        raise CloudantException(msg)
+                        raise CloudantDesignDocumentException(105, view_name)
 
         if self.indexes:
             if self.get('language', None) != QUERY_LANGUAGE:
                 for index_name, search in self.iterindexes():
                     # Check the instance of the javascript search function
                     if not isinstance(search['index'], STRTYPE):
-                        msg = (
-                            'Function for search index {0} must '
-                            'be of type string.'
-                        ).format(index_name)
-                        raise CloudantException(msg)
+                        raise CloudantDesignDocumentException(106, index_name)
             else:
                 for index_name, index in self.iterindexes():
                     if not isinstance(index['index'], dict):
-                        msg = (
-                            'Definition for query text index {0} must '
-                            'be of type dict.'
-                        ).format(index_name)
-                        raise CloudantException(msg)
+                        raise CloudantDesignDocumentException(107, index_name)
 
         for prop in self._nested_object_names:
             if not getattr(self, prop):

src/cloudant/document.py

@@ -21,7 +21,8 @@
 from requests.exceptions import HTTPError
 
 from ._2to3 import url_quote, url_quote_plus
-from .error import CloudantException
+from .error import CloudantDocumentException
+
 
 class Document(dict):
     """
@@ -161,10 +162,7 @@ def fetch(self):
         the locally cached Document object.
         """
         if self.document_url is None:
-            raise CloudantException(
-                'A document id is required to fetch document contents.  '
-                'Add an _id key and value to the document and re-try.'
-            )
+            raise CloudantDocumentException(101)
         resp = self.r_session.get(self.document_url)
         resp.raise_for_status()
         self.clear()
@@ -210,9 +208,7 @@ def list_field_append(doc, field, value):
         if doc.get(field) is None:
             doc[field] = []
         if not isinstance(doc[field], list):
-            raise CloudantException(
-                'The field {0} is not a list.'.format(field)
-            )
+            raise CloudantDocumentException(102, field)
         if value is not None:
             doc[field].append(value)
 
@@ -227,9 +223,7 @@ def list_field_remove(doc, field, value):
         :param value: Value to remove from the field list.
         """
         if not isinstance(doc[field], list):
-            raise CloudantException(
-                'The field {0} is not a list.'.format(field)
-            )
+            raise CloudantDocumentException(102, field)
         doc[field].remove(value)
 
     @staticmethod
@@ -314,10 +308,7 @@ def delete(self):
         object.
         """
         if not self.get("_rev"):
-            raise CloudantException(
-                "Attempting to delete a doc with no _rev. Try running "
-                ".fetch first!"
-            )
+            raise CloudantDocumentException(103)
 
         del_resp = self.r_session.delete(
             self.document_url,