From 1eec99f8ab92ab29b776d17a0b49a9406be7e0d2 Mon Sep 17 00:00:00 2001
From: Eric Atkin <eatkin@certusllc.us>
Date: Wed, 28 Feb 2018 16:00:38 -0500
Subject: [PATCH] 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
(cherry picked from commit 451f81ef53a8065db20257af2a4a245196cc07d9)
---
 .../changelog/unreleased_12/single_entity.rst |  9 ++++++++
 lib/sqlalchemy/orm/loading.py                 |  3 ++-
 lib/sqlalchemy/orm/query.py                   | 11 ++++++++++
 test/orm/test_query.py                        | 22 +++++++++++++++++++
 4 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 doc/build/changelog/unreleased_12/single_entity.rst

diff --git a/doc/build/changelog/unreleased_12/single_entity.rst b/doc/build/changelog/unreleased_12/single_entity.rst
new file mode 100644
index 0000000000..3eb7e56449
--- /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 2628093e01..3599aa3e74 100644
--- 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 1e7f8a2666..043be55397 100644
--- 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 502f1427a8..ed2b17edc4 100644
--- 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
 
-- 
2.47.2