From 8f15b4edc0d0b3206525b724fd48b4c0bf3d672c Mon Sep 17 00:00:00 2001
From: Honza Kral <honza.kral@gmail.com>
Date: Mon, 30 Sep 2013 18:59:27 +0200
Subject: [PATCH] Helpers documentation

---
 docs/helpers.rst         | 14 ++++++++++
 docs/index.rst           |  1 +
 elasticsearch/helpers.py | 58 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+)
 create mode 100644 docs/helpers.rst

diff --git a/docs/helpers.rst b/docs/helpers.rst
new file mode 100644
index 00000000..d6909853
--- /dev/null
+++ b/docs/helpers.rst
@@ -0,0 +1,14 @@
+Helpers
+=======
+
+Collection of simple helper functions that abstract some specifics or the raw
+API.
+
+
+.. py:module:: elasticsearch.helpers
+
+.. autofunction:: bulk_index
+
+.. autofunction:: scan
+
+.. autofunction:: reindex
diff --git a/docs/index.rst b/docs/index.rst
index d4edadc6..b8b6adab 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -77,6 +77,7 @@ Contents
    api
    connection
    transports
+   helpers
 
 License
 -------
diff --git a/elasticsearch/helpers.py b/elasticsearch/helpers.py
index e7dec2bb..51946872 100644
--- a/elasticsearch/helpers.py
+++ b/elasticsearch/helpers.py
@@ -1,6 +1,33 @@
 from itertools import islice
 
 def bulk_index(client, docs, chunk_size=500, **kwargs):
+    """
+    Helper for the :meth:`~elasticsearch.Elasticsearch.bulk` api that provides
+    a more human friendly interface - it consumes an iterator of documents and
+    sends them to elasticsearch in chunks.
+
+    This function expects the doc to be in the format as returned by
+    :meth:`~elasticsearch.Elasticsearch.search`, for example::
+
+        {
+            '_index': 'index-name',
+            '_type': 'document',
+            '_parent': '5',
+            '_ttl': '1d',
+            '_source': {
+                ...
+            }
+        }
+
+    alternatively, if `_source` is not present, it will pop all metadata fields
+    from the doc and use the rest as the document data.
+
+    :arg client: instance of :class:`~elasticsearch.Elasticsearch` to use
+    :arg docs: iterator containing the docs
+    :arg chunk_size: number of docs in one chunk sent to es (default: 500)
+
+    Any additional keyword arguments will be passed to the bulk API itself.
+    """
     success, failed = [], []
     docs = iter(docs)
     while True:
@@ -28,6 +55,19 @@ def bulk_index(client, docs, chunk_size=500, **kwargs):
                 failed.append(item)
 
 def scan(client, query=None, scroll='5m', **kwargs):
+    """
+    Simple abstraction on top of the
+    :meth:`~elasticsearch.Elasticsearch.scroll` api - a simple iterator that
+    yields all hits as returned by underlining scroll requests.
+
+    :arg client: instance of :class:`~elasticsearch.Elasticsearch` to use
+    :arg query: body for the :meth:`~elasticsearch.Elasticsearch.search` api
+    :arg scroll: Specify how long a consistent view of the index should be
+        maintained for scrolled search
+
+    Any additional keyword arguments will be passed to the initial
+    :meth:`~elasticsearch.Elasticsearch.search` call.
+    """
     # initial search to 
     resp = client.search(body=query, search_type='scan', scroll=scroll, **kwargs)
 
@@ -42,6 +82,24 @@ def scan(client, query=None, scroll='5m', **kwargs):
         scroll_id = resp['_scroll_id']
 
 def reindex(client, source_index, target_index, target_client=None, chunk_size=500, scroll='5m'):
+    """
+    Reindex all documents from one index to another, potentially (if
+    `target_client` is specified) on a different cluster.
+
+    .. note::
+
+        This helper doesn't transfer mappings, just the data.
+
+    :arg client: instance of :class:`~elasticsearch.Elasticsearch` to use (for
+        read if `target_client` is specified as well)
+    :arg source_index: index (or list of indices) to read documents from
+    :arg target_index: name of the index in the target cluster to populate
+    :arg target_client: optional, is specified will be used for writing (thus
+        enabling reindex between clusters)
+    :arg chunk_size: number of docs in one chunk sent to es (default: 500)
+    :arg scroll: Specify how long a consistent view of the index should be
+        maintained for scrolled search
+    """
     target_client = client if target_client is None else target_index
 
     docs = scan(client, index=source_index, scroll=scroll)