More doc fixes

2013-09-24 16:58:37 +02:00
parent 4477895b42
commit ec038c4e9c
9 changed files with 114 additions and 61 deletions
@@ -1,6 +1,14 @@
 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.
+
 .. py:module:: elasticsearch

 Elasticsearch
@@ -1,3 +1,5 @@
+.. _connection_api:
+
 Connection Layer API
 ====================

@@ -49,6 +49,26 @@ Example Usage
    {u'text': u'Elasticsearch: cool. bonsai cool.', u'author': u'kimchy', u'timestamp': u'2010-10-10T10:10:10'}
    Got 1 Hits:
    2010-10-10T10:10:10 kimchy: Elasticsearch: cool. bonsai cool.
+
+Features
+--------
+
+Extendability
+~~~~~~~~~~~~~
+
+Configurable connections and load balancing (see :ref:`connection_api`)::
+ * persistent connections
+ * configurable load balancing strategy
+ * different protocols and connection classes
+ * ...
+
+
+Sniffing
+~~~~~~~~
+
+The client can be configured to inspect the cluster state to get a list of
+nodes upon startup, periodically and/or on failure. See
+:class:`~elasticsearch.Transport` parameters for details.
    
 Contents
 --------
@@ -58,6 +78,7 @@ Contents

   api
   connection
+   transports

 License
 -------
@@ -36,6 +36,10 @@ class Elasticsearch(object):
    """
    Elasticsearch low-level client. Provides a straightforward mapping from
    Python to ES REST endpoints.
+
+    The instance has attributes `indices` and `cluster` that provide access to
+    :class:`~elasticsearch.client.IndicesClient` and
+    :class:`~elasticsearch.client.ClusterClient` instances respectively.
    """
    def __init__(self, hosts=None, transport_class=Transport, **kwargs):
        """
@@ -91,7 +95,7 @@ class Elasticsearch(object):
        """
        Adds a typed JSON document in a specific index, making it searchable.
        Behind the scenes this method calls index(..., op_type='create')
-        http://elasticsearch.org/guide/reference/api/index_/
+        `<http://elasticsearch.org/guide/reference/api/index_/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document
@@ -117,7 +121,7 @@ class Elasticsearch(object):
    def index(self, index, doc_type, body, id=None, params=None):
        """
        Adds or updates a typed JSON document in a specific index, making it searchable.
-        http://elasticsearch.org/guide/reference/api/index_/
+        `<http://elasticsearch.org/guide/reference/api/index_/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document
@@ -144,7 +148,7 @@ class Elasticsearch(object):
    def exists(self, index, id, doc_type='_all', params=None):
        """
        Returns a boolean indicating whether or not given document exists in Elasticsearch.
-        http://elasticsearch.org/guide/reference/api/get/
+        `<http://elasticsearch.org/guide/reference/api/get/>`_

        :arg index: The name of the index
        :arg id: The document ID
@@ -169,7 +173,7 @@ class Elasticsearch(object):
    def get(self, index, id, doc_type='_all', ignore=(), params=None):
        """
        Get a typed JSON document from the index based on its id.
-        http://elasticsearch.org/guide/reference/api/get/
+        `<http://elasticsearch.org/guide/reference/api/get/>`_

        :arg index: The name of the index
        :arg id: The document ID
@@ -200,7 +204,7 @@ class Elasticsearch(object):
    def get_source(self, index, id, doc_type='_all', ignore=(), params=None):
        """
        Get the source of a document by it's index, type and id.
-        http://elasticsearch.org/guide/reference/api/get/
+        `<http://elasticsearch.org/guide/reference/api/get/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document (uses `_all` by default to
@@ -229,7 +233,7 @@ class Elasticsearch(object):
    def mget(self, body, index=None, doc_type=None, params=None):
        """
        Get multiple documents based on an index, type (optional) and ids.
