From 0f613eb1d487d8afcf7c881d29299f21497f389a Mon Sep 17 00:00:00 2001
From: Honza Kral <honza.kral@gmail.com>
Date: Sun, 12 May 2013 19:56:07 +0200
Subject: [PATCH] More extensive README

---
 README.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 54 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index 6232131f..16552995 100644
--- a/README.rst
+++ b/README.rst
@@ -1,16 +1,60 @@
 Python Elasticsearch Client
 ===========================
 
-   Copyright 2013 Elasticsearch
+Official low-level client for Elasticsearch. It's goal is to provide common
+ground for all Elasticsearch-related code in Python; because of this it tries
+to be opinion-free and very extendable.
 
-   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
+Example use
+-----------
 
-   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.
+Simple use-case::
+
+    >>> from datetime import datetime
+    >>> from elasticsearch import Elasticsearch
+
+    # by default we connect to localhost:9200
+    >>> es = Elasticsearch()
+
+    # datetimes will be serialized
+    >>> es.index("my-index", "test-type", {"any": "data", "timestamp": datetime.now()}, id=42)
+    {u'_id': u'42', u'_index': u'my-index', u'_type': u'test-type', u'_version': 1, u'ok': True}
+
+    # but not deserialized
+    >>> es.get("my-index", 42, doc_type="test-type")['_source']
+    {u'any': u'data', u'timestamp': u'2013-05-12T19:45:31.804229'}
+
+
+Features
+--------
+
+The client's features include:
+
+ * translating basic Python data types to and from json (datetimes are not
+   decoded for performance reasons)
+ * configurable automatic discovery of cluster nodes
+ * persistent connections
+ * load balancing (with pluggable selection strategy) across all availible nodes
+ * failed connection penalization (time based - failed connections won't be
+   retried until a timeout is reached)
+ * thread safety
+ * pluggable architecture
+
+
+License
+-------
+
+Copyright 2013 Elasticsearch
+
+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.