Replace with_labels() and apply_labels() in ORM/Core

Replace :meth:`_orm.Query.with_labels` and
:meth:`_sql.GenerativeSelect.apply_labels` with explicit getters and
setters ``get_label_style`` and ``set_label_style`` to accommodate the
three supported label styles: ``LABEL_STYLE_DISAMBIGUATE_ONLY`` (default),
``LABEL_STYLE_TABLENAME_PLUS_COL``, and ``LABEL_STYLE_NONE``.

In addition, for Core and "future style" ORM queries,
``LABEL_STYLE_DISAMBIGUATE_ONLY`` is now the default label style. This
style differs from the existing "no labels" style in that labeling is
applied in the case of column name conflicts; with ``LABEL_STYLE_NONE``, a
duplicate column name is not accessible via name in any case.

For legacy ORM queries using :class:`_query.Query`, the table-plus-column
names labeling style applied by ``LABEL_STYLE_TABLENAME_PLUS_COL``
continues to be used so that existing test suites and logging facilities
see no change in behavior by default, however this style of labeling is no
longer required for SQLAlchemy queries to function, as result sets are
commonly matched to columns using a positional approach since SQLAlchemy
1.0.

Within test suites, all use of apply_labels()  / use_labels
now uses the new methods.    New tests added to
test/sql/test_deprecations.py nad test/orm/test_deprecations.py
to cover just the old apply_labels() method call.  Tests
in ORM that made explicit use apply_labels()/ etc. where it isn't needed
for the ORM to work correctly use default label style now.

Co-authored-by: Mike Bayer <[email protected]>
Fixes: sqlalchemy#4757
Change-Id: I5fdcd2ed4ae8c7fe62f8be2b6d0e8f66409b6a54

Author: gordthompson

doc/build/changelog/unreleased_14/4757.rst

@@ -0,0 +1,29 @@
+.. change::
+    :tags: sql
+    :tickets: 4757
+
+    Replace :meth:`_orm.Query.with_labels` and
+    :meth:`_sql.GenerativeSelect.apply_labels` with explicit getters and
+    setters :meth:`_sql.GenerativeSelect.get_label_style` and
+    :meth:`_sql.GenerativeSelect.set_label_style` to accommodate the three
+    supported label styles: :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY`,
+    :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL`, and
+    :data:`_sql.LABEL_STYLE_NONE`.
+
+    In addition, for Core and "future style" ORM queries,
+    ``LABEL_STYLE_DISAMBIGUATE_ONLY`` is now the default label style. This
+    style differs from the existing "no labels" style in that labeling is
+    applied in the case of column name conflicts; with ``LABEL_STYLE_NONE``, a
+    duplicate column name is not accessible via name in any case.
+
+    For cases where labeling is significant, namely that the ``.c`` collection
+    of a subquery is able to refer to all columns unambiguously, the behavior
+    of ``LABEL_STYLE_DISAMBIGUATE_ONLY`` is now sufficient for all
+    SQLAlchemy features across Core and ORM which involve this behavior.
+    Result set rows since SQLAlchemy 1.0 are usually aligned with column
+    constructs positionally.
+
+    For legacy ORM queries using :class:`_query.Query`, the table-plus-column
+    names labeling style applied by ``LABEL_STYLE_TABLENAME_PLUS_COL``
+    continues to be used so that existing test suites and logging facilities
+    see no change in behavior by default.

doc/build/core/selectable.rst

@@ -145,3 +145,28 @@ The classes here are generated using the constructors listed at
 
 .. autoclass:: Values
    :members:
