Documentation tweaks

Author: honzakral

README.rst

@@ -54,7 +54,7 @@ With the low-level client you would write something like this:
     for hit in response['hits']['hits']:
         print(hit['_score'], hit['_source']['title'])
 
-Which would be very hard to modify (imagine adding another filter to that
+Which could be very hard to modify (imagine adding another filter to that
 query) and is definitely no fun to write. With the python DSL you can write the
 same query as:
 
@@ -85,7 +85,7 @@ Or, if you want to have absolute control over your queries:
 
 The library will take care of:
 
-  * composing queries/filters into ``bool`` queries/filters
+  * composing queries/filters into compound queries/filters
 
   * creating filtered queries when ``.filter()`` has been used
 
@@ -106,10 +106,10 @@ with it and, at the end, serialize it back to dict to send over the wire:
 
     body = {...} # insert complicated query here
     # convert to search
-    s = Search.from_dict()
+    s = Search.from_dict(body)
     # add some filters, aggregations, queries, ...
     s.filter("term", tags="python")
-    # convert back to dict to plug back into existing code
+    # optionally convert back to dict to plug back into existing code
     body = s.to_dict()
 
 Since the DSL is built on top of the low-level client there should be nothing

elasticsearch_dsl/search.py

@@ -92,12 +92,11 @@ def __getitem__(self, n):
 
         Slicing equates to the from/size parameters. E.g.::
 
-            Search().query(...)[0:25]
+            s = Search().query(...)[0:25]
 
         is equivalent to::
 
-            {"query": ...
-             "from": 0, "size": 25}
+            s = Search().query(...).extra(from_=0, size=25)
 
         """
         s = self._clone()
@@ -130,6 +129,10 @@ def from_dict(cls, d):
         return s
 
     def _clone(self):
+        """
+        Return a clone of the current search request. Performs a shallow copy
+        of all the underlying objects. Used internally by most state modifying APIs.
+        """
         s = Search(using=self._using, index=self._index, doc_type=self._doc_type)
         s._sort = self._sort[:]
         s._extra = self._extra.copy()
@@ -143,6 +146,10 @@ def _clone(self):
         return s
 
     def update_from_dict(self, d):
+        """
+        Apply options from a serialized body to the current instance. Modifies
+        the object in-place.
+        """
         d = d.copy()
         self.query._proxied = Q(d.pop('query'))
         if 'post_filter' in d:
@@ -163,6 +170,10 @@ def update_from_dict(self, d):
         self._extra = d
 
     def params(self, **kwargs):
+        """
+        Specify query params to be used when executing the search. All the
+        keyword arguments will override the current values.
+        """
         s = self._clone()
         s._params.update(kwargs)
         return s
@@ -181,13 +192,13 @@ def sort(self, *keys):
         """
         Add sorting information to the search request. If called without
         arguments it will remove all sort requirements. Otherwise it will
-        replace them. Acceptable arguments are:
+        replace them. Acceptable arguments are::
 
             'some.field'
             '-some.other.fiels'
             {'different.field': {'any': 'dict'}}
 
-        so for example:
+        so for example::
 
             s = Search().sort(
                 'category',
@@ -225,6 +236,11 @@ def index(self, *index):
         return s
 
     def doc_type(self, *doc_type):
+        """
+        Set the type to search through. You can supply a single value or a
+        list. If no index is supplied (or an empty value) any information
+        stored on the instance will be erased.
+        """
         # .doc_type() resets
         s = self._clone()
         if not doc_type:
@@ -233,7 +249,13 @@ def doc_type(self, *doc_type):
             s._doc_type = (self._doc_type or []) + list(doc_type)
         return s
 
-    def to_dict(self, count=False, **kwargs):
+    def to_dict(self, count=False):
+        """
+        Serialize the search into the dictionary that will be sent over as the request's body.
+
+        :arg count: a flag to specify we are interested in a body for count -
+            no aggregations, no pagination bounds etc.
+        """
         if self.filter:
             d = {
               "query": {
@@ -257,15 +279,24 @@ def to_dict(self, count=False, **kwargs):
 
         if not count:
             d.update(self._extra)
-        d.update(kwargs)
         return d
 
     def using(self, client):
+        """
+        Associate the search request with an elasticsearch client. A fresh copy
+        will be returned with current instance remaining unchanged.
+
+        :arg client: and instance of ``elasticsearch.Elasticsearch`` to use
+        """
         s = self._clone()
         s._using = client
         return s
 
     def count(self):
+        """
+        Return the number of hits matching the query and filters. Note that
+        only the actual number is returned.
+        """
         if not self._using:
             raise #XXX
 
@@ -278,6 +309,10 @@ def count(self):
         )['count']
 
     def execute(self):
+        """
+        Execute the search and return an instance of ``Response`` wrapping all
+        the data.
+        """
         if not self._using:
             raise #XXX