Documentation improvements

Also remove deprecated usage:
- load_only does not accept strings
- case.whens is positional only

Ref #6712
Ref #5994
Ref #6121
Ref #6785
Ref https://groups.google.com/g/sqlalchemy/c/-cnhThEu3kk

Change-Id: I5db49a075b9d3d332518b9d189a24b13b502e2af

4 files changed, 24 insertions, 6 deletions

diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 119bf4a9e..60474c0ed 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -708,6 +708,15 @@ class Result(_WithKeys, ResultInternal):
        :class:`.ResultProxy` interface.   When using the ORM, a higher level
        object called :class:`.ChunkedIteratorResult` is normally used.
 
+    .. note:: In SQLAlchemy 1.4 and above, this object is
+       used for ORM results returned by :meth:`_orm.Session.execute`, which can
+       yield instances of ORM mapped objects either individually or within
+       tuple-like rows. Note that the :class:`_result.Result` object does not
+       deduplicate instances or rows automatically as is the case with the
+       legacy :class:`_orm.Query` object. For in-Python de-duplication of
+       instances or rows, use the :meth:`_result.Result.unique` modifier
+       method.
+
     .. seealso::
 
         :ref:`tutorial_fetching_rows` - in the :doc:`/tutorial/index`
diff --git a/lib/sqlalchemy/ext/asyncio/result.py b/lib/sqlalchemy/ext/asyncio/result.py
index 2fdaec741..dff87a569 100644
--- a/lib/sqlalchemy/ext/asyncio/result.py
+++ b/lib/sqlalchemy/ext/asyncio/result.py
@@ -29,6 +29,15 @@ class AsyncResult(AsyncCommon):
     :meth:`_asyncio.AsyncConnection.stream` and
     :meth:`_asyncio.AsyncSession.stream` methods.
 
+    .. note:: As is the case with :class:`_engine.Result`, this object is
+       used for ORM results returned by :meth:`_asyncio.AsyncSession.execute`,
+       which can yield instances of ORM mapped objects either individually or
+       within tuple-like rows.  Note that these result objects do not
+       deduplicate instances or rows automatically as is the case with the
+       legacy :class:`_orm.Query` object. For in-Python de-duplication of
+       instances or rows, use the :meth:`_asyncio.AsyncResult.unique` modifier
+       method.
+
     .. versionadded:: 1.4
 
     """
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 043ecfed3..399e33b89 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -414,7 +414,7 @@ class Load(Generative, LoaderOption):
             query = session.query(Author)
             query = query.options(
                         joinedload(Author.book).options(
-                            load_only("summary", "excerpt"),
+                            load_only(Book.summary, Book.excerpt),
                             joinedload(Book.citations).options(
                                 joinedload(Citation.author)
                             )
@@ -1152,14 +1152,14 @@ def load_only(loadopt, *attrs):
     Example - given a class ``User``, load only the ``name`` and ``fullname``
     attributes::
 
-        session.query(User).options(load_only("name", "fullname"))
+        session.query(User).options(load_only(User.name, User.fullname))
 
     Example - given a relationship ``User.addresses -> Address``, specify
     subquery loading for the ``User.addresses`` collection, but on each
     ``Address`` object load only the ``email_address`` attribute::
 
         session.query(User).options(
-                subqueryload("addresses").load_only("email_address")
+                subqueryload(User.addresses).load_only(Address.email_address)
         )
 
     For a :class:`_query.Query` that has multiple entities,
@@ -1167,8 +1167,8 @@ def load_only(loadopt, *attrs):
     specifically referred to using the :class:`_orm.Load` constructor::
 
         session.query(User, Address).join(User.addresses).options(
-                    Load(User).load_only("name", "fullname"),
-                    Load(Address).load_only("email_address")
+                    Load(User).load_only(User.name, User.fullname),
+                    Load(Address).load_only(Address.email_address)
                 )
 
      .. note:: This method will still load a :class:`_schema.Column` even
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 173314abe..ef3eb82cd 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -2732,7 +2732,7 @@ class Case(ColumnElement):
             stmt = select(users_table).\
                         where(
                             case(
-                                whens={"wendy": "W", "jack": "J"},
+                                {"wendy": "W", "jack": "J"},
                                 value=users_table.c.name,
                                 else_='E'
                             )