Merge "migrate labels to new tutorial" into main

3 files changed, 48 insertions, 9 deletions

diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py
index 7947456af..4b0047e34 100644
--- a/lib/sqlalchemy/engine/cursor.py
+++ b/lib/sqlalchemy/engine/cursor.py
@@ -1244,7 +1244,7 @@ class CursorResult(Result[_T]):
 
     .. seealso::
 
-        :ref:`coretutorial_selecting` - introductory material for accessing
+        :ref:`tutorial_selecting_data` - introductory material for accessing
         :class:`_engine.CursorResult` and :class:`.Row` objects.
 
     """
diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py
index 7c9eacb78..06976dd4b 100644
--- a/lib/sqlalchemy/engine/row.py
+++ b/lib/sqlalchemy/engine/row.py
@@ -65,7 +65,7 @@ class Row(BaseRow, Sequence[Any], Generic[_TP]):
 
     .. seealso::
 
-        :ref:`coretutorial_selecting` - includes examples of selecting
+        :ref:`tutorial_selecting_data` - includes examples of selecting
         rows from SELECT statements.
 
     .. versionchanged:: 1.4
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index 5558b397c..6dea3677e 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -75,13 +75,7 @@ class URL(NamedTuple):
     * :attr:`_engine.URL.drivername`: database backend and driver name, such as
       ``postgresql+psycopg2``
     * :attr:`_engine.URL.username`: username string
-    * :attr:`_engine.URL.password`: password string, or object that includes
-      a ``__str__()`` method that produces a password.
-
-      .. note::  A password-producing object will be stringified only
-         **once** per :class:`_engine.Engine` object.  For dynamic password
-         generation per connect, see :ref:`engines_dynamic_tokens`.
-
+    * :attr:`_engine.URL.password`: password string
     * :attr:`_engine.URL.host`: string hostname
     * :attr:`_engine.URL.port`: integer port number
     * :attr:`_engine.URL.database`: string database name
@@ -93,12 +87,57 @@ class URL(NamedTuple):
     """
 
     drivername: str
+    """database backend and driver name, such as
+    ``postgresql+psycopg2``
+
+    """
+
     username: Optional[str]
+    "username string"
+
     password: Optional[str]
+    """password, which is normally a string but may also be any
+    object that has a ``__str__()`` method."""
+
     host: Optional[str]
+    """hostname or IP number.  May also be a data source name for some
+    drivers."""
+
     port: Optional[int]
+    """integer port number"""
+
     database: Optional[str]
+    """database name"""
+
     query: util.immutabledict[str, Union[Tuple[str, ...], str]]
+    """an immutable mapping representing the query string.  contains strings
+       for keys and either strings or tuples of strings for values, e.g.::
+
+            >>> from sqlalchemy.engine import make_url
+            >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
+            >>> url.query
+            immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
+
+         To create a mutable copy of this mapping, use the ``dict`` constructor::
+
+            mutable_query_opts = dict(url.query)
+
+       .. seealso::
+
+          :attr:`_engine.URL.normalized_query` - normalizes all values into sequences
+          for consistent processing
+
+          Methods for altering the contents of :attr:`_engine.URL.query`:
+
+          :meth:`_engine.URL.update_query_dict`
+
+          :meth:`_engine.URL.update_query_string`
+
+          :meth:`_engine.URL.update_query_pairs`
+
+          :meth:`_engine.URL.difference_update_query`
+
+    """  # noqa: E501
 
     @classmethod
     def create(