+
+Label Style Constants
+---------------------
+
+Constants used with the :meth:`_sql.GenerativeSelect.set_label_style`
+method.
+
+.. autodata:: LABEL_STYLE_DISAMBIGUATE_ONLY
+
+.. autodata:: LABEL_STYLE_NONE
+
+.. autodata:: LABEL_STYLE_TABLENAME_PLUS_COL
+
+.. data:: LABEL_STYLE_DEFAULT
+
+  The default label style, refers to :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY`.
+
+  .. versionadded:: 1.4
+
+  .. seealso::
+
+      :meth:`_sql.Select.set_label_style`
+
+      :meth:`_sql.Select.get_label_style`
+

doc/build/core/tutorial.rst

@@ -579,7 +579,7 @@ our :func:`_expression.select` statement:
 
     {sql}>>> for row in conn.execute(select(users, addresses)):
     ...     print(row)
-    SELECT users.id, users.name, users.fullname, addresses.id, addresses.user_id, addresses.email_address
+    SELECT users.id, users.name, users.fullname, addresses.id AS id_1, addresses.user_id, addresses.email_address
     FROM users, addresses
     [...] ()
     {stop}(1, u'jack', u'Jack Jones', 1, 1, u'[email protected]')
@@ -602,7 +602,7 @@ WHERE clause.  We do that using :meth:`_expression.Select.where`:
     >>> s = select(users, addresses).where(users.c.id == addresses.c.user_id)
     {sql}>>> for row in conn.execute(s):
     ...     print(row)
-    SELECT users.id, users.name, users.fullname, addresses.id,
+    SELECT users.id, users.name, users.fullname, addresses.id AS id_1,
        addresses.user_id, addresses.email_address
     FROM users, addresses
     WHERE users.id = addresses.user_id
@@ -1277,8 +1277,8 @@ by a column name that appears more than once:
     ...             order_by(u1a.c.name)  # using "name" here would be ambiguous
 
     {sql}>>> conn.execute(stmt).fetchall()
-    SELECT users_1.id, users_1.name, users_1.fullname, users_2.id,
-    users_2.name, users_2.fullname
+    SELECT users_1.id, users_1.name, users_1.fullname, users_2.id AS id_1,
+    users_2.name AS name_1, users_2.fullname AS fullname_1
     FROM users AS users_1, users AS users_2
     WHERE users_1.name > users_2.name ORDER BY users_1.name
     [...] ()
@@ -1597,7 +1597,7 @@ single named value is needed in the execute parameters:
     ...     select_from(users.outerjoin(addresses)).\
     ...     order_by(addresses.c.id)
     {sql}>>> conn.execute(s, {"name": "jack"}).fetchall()
-    SELECT users.id, users.name, users.fullname, addresses.id,
+    SELECT users.id, users.name, users.fullname, addresses.id AS id_1,
         addresses.user_id, addresses.email_address
     FROM users LEFT OUTER JOIN addresses ON users.id = addresses.user_id
     WHERE users.name LIKE ? || '%' OR addresses.email_address LIKE ? || '@%'

doc/build/tutorial/data.rst

@@ -879,7 +879,7 @@ below for example returns all unique pairs of user names::
     ...     select(user_alias_1.c.name, user_alias_2.c.name).
     ...     join_from(user_alias_1, user_alias_2, user_alias_1.c.id > user_alias_2.c.id)
     ... )
-    {opensql}SELECT user_account_1.name, user_account_2.name
+    {opensql}SELECT user_account_1.name, user_account_2.name AS name_1
     FROM user_account AS user_account_1
     JOIN user_account AS user_account_2 ON user_account_1.id > user_account_2.id
 

lib/sqlalchemy/__init__.py

@@ -54,6 +54,10 @@
 from .sql import intersect  # noqa
 from .sql import intersect_all  # noqa
 from .sql import join  # noqa
+from .sql import LABEL_STYLE_DEFAULT  # noqa
+from .sql import LABEL_STYLE_DISAMBIGUATE_ONLY  # noqa
+from .sql import LABEL_STYLE_NONE  # noqa
+from .sql import LABEL_STYLE_TABLENAME_PLUS_COL  # noqa
 from .sql import lambda_stmt  # noqa
 from .sql import lateral  # noqa
 from .sql import literal  # noqa

lib/sqlalchemy/orm/context.py

@@ -373,9 +373,11 @@ def create_for_statement(cls, statement_container, compiler, **kw):
         if (
             isinstance(statement, expression.SelectBase)
             and not statement._is_textual
-            and not statement.use_labels
+            and statement._label_style is util.symbol("LABEL_STYLE_NONE")
         ):
-            self.statement = statement.apply_labels()
+            self.statement = statement.set_label_style(
+                LABEL_STYLE_TABLENAME_PLUS_COL
+            )
         else:
             self.statement = statement
         self.order_by = None

lib/sqlalchemy/orm/loading.py

@@ -31,6 +31,7 @@
 from ..engine.result import FrozenResult
 from ..engine.result import SimpleResultMetaData
 from ..sql import util as sql_util
+from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
 
 _new_runid = util.counter()
 
@@ -1396,7 +1397,9 @@ def load_scalar_attributes(mapper, state, attribute_names, passive):
 
         result = load_on_ident(
             session,
-            future.select(mapper).apply_labels(),
+            future.select(mapper).set_label_style(
+                LABEL_STYLE_TABLENAME_PLUS_COL
+            ),
             identity_key,
             refresh_state=state,
             only_load_props=attribute_names,

lib/sqlalchemy/orm/mapper.py

@@ -54,6 +54,7 @@
 from ..sql import roles
 from ..sql import util as sql_util
 from ..sql import visitors
+from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
 from ..util import HasMemoized
 
 
@@ -3008,7 +3009,11 @@ def visit_binary(binary):
         cols = []
         for key in col_attribute_names:
             cols.extend(props[key].columns)
-        return sql.select(*cols).where(cond).apply_labels()
+        return (
+            sql.select(*cols)
+            .where(cond)
+            .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
+        )
 
     def _iterate_to_target_viawpoly(self, mapper):
         if self.isa(mapper):

lib/sqlalchemy/orm/persistence.py

@@ -40,6 +40,7 @@
 from ..sql.dml import DeleteDMLState
 from ..sql.dml import UpdateDMLState
 from ..sql.elements import BooleanClauseList
+from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
 
 
 def _bulk_insert(
@@ -1521,7 +1522,9 @@ def _finalize_insert_update_commands(base_mapper, uowtransaction, states):
 
         if toload_now:
             state.key = base_mapper._identity_key_from_state(state)
-            stmt = future.select(mapper).apply_labels()
+            stmt = future.select(mapper).set_label_style(
+                LABEL_STYLE_TABLENAME_PLUS_COL
+            )
             loading.load_on_ident(
                 uowtransaction.session,
                 stmt,

lib/sqlalchemy/orm/query.py

@@ -470,7 +470,7 @@ def subquery(
         """
         q = self.enable_eagerloads(False)
         if with_labels:
-            q = q.with_labels()
+            q = q.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
 
         q = q.statement
 
@@ -576,7 +576,11 @@ def scalar_subquery(self):
         return self.enable_eagerloads(False).statement.scalar_subquery()
 
     def __clause_element__(self):
-        return self.enable_eagerloads(False).with_labels().statement
+        return (
+            self.enable_eagerloads(False)
+            .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
+            .statement
+        )
 
     @_generative
     def only_return_tuples(self, value):
@@ -637,8 +641,27 @@ def enable_eagerloads(self, value):
         """
         self._compile_options += {"_enable_eagerloads": value}
 
-    @_generative
+    @util.deprecated_20(
+        ":meth:`_orm.Query.with_labels` and :meth:`_orm.Query.apply_labels`",
+        alternative="Use set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) "
+        "instead.",
+    )
     def with_labels(self):
+        return self.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
+
+    apply_labels = with_labels
+
+    @property
+    def get_label_style(self):
+        """
+        Retrieve the current label style.
+
+        .. versionadded:: 1.4
+
+        """
+        return self._label_style
+
+    def set_label_style(self, style):
         """Apply column labels to the return value of Query.statement.
 
         Indicates that this Query's `statement` accessor should return
@@ -650,26 +673,28 @@ def with_labels(self):
         When the `Query` actually issues SQL to load rows, it always
         uses column labeling.
 
-        .. note:: The :meth:`_query.Query.with_labels` method *only* applies
+        .. note:: The :meth:`_query.Query.set_label_style` method *only* applies
            the output of :attr:`_query.Query.statement`, and *not* to any of
            the result-row invoking systems of :class:`_query.Query` itself,
            e.g.
            :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
            To execute
-           a query using :meth:`_query.Query.with_labels`, invoke the
+           a query using :meth:`_query.Query.set_label_style`, invoke the
            :attr:`_query.Query.statement` using :meth:`.Session.execute`::
 
-                result = session.execute(query.with_labels().statement)
-
-
-        """
-        self._label_style = LABEL_STYLE_TABLENAME_PLUS_COL
+                result = session.execute(
+                    query
+                    .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
+                    .statement
+                )
 
-    apply_labels = with_labels
+        .. versionadded:: 1.4
 
-    @property
-    def use_labels(self):
-        return self._label_style is LABEL_STYLE_TABLENAME_PLUS_COL
+        """  # noqa
+        if self._label_style is not style:
+            self = self._generate()
+            self._label_style = style
+        return self
 
     @_generative
     def enable_assertions(self, value):
@@ -1259,7 +1284,7 @@ def from_self(self, *entities):
 
     def _from_self(self, *entities):
         fromclause = (
-            self.with_labels()
+            self.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
             .enable_eagerloads(False)
             .correlate(None)
             .subquery()
@@ -2903,7 +2928,7 @@ def exists(self):
         inner = (
             self.enable_eagerloads(False)
             .add_columns(sql.literal_column("1"))
-            .with_labels()
+            .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
             .statement.with_only_columns(1)
         )