From e55e749e182e257fcc60db383751d5afbe52ddfb Mon Sep 17 00:00:00 2001
From: Patrick Hayes <pfhayes@gmail.com>
Date: Thu, 24 Oct 2019 10:11:52 -0400
Subject: Add public accessor `is_single_entity` to Query

Added accessor :attr:`.Query.is_single_entity` to :class:`.Query`, which
will indicate if the results returned by this :class:`.Query` will be a
list of ORM entities, or a tuple of entities or column expressions.
SQLAlchemy hopes to improve upon the behavior of single entity / tuples in
future releases such that the behavior would be explicit up front, however
this attribute should be helpful with the current behavior.  Pull request
courtesy Patrick Hayes.

Fixes: #4934
Closes: #4935
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4935
Pull-request-sha: 98f72b40a896761a65b048cc3722ff2dac4cf2b1

Change-Id: If5db5db3ea46a93406d76ef90b5b588149ba2986
---
 lib/sqlalchemy/orm/loading.py |  6 +-----
 lib/sqlalchemy/orm/query.py   | 32 +++++++++++++++++++++++++++++---
 2 files changed, 30 insertions(+), 8 deletions(-)

(limited to 'lib/sqlalchemy')

diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
index 8de7d5a8b..25ba8a398 100644
--- a/lib/sqlalchemy/orm/loading.py
+++ b/lib/sqlalchemy/orm/loading.py
@@ -42,11 +42,7 @@ def instances(query, cursor, context):
 
     filtered = query._has_mapper_entities
 
-    single_entity = (
-        not query._only_return_tuples
-        and len(query._entities) == 1
-        and query._entities[0].supports_single_entity
-    )
+    single_entity = query.is_single_entity
 
     if filtered:
         if single_entity:
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 92f9ee952..1a36349f3 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -640,14 +640,40 @@ class Query(Generative):
 
     @_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.
+        """When set to True, the query results will always be a tuple.
 
-    .   .. versionadded:: 1.2.5
+        This is specifically for single element queries. The default is False.
+
+        .. versionadded:: 1.2.5
+
+        .. seealso::
+
+            :meth:`.Query.is_single_entity`
 
         """
         self._only_return_tuples = value
 
+    @property
+    def is_single_entity(self):
+        """Indicates if this :class:`.Query` returns tuples or single entities.
+
+        Returns True if this query returns a single entity for each instance
+        in its result list, and False if this query returns a tuple of entities
+        for each result.
+
+        .. versionadded:: 1.3.11
+
+        .. seealso::
+
+            :meth:`.Query.only_return_tuples`
+
+        """
+        return (
+            not self._only_return_tuples
+            and len(self._entities) == 1
+            and self._entities[0].supports_single_entity
+        )
+
     @_generative
     def enable_eagerloads(self, value):
         """Control whether or not eager joins and subqueries are
-- 
cgit v1.2.1