More extensive README

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.
+Example use
-   You may obtain a copy of the License at
+-----------
+
+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
+Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
+distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
+See the License for the specific language governing permissions and
-   limitations under the License.
+limitations under the License.