Allow aliased() to be passed to Query.select_entity_from().

An :func:`.aliased()` construct can now be passed to the
:meth:`.Query.select_entity_from` method.   Entities will be pulled
from the selectable represented by the :func:`.aliased` construct.
This allows special options for :func:`.aliased` such as
:paramref:`.aliased.adapt_on_names` to be used in conjunction with
:meth:`.Query.select_entity_from`.

Additionally rewrote the docstring for :meth:`.Query.select_entity_from`,
including starting with explicit use of :func:`.aliased` as the
usual idiomatic pattern.  An example using text().columns() is added
as well as the use case from :ticket:`3933` using name matching.

Change-Id: If7e182965236993064a2a086e3b6d55a4f097ca8
Fixes: #3933

1 files changed, 25 insertions, 0 deletions

diff --git a/test/orm/test_froms.py b/test/orm/test_froms.py
index 44d87822e..9bfa8e8eb 100644
--- a/test/orm/test_froms.py
+++ b/test/orm/test_froms.py
@@ -1852,6 +1852,31 @@ class SelectFromTest(QueryTest, AssertsCompiledSQL):
             options(joinedload('addresses')).first(),
             User(name='jack', addresses=[Address(id=1)]))
 
+    def test_select_from_aliased(self):
+        User, users = self.classes.User, self.tables.users
+
+        mapper(User, users)
+
+        sess = create_session()
+
+        not_users = table('users', column('id'), column('name'))
+        ua = aliased(
+            User,
+            select([not_users]).alias(),
+            adapt_on_names=True
+        )
+
+        q = sess.query(User.name).select_entity_from(ua).order_by(User.name)
+        self.assert_compile(
+            q,
+            "SELECT anon_1.name AS anon_1_name FROM (SELECT users.id AS id, "
+            "users.name AS name FROM users) AS anon_1 ORDER BY anon_1.name"
+        )
+        eq_(
+            q.all(),
+            [('chuck',), ('ed',), ('fred',), ('jack',)]
+        )
+
     @testing.uses_deprecated("Mapper.order_by")
     def test_join_mapper_order_by(self):
         """test that mapper-level order_by is adapted to a selectable."""