From: Priit Laes <plaes@plaes.org>
Date: Fri, 13 Jan 2012 14:03:41 +0000 (+0200)
Subject: Add some documentation sugar for ``having`` criterion.
X-Git-Tag: rel_0_8_0b1~436
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b5559d307039767f7aa961c537b985e56e81deaf;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add some documentation sugar for ``having`` criterion.
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 77d3cd2d33..103b0a7956 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1231,7 +1231,7 @@ class Query(object):
     @_generative(_no_statement_condition, _no_limit_offset)
     def group_by(self, *criterion):
         """apply one or more GROUP BY criterion to the query and return 
-        the newly resulting ``Query``"""
+        the newly resulting :class:`.Query`"""
 
         criterion = list(chain(*[_orm_columns(c) for c in criterion]))
 
@@ -1244,8 +1244,20 @@ class Query(object):
 
     @_generative(_no_statement_condition, _no_limit_offset)
     def having(self, criterion):
-        """apply a HAVING criterion to the query and return the 
-        newly resulting ``Query``."""
+        """apply a HAVING criterion to the query and return the
+        newly resulting :class:`.Query`.
+        
+        :meth:`having` is used in conjunction with :meth:`group_by`.
+ 
+        HAVING criterion makes it possible to use filters on aggregate
+        functions like COUNT, SUM, AVG, MAX, and MIN, eg.::
+ 
+            q = session.query(User.id).\\
+                        join(User.addresses).\\
+                        group_by(User.id).\\
+                        having(func.count(Address.id) > 2)
+ 
+        """
 
         if isinstance(criterion, basestring):
             criterion = sql.text(criterion)