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

3 files changed, 22 insertions, 23 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
diff --git a/test/orm/test_froms.py b/test/orm/test_froms.py
index 4246df1f6..b4260674d 100644
--- a/test/orm/test_froms.py
+++ b/test/orm/test_froms.py
@@ -1,6 +1,7 @@
 from sqlalchemy import testing
 from sqlalchemy.testing import (
-    fixtures, eq_, assert_raises, assert_raises_message, AssertsCompiledSQL)
+    fixtures, eq_, is_, assert_raises,
+    assert_raises_message, AssertsCompiledSQL)
 from sqlalchemy import (
     exc as sa_exc, util, Integer, Table, String, ForeignKey, select, func,
     and_, asc, desc, inspect, literal_column, cast, exists, text)
@@ -1737,8 +1738,8 @@ class MixedEntitiesTest(QueryTest, AssertsCompiledSQL):
                 "ON users.id = addresses_1.user_id"),
         ]:
             q = s.query(crit)
-            mzero = q._mapper_zero()
-            assert mzero.mapped_table is q._entity_zero().selectable
+            mzero = q._entity_zero()
+            is_(mzero.mapped_table, q._query_entity_zero().selectable)
             q = q.join(j)
             self.assert_compile(q, exp)
 
@@ -1761,8 +1762,8 @@ class MixedEntitiesTest(QueryTest, AssertsCompiledSQL):
                 "ON users_1.id = addresses_1.user_id")
         ]:
             q = s.query(crit)
-            mzero = q._mapper_zero()
-            assert inspect(mzero).selectable is q._entity_zero().selectable
+            mzero = q._entity_zero()
+            is_(inspect(mzero).selectable, q._query_entity_zero().selectable)
             q = q.join(j)
             self.assert_compile(q, exp)
 
diff --git a/test/orm/test_query.py b/test/orm/test_query.py
index cdc4ac2c2..d79de1d96 100644
--- a/test/orm/test_query.py
+++ b/test/orm/test_query.py
@@ -805,7 +805,7 @@ class InvalidGenerationsTest(QueryTest, AssertsCompiledSQL):
             text("select * from table"))
         assert_raises(sa_exc.InvalidRequestError, q.with_polymorphic, User)
 
-    def test_mapper_zero(self):
+    def test_only_full_mapper_zero(self):
         User, Address = self.classes.User, self.classes.Address
 
         s = create_session()