Added documentation for exceptions raised by elasticsearch-py

Fixes #58, thanks, willkg, for the report!

docs/api.rst

@@ -3,13 +3,16 @@
 API Documentation
 =================
 
-.. note::
+All the API calls map the raw REST api as closely as possible, including the
+distinction between required and optional arguments to the calls. This means
+that the code makes distinction between positional and keyword arguments; we,
+however, recommend that people *use keyword arguments for all calls for
+consistency and safety*.
 
-    All the API calls map the raw REST api as closely as possible, including
-    the distinction between required and optional arguments to the calls. This
-    means that the code makes distinction between positional and keyword arguments;
-    we, however, recommend that people use keyword arguments for all calls for
-    consistency and safety.
+An API call is considered successful (and will return a response) if
+elasticsearch returns a 2XX response. Otherwise an instance of
+:class:`~elasticsearch.TransportError` (or a more specific subclass) will be
+raised. You can see other exception and error states in :ref:`exceptions`.
 
 .. note::
    

docs/exceptions.rst

@@ -0,0 +1,20 @@
+.. _exceptions:
+
+Exceptions
+==========
+
+.. py:module:: elasticsearch
+
+.. autoclass:: ImproperlyConfigured
+
+.. autoclass:: ElasticsearchException
+
+.. autoclass:: SerializationError(ElasticsearchException)
+
+.. autoclass:: TransportError(ElasticsearchException)
+   :members:
+
+.. autoclass:: NotFoundError(TransportError)
+.. autoclass:: ConflictError(TransportError)
+.. autoclass:: RequestError(TransportError)
+.. autoclass:: ConnectionError(TransportError)

docs/index.rst

@@ -123,6 +123,7 @@ Contents
    :maxdepth: 2
 
    api
+   exceptions
    connection
    transports
    helpers

elasticsearch/exceptions.py

@@ -1,24 +1,39 @@
 __all__ = [
     'ImproperlyConfigured', 'ElasticsearchException', 'SerializationError',
-    'TransportError', 'NotFoundError', 'ConflictError', 'RequestError'
+    'TransportError', 'NotFoundError', 'ConflictError', 'RequestError', 'ConnectionError'
 ]
 
 class ImproperlyConfigured(Exception):
-    pass
+    """
+    Exception raised when the config passed to the client is inconsistent or invalid.
+    """
 
 class ElasticsearchException(Exception):
-    pass
+    """
+    Base class for all exceptions raised by this package's operations (doesn't
+    apply to :class:`~elasticsearch.ImproperlyConfigured`).
+    """
 
 
 class SerializationError(ElasticsearchException):
-    pass
+    """
+    Data passed int failed to serialize properly in the ``Serializer`` being
+    used.
+    """
 
 
 class TransportError(ElasticsearchException):
-    """ Exception raised when ES returns a non-OK (>=400) HTTP status code. """
+    """
+    Exception raised when ES returns a non-OK (>=400) HTTP status code. Or when
+    an actual connection error happens; in that case the ``status_code`` will
+    be set to ``'N/A'``.
+    """
     @property
     def status_code(self):
-        """ The HTTP status code of the response that precipitated the error. """
+        """
+        The HTTP status code of the response that precipitated the error or
+        ``'N/A'`` if not applicable.
+        """
         return self.args[0]
 
     @property
@@ -28,7 +43,7 @@ class TransportError(ElasticsearchException):
 
     @property
     def info(self):
-        """ Dict of returned error info from ES, where applicable. """
+        """ Dict of returned error info from ES, where available. """
         return self.args[2]
 
     def __str__(self):
@@ -36,22 +51,26 @@ class TransportError(ElasticsearchException):
 
 
 class ConnectionError(TransportError):
-    """ Error raised when there was an exception while talking to ES. """
+    """
+    Error raised when there was an exception while talking to ES. Original
+    exception from the underlying :class:`~elasticsearch.Connection`
+    implementation is available as ``.info.``
+    """
     def __str__(self):
         return 'ConnectionError(%s) caused by: %s(%s)' % (
             self.error, self.info.__class__.__name__, self.info)
 
 
 class NotFoundError(TransportError):
-    pass
+    """ Exception representing a 404 status code. """
 
 
 class ConflictError(TransportError):
-    pass
+    """ Exception representing a 409 status code. """
 
 
 class RequestError(TransportError):
-    pass
+    """ Exception representing a 400 status code. """
 
 # more generic mappings from status_code to python exceptions
 HTTP_EXCEPTIONS = {