Merge "migrate labels to new tutorial" into main

7 files changed, 30 insertions, 69 deletions

diff --git a/lib/sqlalchemy/sql/_dml_constructors.py b/lib/sqlalchemy/sql/_dml_constructors.py
index 926e5257b..293d225f9 100644
--- a/lib/sqlalchemy/sql/_dml_constructors.py
+++ b/lib/sqlalchemy/sql/_dml_constructors.py
@@ -35,9 +35,6 @@ def insert(table: _DMLTableArgument) -> Insert:
 
     .. seealso::
 
-        :ref:`coretutorial_insert_expressions` - in the
-        :ref:`1.x tutorial <sqlexpression_toplevel>`
-
         :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
 
 
@@ -79,9 +76,7 @@ def insert(table: _DMLTableArgument) -> Insert:
 
     .. seealso::
 
-        :ref:`coretutorial_insert_expressions` - SQL Expression Tutorial
-
-        :ref:`inserts_and_updates` - SQL Expression Tutorial
+        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
 
     """
     return Insert(table)
@@ -104,15 +99,6 @@ def update(table: _DMLTableArgument) -> Update:
     :meth:`_expression.TableClause.update` method on
     :class:`_schema.Table`.
 
-    .. seealso::
-
-        :ref:`inserts_and_updates` - in the
-        :ref:`1.x tutorial <sqlexpression_toplevel>`
-
-        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
-
-
-
     :param table: A :class:`_schema.Table`
      object representing the database
      table to be updated.
diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py
index f6dd92865..8b8f6b010 100644
--- a/lib/sqlalchemy/sql/_elements_constructors.py
+++ b/lib/sqlalchemy/sql/_elements_constructors.py
@@ -605,15 +605,6 @@ def bindparam(
       .. versionchanged:: 1.3 the "expanding" bound parameter feature now
          supports empty lists.
 
-
-      .. seealso::
-
-        :ref:`coretutorial_bind_param`
-
-        :ref:`coretutorial_insert_expressions`
-
-        :func:`.outparam`
-
     :param literal_execute:
       if True, the bound parameter will be rendered in the compile phase
       with a special "POSTCOMPILE" token, and the SQLAlchemy compiler will
@@ -635,6 +626,12 @@ def bindparam(
 
             :ref:`change_4808`.
 
+    .. seealso::
+
+        :ref:`tutorial_sending_parameters` - in the
+        :ref:`unified_tutorial`
+
+
     """
     return BindParameter(
         key,
@@ -827,7 +824,7 @@ def cast(
 
     .. seealso::
 
-        :ref:`coretutorial_casts`
+        :ref:`tutorial_casts`
 
         :func:`.type_coerce` - an alternative to CAST that coerces the type
         on the Python side only, which is often sufficient to generate the
@@ -932,7 +929,7 @@ def column(
 
         :func:`_expression.text`
 
-        :ref:`sqlexpression_literal_column`
+        :ref:`tutorial_select_arbitrary_text`
 
     """
     return ColumnClause(text, type_, is_literal, _selectable)
@@ -1468,8 +1465,7 @@ def text(text: str) -> TextClause:
 
     .. seealso::
 
-        :ref:`sqlexpression_text` - in the Core tutorial
-
+        :ref:`tutorial_select_arbitrary_text`
 
     """
     return TextClause(text)
@@ -1615,7 +1611,7 @@ def type_coerce(
 
     .. seealso::
 
-        :ref:`coretutorial_casts`
+        :ref:`tutorial_casts`
 
         :func:`.cast`
 
diff --git a/lib/sqlalchemy/sql/_selectable_constructors.py b/lib/sqlalchemy/sql/_selectable_constructors.py
index ea824d622..b661d6f47 100644
--- a/lib/sqlalchemy/sql/_selectable_constructors.py
+++ b/lib/sqlalchemy/sql/_selectable_constructors.py
@@ -290,7 +290,7 @@ def lateral(
 
     .. seealso::
 
-        :ref:`lateral_selects` -  overview of usage.
+        :ref:`tutorial_lateral_correlation` -  overview of usage.
 
     """
     return Lateral._factory(selectable, name=name)
@@ -466,8 +466,7 @@ def select(*entities: _ColumnsClauseArgument[Any], **__kw: Any) -> Select[Any]:
 
     .. seealso::
 
-        :ref:`coretutorial_selecting` - Core Tutorial description of
-        :func:`_expression.select`.
+        :ref:`tutorial_selecting_data` - in the :ref:`unified_tutorial`
 
     :param \*entities:
       Entities to SELECT from.  For Core usage, this is typically a series
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 28ea512a7..2ed3be9cb 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -800,7 +800,7 @@ class ValuesBase(UpdateBase):
 
            .. seealso::
 
-               :ref:`execute_multiple` - an introduction to
+               :ref:`tutorial_multiple_parameters` - an introduction to
                the traditional Core method of multiple parameter set
                invocation for INSERTs and other statements.
 
@@ -1256,16 +1256,6 @@ class DMLWhereBase:
 
         .. seealso::
 
-            **1.x Tutorial Examples**
-
-            :ref:`tutorial_1x_correlated_updates`
-
-            :ref:`multi_table_updates`
-
-            :ref:`multi_table_deletes`
-
-            **2.0 Tutorial Examples**
-
             :ref:`tutorial_correlated_updates`
 
             :ref:`tutorial_update_from`
@@ -1381,7 +1371,7 @@ class Update(DMLWhereBase, ValuesBase):
 
         .. seealso::
 
-           :ref:`updates_order_parameters` - full example of the
+           :ref:`tutorial_parameter_ordered_updates` - full example of the
            :meth:`_expression.Update.ordered_values` method.
 
         .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values`
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 6032253c2..625e1d94b 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -190,7 +190,7 @@ def literal_column(
 
         :func:`_expression.text`
 
-        :ref:`sqlexpression_literal_column`
+        :ref:`tutorial_select_arbitrary_text`
 
     """
     return ColumnClause(text, type_=type_, is_literal=True)
@@ -1568,7 +1568,7 @@ class ColumnElement(
 
         .. seealso::
 
-            :ref:`coretutorial_casts`
+            :ref:`tutorial_casts`
 
             :func:`_expression.cast`
 
@@ -3198,7 +3198,7 @@ class Cast(WrapsColumnExpression[_T]):
 
     .. seealso::
 
-        :ref:`coretutorial_casts`
+        :ref:`tutorial_casts`
 
         :func:`.cast`
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 0cba1a1a8..befd262ec 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -102,7 +102,7 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
 
     .. seealso::
 
-        :ref:`coretutorial_functions` - in the Core tutorial
+        :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
 
         :class:`.Function` - named SQL function.
 
@@ -821,7 +821,7 @@ class _FunctionGenerator:
 
     .. seealso::
 
-        :ref:`coretutorial_functions` - in the Core Tutorial
+        :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
 
         :class:`.Function`
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index eebefb877..ce561697b 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -105,6 +105,7 @@ and_ = BooleanClauseList.and_
 _T = TypeVar("_T", bound=Any)
 
 if TYPE_CHECKING:
+    import sqlalchemy
     from ._typing import _ColumnExpressionArgument
     from ._typing import _FromClauseArgument
     from ._typing import _JoinTargetArgument
@@ -129,7 +130,6 @@ if TYPE_CHECKING:
     from .cache_key import _CacheKeyTraversalType
     from .compiler import SQLCompiler
     from .dml import Delete
-    from .dml import Insert
     from .dml import Update
     from .elements import KeyedColumnElement
     from .elements import Label
@@ -292,7 +292,7 @@ class Selectable(ReturnsRows):
 
         .. seealso::
 
-            :ref:`lateral_selects` -  overview of usage.
+            :ref:`tutorial_lateral_correlation` -  overview of usage.
 
         """
         return Lateral._construct(self, name)
@@ -751,7 +751,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
         .. seealso::
 
-            :ref:`core_tutorial_aliases`
+            :ref:`tutorial_using_aliases`
 
             :func:`_expression.alias`
 
@@ -1893,7 +1893,7 @@ class Lateral(FromClauseAlias, LateralFromClause):
 
     .. seealso::
 
-        :ref:`lateral_selects` -  overview of usage.
+        :ref:`tutorial_lateral_correlation` -  overview of usage.
 
     """
 
@@ -2063,7 +2063,7 @@ class CTE(
 
         .. seealso::
 
-            :ref:`core_tutorial_aliases`
+            :ref:`tutorial_using_aliases`
 
             :func:`_expression.alias`
 
@@ -2996,7 +2996,7 @@ class TableClause(roles.DMLTableRole, Immutable, NamedFromClause):
         c.table = self
 
     @util.preload_module("sqlalchemy.sql.dml")
-    def insert(self) -> Insert:
+    def insert(self) -> sqlalchemy.sql.expression.Insert:
         """Generate an :func:`_expression.insert` construct against this
         :class:`_expression.TableClause`.
 
@@ -3180,7 +3180,7 @@ class Values(Generative, LateralFromClause):
 
         .. seealso::
 
-            :ref:`core_tutorial_aliases`
+            :ref:`tutorial_using_aliases`
 
             :func:`_expression.alias`
 
@@ -3462,8 +3462,6 @@ class SelectBase(
 
             :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
 
-            :ref:`scalar_selects` - in the 1.x tutorial
-
         """
         if self._label_style is not LABEL_STYLE_NONE:
             self = self.set_label_style(LABEL_STYLE_NONE)
@@ -3491,7 +3489,7 @@ class SelectBase(
 
         .. seealso::
 
-            :ref:`lateral_selects` -  overview of usage.
+            :ref:`tutorial_lateral_correlation` -  overview of usage.
 
         """
         return Lateral._factory(self, name)
@@ -4970,8 +4968,6 @@ class Select(
 
         :func:`_sql.select`
 
-        :ref:`coretutorial_selecting` - in the 1.x tutorial
-
         :ref:`tutorial_selecting_data` - in the 2.0 tutorial
 
     """
@@ -6022,7 +6018,7 @@ class Select(
 
             :meth:`_expression.Select.correlate_except`
 
-            :ref:`correlated_subqueries`
+            :ref:`tutorial_scalar_subquery`
 
         """
 
@@ -6072,7 +6068,7 @@ class Select(
 
             :meth:`_expression.Select.correlate`
 
-            :ref:`correlated_subqueries`
+            :ref:`tutorial_scalar_subquery`
 
         """
 
@@ -6345,8 +6341,6 @@ class ScalarSelect(
 
         :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
 
-        :ref:`scalar_selects` - in the 1.x tutorial
-
     """
 
     _traverse_internals: _TraverseInternalsType = [
@@ -6444,8 +6438,6 @@ class ScalarSelect(
 
             :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
 
-            :ref:`correlated_subqueries` - in the 1.x tutorial
-
 
         """
         self.element = cast("Select[Any]", self.element).correlate(
@@ -6483,8 +6475,6 @@ class ScalarSelect(
 
             :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
 
-            :ref:`correlated_subqueries` - in the 1.x tutorial
-
 
         """