selectresults docs

4 files changed, 28 insertions, 4 deletions

diff --git a/doc/build/compile_docstrings.py b/doc/build/compile_docstrings.py
index 191a5f4ec..119dbd85b 100644
--- a/doc/build/compile_docstrings.py
+++ b/doc/build/compile_docstrings.py
@@ -15,6 +15,7 @@ import sqlalchemy.exceptions as exceptions
 import sqlalchemy.ext.proxy as proxy
 import sqlalchemy.ext.sessioncontext as sessioncontext
 import sqlalchemy.mods.threadlocal as threadlocal
+import sqlalchemy.ext.selectresults as selectresults
 
 objects = []
 def make_doc(obj, classes=None, functions=None):
@@ -22,15 +23,16 @@ def make_doc(obj, classes=None, functions=None):
     
 make_doc(obj=sql, classes=[sql.Engine, sql.AbstractDialect, sql.ClauseParameters, sql.Compiled, sql.ClauseElement, sql.TableClause, sql.ColumnClause])
 make_doc(obj=schema)
-make_doc(obj=engine, classes=[engine.ComposedSQLEngine, engine.Connection, engine.Transaction, engine.Dialect, engine.ConnectionProvider, engine.ExecutionContext, engine.ResultProxy, engine.RowProxy])
+make_doc(obj=engine, classes=[engine.Connectable, engine.ComposedSQLEngine, engine.Connection, engine.Transaction, engine.Dialect, engine.ConnectionProvider, engine.ExecutionContext, engine.ResultProxy, engine.RowProxy])
 make_doc(obj=strategies)
 make_doc(obj=orm, classes=[orm.Mapper, orm.MapperExtension])
 make_doc(obj=orm.query, classes=[orm.query.Query])
 make_doc(obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction])
+make_doc(obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool])
 make_doc(obj=sessioncontext)
 make_doc(obj=threadlocal)
+make_doc(obj=selectresults)
 make_doc(obj=exceptions)
-make_doc(obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool])
 make_doc(obj=proxy)
 
 
diff --git a/doc/build/content/plugins.txt b/doc/build/content/plugins.txt
index cb1707758..9012c89fd 100644
--- a/doc/build/content/plugins.txt
+++ b/doc/build/content/plugins.txt
@@ -292,7 +292,7 @@ The `ProxyEngine` is used to "wrap" an `Engine`, and via subclassing `ProxyEngin
 
 **Author:** Jonas Borgström
 
-SelectResults gives generator-like behavior to the results returned from the `select` and `select_by` method of `Query`.  It supports three modes of operation; per-query, per-mapper, and per-application.
+SelectResults gives transformative behavior to the results returned from the `select` and `select_by` method of `Query`.  It supports three modes of operation; per-query, per-mapper, and per-application.
 
     {python title="SelectResults with a Query Object"}
     from sqlalchemy.ext.selectresults import SelectResults
@@ -326,3 +326,4 @@ Or across an application via the `selectresults` mod:
     mapper(MyClass, mytable)
     session.query(MyClass).select(mytable.c.column=="something").order_by([mytable.c.column])[2:7]
     
+For a full listing of methods, see the [generated documentation](rel:docstrings_sqlalchemy.ext.selectresults).
\ No newline at end of file
diff --git a/lib/sqlalchemy/ext/selectresults.py b/lib/sqlalchemy/ext/selectresults.py
index 5ba9153dd..17e92ef32 100644
--- a/lib/sqlalchemy/ext/selectresults.py
+++ b/lib/sqlalchemy/ext/selectresults.py
@@ -1,9 +1,10 @@
 import sqlalchemy.sql as sql
-
 import sqlalchemy.orm as orm
 
 
 class SelectResultsExt(orm.MapperExtension):
+    """a MapperExtension that provides SelectResults functionality for the 
+    results of query.select_by() and query.select()"""
     def select_by(self, query, *args, **params):
         return SelectResults(query, query.join_by(*args, **params))
     def select(self, query, arg=None, **kwargs):
@@ -13,47 +14,65 @@ class SelectResultsExt(orm.MapperExtension):
             return SelectResults(query, arg, ops=kwargs)
 
 class SelectResults(object):
+    """Builds a query one component at a time via separate method calls, 
+    each call transforming the previous SelectResults instance into a new SelectResults 
+    instance with further limiting criterion added. When interpreted
+    in an iterator context (such as via calling list(selectresults)), executes the query."""
+    
     def __init__(self, query, clause=None, ops={}):
+        """constructs a new SelectResults using the given Query object and optional WHERE 
+        clause.  ops is an optional dictionary of bind parameter values."""
         self._query = query
         self._clause = clause
         self._ops = {}
         self._ops.update(ops)
 
     def count(self):
+        """executes the SQL count() function against the SelectResults criterion."""
         return self._query.count(self._clause)
     
     def min(self, col):
+        """executes the SQL min() function against the given column"""
         return sql.select([sql.func.min(col)], self._clause, **self._ops).scalar()
 
     def max(self, col):
+        """executes the SQL max() function against the given column"""
         return sql.select([sql.func.max(col)], self._clause, **self._ops).scalar()
 
     def sum(self, col):
+        """executes the SQL sum() function against the given column"""
         return sql.select([sql.func.sum(col)], self._clause, **self._ops).scalar()
 
     def avg(self, col):
+        """executes the SQL avg() function against the given column"""
         return sql.select([sql.func.avg(col)], self._clause, **self._ops).scalar()
 
     def clone(self):
+        """creates a copy of this SelectResults."""
         return SelectResults(self._query, self._clause, self._ops.copy())
         
     def filter(self, clause):
+        """applies an additional WHERE clause against the query."""
         new = self.clone()
         new._clause = sql.and_(self._clause, clause)
         return new
 
     def order_by(self, order_by):
+        """applies an ORDER BY to the query."""
         new = self.clone()
         new._ops['order_by'] = order_by
         return new
 
     def limit(self, limit):
+        """applies a LIMIT to the query."""
         return self[:limit]
 
     def offset(self, offset):
+        """applies an OFFSET to the query."""
         return self[offset:]
 
     def list(self):
+        """returns the results represented by this SelectResults as a list.  this results in an execution of the underlying query."""
         return list(self)
         
     def __getitem__(self, item):
diff --git a/lib/sqlalchemy/mods/threadlocal.py b/lib/sqlalchemy/mods/threadlocal.py
index 6f122a409..f96bb5649 100644
--- a/lib/sqlalchemy/mods/threadlocal.py
+++ b/lib/sqlalchemy/mods/threadlocal.py
@@ -20,6 +20,8 @@ Note: this mod creates a global, thread-local session context named sqlalchemy.o
 while this mod is installed will reference this global context when creating new mapped object instances.
 """
 
+__all__ = ['Objectstore', 'assign_mapper']
+
 class Objectstore(SessionContext):
     def __getattr__(self, key):
         return getattr(self.current, key)