Added loader options to session.merge, asyncsession.merge

Added loader options to :meth:`_orm.Session.merge` and
:meth:`_asyncio.AsyncSession.merge`, which will apply the given loader
options to the ``get()`` used internally by merge, allowing eager loading
of relationships etc. to be applied when the merge process loads a new
object. Pull request courtesy Daniel Stone.

Fixes: #6955
Closes: #6957
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/6957
Pull-request-sha: ab4d96cd5da9a5dd01112b8dcd6514db64aa8d9f

Change-Id: I5b94dfda1088a8bc6396e9fd9a072827df1f8680

1 files changed, 38 insertions, 4 deletions

diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
index 6b18e3d7c..e4372f448 100644
--- a/lib/sqlalchemy/ext/asyncio/session.py
+++ b/lib/sqlalchemy/ext/asyncio/session.py
@@ -133,6 +133,10 @@ class AsyncSession(ReversibleProxy):
         This is the async version of the :meth:`_orm.Session.refresh` method.
         See that method for a complete description of all options.
 
+        .. seealso::
+
+            :meth:`_orm.Session.refresh` - main documentation for refresh
+
         """
 
         return await greenlet_spawn(
@@ -179,6 +183,11 @@ class AsyncSession(ReversibleProxy):
     ):
         """Execute a statement and return a buffered
         :class:`_engine.Result` object.
+
+        .. seealso::
+
+            :meth:`_orm.Session.execute` - main documentation for execute
+
         """
 
         if execution_options:
@@ -205,7 +214,13 @@ class AsyncSession(ReversibleProxy):
         bind_arguments=None,
         **kw
     ):
-        """Execute a statement and return a scalar result."""
+        """Execute a statement and return a scalar result.
+
+        .. seealso::
+
+            :meth:`_orm.Session.scalar` - main documentation for scalar
+
+        """
 
         result = await self.execute(
             statement,
@@ -228,6 +243,10 @@ class AsyncSession(ReversibleProxy):
         """Return an instance based on the given primary key identifier,
         or ``None`` if not found.
 
+        .. seealso::
+
+            :meth:`_orm.Session.get` - main documentation for get
+
 
         """
         return await greenlet_spawn(
@@ -276,17 +295,24 @@ class AsyncSession(ReversibleProxy):
         As this operation may need to cascade along unloaded relationships,
         it is awaitable to allow for those queries to take place.
 
+        .. seealso::
+
+            :meth:`_orm.Session.delete` - main documentation for delete
 
         """
         return await greenlet_spawn(self.sync_session.delete, instance)
 
-    async def merge(self, instance, load=True):
+    async def merge(self, instance, load=True, options=None):
         """Copy the state of a given instance into a corresponding instance
         within this :class:`_asyncio.AsyncSession`.
 
+        .. seealso::
+
+            :meth:`_orm.Session.merge` - main documentation for merge
+
         """
         return await greenlet_spawn(
-            self.sync_session.merge, instance, load=load
+            self.sync_session.merge, instance, load=load, options=options
         )
 
     async def flush(self, objects=None):
@@ -294,7 +320,7 @@ class AsyncSession(ReversibleProxy):
 
         .. seealso::
 
-            :meth:`_orm.Session.flush`
+            :meth:`_orm.Session.flush` - main documentation for flush
 
         """
         await greenlet_spawn(self.sync_session.flush, objects=objects)
@@ -334,9 +360,17 @@ class AsyncSession(ReversibleProxy):
         r"""Return a :class:`_asyncio.AsyncConnection` object corresponding to
         this :class:`.Session` object's transactional state.
 
+        This method may also be used to establish execution options for the
+        database connection used by the current transaction.
+
         .. versionadded:: 1.4.24  Added **kw arguments which are passed through
            to the underlying :meth:`_orm.Session.connection` method.
 
+        .. seealso::
+
+            :meth:`_orm.Session.connection` - main documentation for
+            "connection"
+
         """
 
         sync_connection = await greenlet_spawn(