Rename Query._mapper_zero() to Query._entity_zero()

To be more descriptive of the use of _mapper_zero(), rename
it to _entity_zero(), but also supply a new _mapper_zero() function
that more strictly returns a mapper.  The existing
_entity_zero() function is renamed to _query_entity_zero.
_only_mapper_zero() is removed as it isn't used.  Divide up the
existing calling functions to refer to the appropriate new method.

Change-Id: I8780c3235e87b4936c6daf64d9d299b22b6e1260
Fixes: #3608

1 files changed, 15 insertions, 17 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 4606c2ffb..34daa707f 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -285,15 +285,22 @@ class Query(object):
             replace
         )
 
-    def _entity_zero(self):
+    def _query_entity_zero(self):
+        """Return the first QueryEntity."""
         return self._entities[0]
 
     def _mapper_zero(self):
-        # TODO: self._select_from_entity is not a mapper
-        # so this method is misnamed
+        """return the Mapper associated with the first QueryEntity."""
+        return self._entities[0].mapper
+
+    def _entity_zero(self):
+        """Return the 'entity' (mapper or AliasedClass) associated
+        with the first QueryEntity, or alternatively the 'select from'
+        entity if specified."""
+
         return self._select_from_entity \
             if self._select_from_entity is not None \
-            else self._entity_zero().entity_zero
+            else self._query_entity_zero().entity_zero
 
     @property
     def _mapper_entities(self):
@@ -304,11 +311,11 @@ class Query(object):
     def _joinpoint_zero(self):
         return self._joinpoint.get(
             '_joinpoint_entity',
-            self._mapper_zero()
+            self._entity_zero()
         )
 
     def _bind_mapper(self):
-        ezero = self._mapper_zero()
+        ezero = self._entity_zero()
         if ezero is not None:
             insp = inspect(ezero)
             if not insp.is_clause_element:
@@ -316,15 +323,6 @@ class Query(object):
 
         return None
 
-    def _only_mapper_zero(self, rationale=None):
-        if len(self._entities) > 1:
-            raise sa_exc.InvalidRequestError(
-                rationale or
-                "This operation requires a Query "
-                "against a single mapper."
-            )
-        return self._mapper_zero()
-
     def _only_full_mapper_zero(self, methname):
         if self._entities != [self._primary_entity]:
             raise sa_exc.InvalidRequestError(
@@ -945,7 +943,7 @@ class Query(object):
         """
 
         if property is None:
-            mapper_zero = inspect(self._mapper_zero()).mapper
+            mapper_zero = self._mapper_zero()
 
             mapper = object_mapper(instance)
 
@@ -1158,7 +1156,7 @@ class Query(object):
             statement.correlate(None)
         q = self._from_selectable(fromclause)
         q._enable_single_crit = False
-        q._select_from_entity = self._mapper_zero()
+        q._select_from_entity = self._entity_zero()
         if entities:
             q._set_entities(entities)
         return q