Add Query.enable_single_entity()

Added new feature :meth:`.Query.only_return_tuples`.  Causes the
:class:`.Query` object to return keyed tuple objects unconditionally even
if the query is against a single entity.   Pull request courtesy Eric
Atkin.

Change-Id: Ib0b7f5f78431aa68082e5b200ed577daa4222336
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/425

diff --git a/doc/build/changelog/unreleased_12/single_entity.rst b/doc/build/changelog/unreleased_12/single_entity.rst
new file mode 100644 (file)
index 0000000..3eb7e56
--- /dev/null
+++ b/doc/build/changelog/unreleased_12/single_entity.rst
@@ -0,0 +1,9 @@
+.. change::
+    :tags: feature, orm
+    :versions: 1.3.0b1
+
+    Added new feature :meth:`.Query.only_return_tuples`.  Causes the
+    :class:`.Query` object to return keyed tuple objects unconditionally even
+    if the query is against a single entity.   Pull request courtesy Eric
+    Atkin.
+

diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
index 2628093e01c02024c2bb2ba11485407b734c8d7e..3599aa3e74d7bbfe88312045a39ba89b6f99f568 100644 (file)
--- a/lib/sqlalchemy/orm/loading.py
+++ b/lib/sqlalchemy/orm/loading.py
@@ -37,7 +37,8 @@ def instances(query, cursor, context):
 
     filtered = query._has_mapper_entities
 
-    single_entity = len(query._entities) == 1 and \
+    single_entity = not query._only_return_tuples and \
+        len(query._entities) == 1 and \
         query._entities[0].supports_single_entity
 
     if filtered:

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 1e7f8a2666bef0b6cd04f8356bb3686128e7bef0..043be55397dd9127050efa2d99fd0dddffbd6c0a 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -70,6 +70,7 @@ class Query(object):
 
     """
 
+    _only_return_tuples = False
     _enable_eagerloads = True
     _enable_assertions = True
     _with_labels = False
@@ -603,6 +604,16 @@ class Query(object):
     def __clause_element__(self):
         return self.enable_eagerloads(False).with_labels().statement
 
+    @_generative()
+    def only_return_tuples(self, value):
+        """When set to True, the query results will always be a tuple,
+        specifically for single element queries. The default is False.
+
+    .   .. versionadded:: 1.2.5
+
+        """
+        self._only_return_tuples = value
+
     @_generative()
     def enable_eagerloads(self, value):
         """Control whether or not eager joins and subqueries are

diff --git a/test/orm/test_query.py b/test/orm/test_query.py
index 502f1427a87013e82cc800ae012e0d6e9318dc59..ed2b17edc4f93c0ad80516b7a08e5331e3e2077d 100644 (file)
--- a/test/orm/test_query.py
+++ b/test/orm/test_query.py
@@ -47,6 +47,28 @@ class MiscTest(QueryTest):
         assert q1.session is s1
 
 
+class OnlyReturnTuplesTest(QueryTest):
+    def test_single_entity_false(self):
+        User = self.classes.User
+        row = create_session().query(User).only_return_tuples(False).first()
+        assert isinstance(row, User)
+
+    def test_single_entity_true(self):
+        User = self.classes.User
+        row = create_session().query(User).only_return_tuples(True).first()
+        assert isinstance(row, tuple)
+
+    def test_multiple_entity_false(self):
+        User = self.classes.User
+        row = create_session().query(User.id, User).only_return_tuples(False).first()
+        assert isinstance(row, tuple)
+
+    def test_multiple_entity_true(self):
+        User = self.classes.User
+        row = create_session().query(User.id, User).only_return_tuples(True).first()
+        assert isinstance(row, tuple)
+
+
 class RowTupleTest(QueryTest):
     run_setup_mappers = None