-        http://elasticsearch.org/guide/reference/api/multi-get/
+        `<http://elasticsearch.org/guide/reference/api/multi-get/>`_

        :arg body: Document identifiers; can be either `docs` (containing full
            document information) or `ids` (when index and type is provided in the URL.
@@ -254,7 +258,7 @@ class Elasticsearch(object):
    def update(self, index, doc_type, id, body=None, ignore=(), params=None):
        """
        Update a document based on a script or partial data provided.
-        http://elasticsearch.org/guide/reference/api/update/
+        `<http://elasticsearch.org/guide/reference/api/update/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document
@@ -298,7 +302,7 @@ class Elasticsearch(object):
    def search(self, index=None, doc_type=None, body=None, params=None):
        """
        Execute a search query and get back search hits that match the query.
-        http://www.elasticsearch.org/guide/reference/api/search/
+        `<http://www.elasticsearch.org/guide/reference/api/search/>`_

        :arg index: A comma-separated list of index names to search; use `_all`
            or empty string to perform the operation on all indices
@@ -351,7 +355,7 @@ class Elasticsearch(object):
    def scroll(self, scroll_id, params=None):
        """
        Scroll a search request created by specifying the scroll parameter.
-        http://www.elasticsearch.org/guide/reference/api/search/scroll/
+        `<http://www.elasticsearch.org/guide/reference/api/search/scroll/>`_

        :arg scroll_id: The scroll ID
        :arg scroll: Specify how long a consistent view of the index should be
@@ -366,7 +370,7 @@ class Elasticsearch(object):
    def delete(self, index, doc_type, id, ignore=(), params=None):
        """
        Delete a typed JSON document from a specific index based on its id.
-        http://elasticsearch.org/guide/reference/api/delete/
+        `<http://elasticsearch.org/guide/reference/api/delete/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document
@@ -394,7 +398,7 @@ class Elasticsearch(object):
    def count(self, index=None, doc_type=None, body=None, params=None):
        """
        Execute a query and get the number of matches for that query.
-        http://elasticsearch.org/guide/reference/api/count/
+        `<http://elasticsearch.org/guide/reference/api/count/>`_

        :arg index: A comma-separated list of indices to restrict the results
        :arg doc_type: A comma-separated list of types to restrict the results
@@ -415,7 +419,7 @@ class Elasticsearch(object):
    def bulk(self, body, index=None, doc_type=None, params=None):
        """
        Perform many index/delete operations in a single API call.
-        http://elasticsearch.org/guide/reference/api/bulk/
+        `<http://elasticsearch.org/guide/reference/api/bulk/>`_

        :arg body: The operation definition and data (action-data pairs)
        :arg index: Default index for items which don't provide one
@@ -433,7 +437,7 @@ class Elasticsearch(object):
    def msearch(self, body, index=None, doc_type=None, params=None):
        """
        Execute several search requests within the same API.
-        http://www.elasticsearch.org/guide/reference/api/multi-search/
+        `<http://www.elasticsearch.org/guide/reference/api/multi-search/>`_

        :arg body: The request definitions (metadata-search request definition
            pairs), separated by newlines
@@ -449,7 +453,7 @@ class Elasticsearch(object):
    def delete_by_query(self, index, doc_type=None, body=None, params=None):
        """
        Delete documents from one or more indices and one or more types based on a query.
-        http://www.elasticsearch.org/guide/reference/api/delete-by-query/
+        `<http://www.elasticsearch.org/guide/reference/api/delete-by-query/>`_

        :arg index: A comma-separated list of indices to restrict the operation
        :arg doc_type: A comma-separated list of types to restrict the operation
@@ -471,7 +475,7 @@ class Elasticsearch(object):
        """
        The suggest feature suggests similar looking terms based on a provided
        text by using a suggester.
-        http://elasticsearch.org/guide/reference/api/search/suggest/
+        `<http://elasticsearch.org/guide/reference/api/search/suggest/>`_

        :arg index: A comma-separated list of index names to restrict the operation;
            use `_all` or empty string to perform the operation on all indices
@@ -492,7 +496,7 @@ class Elasticsearch(object):
        """
        Send a percolate request which include a doc, and get back the queries
        that match on that doc out of the set of registered queries.
-        http://elasticsearch.org/guide/reference/api/percolate/
+        `<http://elasticsearch.org/guide/reference/api/percolate/>`_

        :arg index: The name of the index with a registered percolator query
        :arg doc_type: The document type
@@ -513,7 +517,7 @@ class Elasticsearch(object):
    def mlt(self, index, doc_type, id, body=None, params=None):
        """
        Get documents that are "like" a specified document.
-        http://elasticsearch.org/guide/reference/api/more-like-this/
+        `<http://elasticsearch.org/guide/reference/api/more-like-this/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document (use `_all` to fetch the first
@@ -558,7 +562,7 @@ class Elasticsearch(object):
        """
        Computes a score explanation for a query and a specific document and
        presents the calculation.
-        http://elasticsearch.org/guide/reference/api/explain/
+        `<http://elasticsearch.org/guide/reference/api/explain/>`_

        :arg index: The name of the index
        :arg doc_type: The type of the document
@@ -7,7 +7,7 @@ class ClusterClient(NamespacedClient):
    def health(self, index=None, params=None):
        """
        Get a very simple status on the health of the cluster.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-health/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-health/>`_

        :arg index: Limit the information returned to a specific index
        :arg level: Specify the level of detail for returned information, default u'cluster'
@@ -29,7 +29,7 @@ class ClusterClient(NamespacedClient):
    def state(self, params=None):
        """
        Get a comprehensive state information of the whole cluster.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-state/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-state/>`_

        :arg filter_blocks: Do not return information about blocks
        :arg filter_index_templates: Do not return information about index templates
@@ -48,7 +48,7 @@ class ClusterClient(NamespacedClient):
    def reroute(self, body=None, params=None):
        """
        Explicitly execute a cluster reroute allocation command including specific commands.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-reroute/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-reroute/>`_

        :arg body: The definition of `commands` to perform (`move`, `cancel`, `allocate`)
        :arg dry_run: Simulate the operation only and return the resulting state
@@ -61,7 +61,7 @@ class ClusterClient(NamespacedClient):
    def get_settings(self, params=None):
        """
        Get cluster settings.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/>`_
        """
        _, data = self.transport.perform_request('GET', '/_cluster/settings', params=params)
        return data
@@ -70,7 +70,7 @@ class ClusterClient(NamespacedClient):
    def put_settings(self, body, params=None):
        """
        Update cluster wide specific settings.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-update-settings/>`_

        :arg body: The settings to be updated. Can be either `transient` or
            `persistent` (survives cluster restart).
@@ -83,7 +83,7 @@ class ClusterClient(NamespacedClient):
    def node_stats(self, node_id=None, metric=None, fields=None, params=None):
        """
        Retrieve one or more (or all) of the cluster nodes statistics.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-stats/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-stats/>`_

        :arg node_id: A comma-separated list of node IDs or names to limit the
            returned information; use `_local` to return information from the node
@@ -113,7 +113,7 @@ class ClusterClient(NamespacedClient):
    def node_info(self, node_id=None, params=None):
        """
        Retrieve one or more (or all) of the cluster nodes' information.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-info/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-info/>`_

        :arg node_id: A comma-separated list of node IDs or names to limit the
            returned information; use `_local` to return information from the node
@@ -139,7 +139,7 @@ class ClusterClient(NamespacedClient):
    def node_shutdown(self, node_id=None, params=None):
        """
        Shutdown one or more (or all) nodes in the cluster.
-        http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-shutdown/
+        `<http://elasticsearch.org/guide/reference/api/admin-cluster-nodes-shutdown/>`_

        :arg node_id: A comma-separated list of node IDs or names to perform
            the operation on; use `_local` to perform the operation on the node
@@ -7,7 +7,7 @@ class IndicesClient(NamespacedClient):
    def analyze(self, index=None, body=None, params=None):
        """
        Perform the analysis process on a text and return the tokens breakdown of the text.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-analyze/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-analyze/>`_

        :arg index: The name of the index to scope the operation
        :arg body: The text on which the analysis should be performed
@@ -32,7 +32,7 @@ class IndicesClient(NamespacedClient):
        """
        Explicitly refresh one or more index, making all operations performed
        since the last refresh available for search.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-refresh/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-refresh/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -47,7 +47,7 @@ class IndicesClient(NamespacedClient):
    def flush(self, index=None, params=None):
        """
        Explicitly flush one or more indices.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-flush/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-flush/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string for all indices
@@ -65,7 +65,7 @@ class IndicesClient(NamespacedClient):
    def create(self, index, body=None, params=None):
        """
        Create an index in Elasticsearch.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index/>`_

        :arg index: The name of the index
        :arg body: The configuration for the index (`settings` and `mappings`)
@@ -80,7 +80,7 @@ class IndicesClient(NamespacedClient):
    def open(self, index, params=None):
        """
        Open a closed index to make it available for search.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/>`_

        :arg index: The name of the index
        :arg master_timeout: Specify timeout for connection to master
@@ -95,7 +95,7 @@ class IndicesClient(NamespacedClient):
        """
        Close an index to remove it's overhead from the cluster. Closed index
        is blocked for read/write operations.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/>`_

        :arg index: The name of the index
        :arg master_timeout: Specify timeout for connection to master
@@ -109,7 +109,7 @@ class IndicesClient(NamespacedClient):
    def delete(self, index=None, params=None):
        """
        Delete an index in Elasticsearch
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-index/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-index/>`_

        :arg index: A comma-separated list of indices to delete; use `_all` or
            empty string to delete all indices
@@ -124,7 +124,7 @@ class IndicesClient(NamespacedClient):
    def exists(self, index, params=None):
        """
        Return a boolean indicating whether given index exists.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-indices-exists/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-indices-exists/>`_

        :arg index: A list of indices to check
        """
@@ -138,7 +138,7 @@ class IndicesClient(NamespacedClient):
    def exists_type(self, index, doc_type, params=None):
        """
        Check if a type/types exists in an index/indices.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-types-exists/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-types-exists/>`_

        :arg index: A comma-separated list of index names; use `_all` to check
            the types across all indices
@@ -156,7 +156,7 @@ class IndicesClient(NamespacedClient):
    def snapshot_index(self, index=None, params=None):
        """
        Explicitly perform a snapshot through the gateway of one or more indices (backup them).
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-gateway-snapshot/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-gateway-snapshot/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string for all indices
@@ -171,7 +171,7 @@ class IndicesClient(NamespacedClient):
    def put_mapping(self, index, doc_type, body, params=None):
        """
        Register specific mapping definition for a specific type.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/>`_

        :arg index: A comma-separated list of index names; use `_all` to
            perform the operation on all indices
@@ -190,7 +190,7 @@ class IndicesClient(NamespacedClient):
    def get_mapping(self, index=None, doc_type=None, params=None):
        """
        Retrieve mapping definition of index or index/type.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-get-mapping/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-get-mapping/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string for all indices
@@ -204,7 +204,7 @@ class IndicesClient(NamespacedClient):
    def delete_mapping(self, index, doc_type, params=None):
        """
        Delete a mapping (type) along with its data.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-mapping/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-mapping/>`_

        :arg index: A comma-separated list of index names; use `_all` for all indices
        :arg doc_type: The name of the document type to delete
@@ -218,7 +218,7 @@ class IndicesClient(NamespacedClient):
    def put_alias(self, index, name, body=None, params=None):
        """
        Create an alias for a specific index/indices.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg index: The name of the index with an alias
        :arg name: The name of the alias to be created or updated
@@ -234,7 +234,7 @@ class IndicesClient(NamespacedClient):
    def exists_alias(self, name, index=None, params=None):
        """
        Return a boolean indicating whether given alias exists.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg name: A comma-separated list of alias names to return
        :arg index: A comma-separated list of index names to filter aliases
@@ -252,7 +252,7 @@ class IndicesClient(NamespacedClient):
    def get_alias(self, name, index=None, params=None):
        """
        Retrieve a specified alias.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg name: A comma-separated list of alias names to return
        :arg index: A comma-separated list of index names to filter aliases
@@ -267,7 +267,7 @@ class IndicesClient(NamespacedClient):
    def get_aliases(self, index=None, params=None):
        """
        Retrieve specified aliases
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg index: A comma-separated list of index names to filter aliases
        :arg timeout: Explicit operation timeout
@@ -280,7 +280,7 @@ class IndicesClient(NamespacedClient):
    def update_aliases(self, body, params=None):
        """
        Update specified aliases.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg body: The definition of `actions` to perform
        :arg master_timeout: Specify timeout for connection to master
@@ -294,7 +294,7 @@ class IndicesClient(NamespacedClient):
    def delete_alias(self, index, name, params=None):
        """
        Delete specific alias.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/>`_

        :arg index: The name of the index with an alias
        :arg name: The name of the alias to be deleted
@@ -310,7 +310,7 @@ class IndicesClient(NamespacedClient):
        """
        Create an index template that will automatically be applied to new
        indices created.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/>`_

        :arg name: The name of the template
        :arg body: The template definition
@@ -327,7 +327,7 @@ class IndicesClient(NamespacedClient):
    def get_template(self, name, params=None):
        """
        Retrieve an index template by its name.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/>`_

        :arg name: The name of the template
        """
@@ -339,7 +339,7 @@ class IndicesClient(NamespacedClient):
    def delete_template(self, name, params=None):
        """
        Delete an index template by its name.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-templates/>`_

        :arg name: The name of the template
        :arg master_timeout: Specify timeout for connection to master
@@ -353,7 +353,7 @@ class IndicesClient(NamespacedClient):
    def get_settings(self, index=None, params=None):
        """
        Retrieve settings for one or more (or all) indices.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-get-settings/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-get-settings/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -366,7 +366,7 @@ class IndicesClient(NamespacedClient):
    def put_settings(self, body, index=None, params=None):
        """
        Change specific index level settings in real time.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -382,7 +382,7 @@ class IndicesClient(NamespacedClient):
        """
        Create an index warmer to run registered search requests to warm up the
        index before it is available for search.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/>`_

        :arg index: A comma-separated list of index names to register the warmer for;
            use `_all` or empty string to perform the operation on all indices
@@ -400,7 +400,7 @@ class IndicesClient(NamespacedClient):
    def get_warmer(self, index, doc_type=None, name=None, params=None):
        """
        Retreieve an index warmer.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/>`_

        :arg index: A comma-separated list of index names to restrict the
            operation; use `_all` to perform the operation on all indices
@@ -415,7 +415,7 @@ class IndicesClient(NamespacedClient):
    def delete_warmer(self, index, doc_type=None, name=None, params=None):
        """
        Delete an index warmer.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-warmers/>`_

        :arg index: A comma-separated list of index names to register warmer
            for; use `_all` or empty string to perform the operation on all indices
@@ -432,7 +432,7 @@ class IndicesClient(NamespacedClient):
    def status(self, index=None, params=None):
        """
        Get a comprehensive status information of one or more indices.
-        http://elasticsearch.org/guide/reference/api/admin-indices-_/
+        `<http://elasticsearch.org/guide/reference/api/admin-indices-_/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -452,7 +452,7 @@ class IndicesClient(NamespacedClient):
    def stats(self, index=None, metric_family=None, params=None):
        """
        Retrieve statistics on different operations happening on an index.
-        http://elasticsearch.org/guide/reference/api/admin-indices-stats/
+        `<http://elasticsearch.org/guide/reference/api/admin-indices-stats/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -486,7 +486,7 @@ class IndicesClient(NamespacedClient):
    def segments(self, index=None, params=None):
        """
        Provide low level segments information that a Lucene index (shard level) is built with.
-        http://elasticsearch.org/guide/reference/api/admin-indices-segments/
+        `<http://elasticsearch.org/guide/reference/api/admin-indices-segments/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -502,7 +502,7 @@ class IndicesClient(NamespacedClient):
    def optimize(self, index=None, params=None):
        """
        Explicitly optimize one or more indices through an API.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-optimize/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-optimize/>`_

        :arg index: A comma-separated list of index names; use `_all` or empty
            string to perform the operation on all indices
@@ -527,7 +527,7 @@ class IndicesClient(NamespacedClient):
    def validate_query(self, index=None, doc_type=None, body=None, params=None):
        """
        Validate a potentially expensive query without executing it.
-        http://www.elasticsearch.org/guide/reference/api/validate/
+        `<http://www.elasticsearch.org/guide/reference/api/validate/>`_

        :arg index: A comma-separated list of index names to restrict the operation;
            use `_all` or empty string to perform the operation on all indices
@@ -552,7 +552,7 @@ class IndicesClient(NamespacedClient):
    def clear_cache(self, index=None, params=None):
        """
        Clear either all caches or specific cached associated with one ore more indices.
-        http://www.elasticsearch.org/guide/reference/api/admin-indices-clearcache/
+        `<http://www.elasticsearch.org/guide/reference/api/admin-indices-clearcache/>`_

        :arg index: A comma-separated list of index name to limit the operation
        :arg field_data: Clear field data
@@ -11,7 +11,7 @@ from ..exceptions import ConnectionError

 class RequestsHttpConnection(Connection):
    """ Connection using the `requests` library. """
-    def __init__(self, **kwargs):
+    def __init__(self, host='localhost', port=9200, url_prefix='', timeout=10, **kwargs):
        super(RequestsHttpConnection, self).__init__(**kwargs)
        self.session = requests.session()

@@ -39,7 +39,10 @@ class RequestsHttpConnection(Connection):
        return response.status_code, raw_data

 class Urllib3HttpConnection(Connection):
-    def __init__(self, host='localhost', port=9200, **kwargs):
+    """
+    Default connection class using the `urllib3` library and the http protocol.
+    """
+    def __init__(self, host='localhost', port=9200, url_prefix='', timeout=10, **kwargs):
        super(Urllib3HttpConnection, self).__init__(host=host, port=port, **kwargs)
        self.pool = urllib3.HTTPConnectionPool(host, port=port, timeout=kwargs.get('timeout', None))

@@ -9,6 +9,12 @@ from ..exceptions import TransportError, ConnectionError, ImproperlyConfigured
 from .pooling import PoolingConnection

 class MemcachedConnection(PoolingConnection):
+    """
+    Client using the `pylibmc` python library to communicate with elasticsearch
+    using the memcached protocol. Requires plugin in the cluster.
+
+    See https://github.com/elasticsearch/elasticsearch-transport-memcached for more details.
+    """
    transport_schema = 'memcached'

    method_map = {
@@ -16,9 +16,18 @@ from ..exceptions import ConnectionError, ImproperlyConfigured
 from .pooling import PoolingConnection

 class ThriftConnection(PoolingConnection):
+    """
+    Connection using the `thrift` protocol to communicate with elasticsearch.
+
+    See https://github.com/elasticsearch/elasticsearch-transport-thrift for additional info.
+    """
    transport_schema = 'thrift'

    def __init__(self, host='localhost', port=9500, framed_transport=False, **kwargs):
+        """
+        :arg framed_transport: use `TTransport.TFramedTransport` instead of
+            `TTransport.TBufferedTransport`
+        """
        if not THRIFT_AVAILABLE:
            raise ImproperlyConfigured("Thrift is not available.")