diff options
| -rw-r--r-- | doc/build/compile_docstrings.py | 6 | ||||
| -rw-r--r-- | doc/build/content/plugins.txt | 3 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/selectresults.py | 21 | ||||
| -rw-r--r-- | lib/sqlalchemy/mods/threadlocal.py | 2 |
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) |