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

Author: zzzeek

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)
         )