20. Adds group_by

Fixes #20.

README.rst

@@ -113,6 +113,15 @@ following attributes:
     * ``excerpt_after_match`` -- text to go after an exceprt
     * ``excerpt_limit`` -- limit of characters in an excerpt
 
+``group_by``
+
+    Tuple of (field to group on, sort order).
+
+    Examples::
+
+        group_by = ('a', '@group')
+        group_by = ('a', '-@group')
+
 
 Other Behavior Notes
 ====================

oedipus/__init__.py

@@ -233,6 +233,18 @@ def order_by(self, *fields):
         """
         return self._clone(next_step=('order_by', fields))
 
+    def group_by(self, attribute, groupsort='-@group'):
+        """Returns a new ``S`` with field grouping changed.
+
+        ``group_by()`` takes these arguments:
+
+        :param attribute: The attribute to group on.
+        :param groupsort: How the results in the final result set get
+            sorted.  e.g. ``@group``, ``-@group``
+
+        """
+        return self._clone(next_step=('group_by', (attribute, groupsort)))
+
     def values(self, *fields):
         """Return a new ``S`` whose results are returned as a list of tuples.
 
@@ -396,14 +408,19 @@ def _sphinx(self):
         # Loop over `self.steps` to build the query format that will be sent to
         # ElasticSearch, and returns it as a dict.
         query = sort = ''
+        try:
+            group_by = self.meta.group_by
+        except AttributeError:
+            group_by = None
         try:
             weights = dict(self.meta.weights)
         except AttributeError:
             weights = {}
-        # TODO: Something that calls SetGroupBy, perhaps
         for action, value in self.steps:
             if action == 'order_by':
                 sort = self._extended_sort_fields(value)
+            elif action == 'group_by':
+                group_by = value
             elif action == 'values':
                 self._fields = value
                 self._results_class = TupleResults
@@ -434,6 +451,10 @@ def _sphinx(self):
         # it all the time:
         sphinx.SetSortMode(sphinxapi.SPH_SORT_EXTENDED, sort)
 
+        if group_by is not None:
+            sphinx.SetGroupBy(group_by[0], sphinxapi.SPH_GROUPBY_ATTR,
+                              self._extended_sort_fields([group_by[1]]))
+
         # Add query. This must be done after filters and such are set up, or
         # they may not apply.
         self._query = query

oedipus/tests/test_groupby.py

@@ -0,0 +1,62 @@
+import fudge
+
+from oedipus import S
+from oedipus.tests import no_results, Biscuit, BaseSphinxMeta
+
+import sphinxapi
+
+
+class BiscuitWithGroupBy(object):
+    """Biscuit with default groupby"""
+
+    class SphinxMeta(BaseSphinxMeta):
+        group_by = ('a', '@group')
+
+
+@fudge.patch('sphinxapi.SphinxClient')
+def test_group_by(sphinx_client):
+    """Test group by."""
+    (sphinx_client.expects_call().returns_fake()
+                  .is_a_stub()
+                  .expects('SetGroupBy')
+                  .with_args('a', sphinxapi.SPH_GROUPBY_ATTR, '@group DESC')
+                  .expects('RunQueries')
+                  .returns(no_results))
+    S(Biscuit).group_by('a', '-@group')._raw()
+
+
+@fudge.patch('sphinxapi.SphinxClient')
+def test_group_by_asc(sphinx_client):
+    """Test group by ascending."""
+    (sphinx_client.expects_call().returns_fake()
+                  .is_a_stub()
+                  .expects('SetGroupBy')
+                  .with_args('a', sphinxapi.SPH_GROUPBY_ATTR, '@group ASC')
+                  .expects('RunQueries')
+                  .returns(no_results))
+    S(Biscuit).group_by('a', '@group')._raw()
+
+
+@fudge.patch('sphinxapi.SphinxClient')
+def test_group_by_override(sphinx_client):
+    """Test group by override."""
+    (sphinx_client.expects_call().returns_fake()
+                  .is_a_stub()
+                  .expects('SetGroupBy')
+                  .with_args('a', sphinxapi.SPH_GROUPBY_ATTR, '@group ASC')
+                  .expects('RunQueries')
+                  .returns(no_results))
+    # The second call overrides the first one.
+    S(Biscuit).group_by('b', '-@group').group_by('a', '@group')._raw()
+
+
+@fudge.patch('sphinxapi.SphinxClient')
+def test_group_by_sphinxmeta(sphinx_client):
+    """Test group by from SphinxMeta."""
+    (sphinx_client.expects_call().returns_fake()
+                  .is_a_stub()
+                  .expects('SetGroupBy')
+                  .with_args('a', sphinxapi.SPH_GROUPBY_ATTR, '@group ASC')
+                  .expects('RunQueries')
+                  .returns(no_results))
+    S(BiscuitWithGroupBy)._raw()