Added merge_all and delete_all

CaselIT · zzzeek · commit 41c30cc03126 · 2025-02-03T10:08:09.000-05:00
Added the utility method :meth:`_orm.Session.merge_all` and :meth:`_orm.Session.delete_all` that operate on a collection of instances. Fixes: #11776 Change-Id: Ifd70ba2850db7c5e7aee482799fd65c348c2899a
diff --git a/doc/build/changelog/unreleased_21/11776.rst b/doc/build/changelog/unreleased_21/11776.rst
@@ -0,0 +1,7 @@
+.. change::
+    :tags: orm, usecase
+    :tickets: 11776
+
+    Added the utility method :meth:`_orm.Session.merge_all` and
+    :meth:`_orm.Session.delete_all` that operate on a collection
+    of instances.
diff --git a/lib/sqlalchemy/ext/asyncio/scoping.py b/lib/sqlalchemy/ext/asyncio/scoping.py
@@ -85,6 +85,7 @@
         "commit",
         "connection",
         "delete",
+        "delete_all",
         "execute",
         "expire",
         "expire_all",
@@ -95,6 +96,7 @@
         "is_modified",
         "invalidate",
         "merge",
+        "merge_all",
         "refresh",
         "rollback",
         "scalar",
@@ -287,7 +289,7 @@ async def aclose(self) -> None:
 
         return await self._proxied.aclose()
 
-    def add(self, instance: object, _warn: bool = True) -> None:
+    def add(self, instance: object, *, _warn: bool = True) -> None:
         r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
@@ -530,6 +532,23 @@ async def delete(self, instance: object) -> None:
 
         return await self._proxied.delete(instance)
 
+    async def delete_all(self, instances: Iterable[object]) -> None:
+        r"""Calls :meth:`.AsyncSession.delete` on multiple instances.
+
+        .. container:: class_bases
+
+            Proxied for the :class:`_asyncio.AsyncSession` class on
+            behalf of the :class:`_asyncio.scoping.async_scoped_session` class.
+
+        .. seealso::
+
+            :meth:`_orm.Session.delete_all` - main documentation for delete_all
+
+
+        """  # noqa: E501
+
+        return await self._proxied.delete_all(instances)
+
     @overload
     async def execute(
         self,
@@ -958,6 +977,31 @@ async def merge(
 
         return await self._proxied.merge(instance, load=load, options=options)
 
+    async def merge_all(
+        self,
+        instances: Iterable[_O],
+        *,
+        load: bool = True,
+        options: Optional[Sequence[ORMOption]] = None,
+    ) -> Sequence[_O]:
+        r"""Calls :meth:`.AsyncSession.merge` on multiple instances.
+
+        .. container:: class_bases
+
+            Proxied for the :class:`_asyncio.AsyncSession` class on
+            behalf of the :class:`_asyncio.scoping.async_scoped_session` class.
+
+        .. seealso::
+
+            :meth:`_orm.Session.merge_all` - main documentation for merge_all
+
+
+        """  # noqa: E501
+
+        return await self._proxied.merge_all(
+            instances, load=load, options=options
+        )
+
     async def refresh(
         self,
         instance: object,
diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
@@ -775,6 +775,16 @@ async def delete(self, instance: object) -> None:
         """
         await greenlet_spawn(self.sync_session.delete, instance)
 
+    async def delete_all(self, instances: Iterable[object]) -> None:
+        """Calls :meth:`.AsyncSession.delete` on multiple instances.
+
+        .. seealso::
+
+            :meth:`_orm.Session.delete_all` - main documentation for delete_all
+
+        """
+        await greenlet_spawn(self.sync_session.delete_all, instances)
+
     async def merge(
         self,
         instance: _O,
@@ -794,6 +804,24 @@ async def merge(
             self.sync_session.merge, instance, load=load, options=options
         )
 
+    async def merge_all(
+        self,
+        instances: Iterable[_O],
+        *,
+        load: bool = True,
+        options: Optional[Sequence[ORMOption]] = None,
+    ) -> Sequence[_O]:
+        """Calls :meth:`.AsyncSession.merge` on multiple instances.
+
+        .. seealso::
+
+            :meth:`_orm.Session.merge_all` - main documentation for merge_all
+
+        """
+        return await greenlet_spawn(
+            self.sync_session.merge_all, instances, load=load, options=options
+        )
+
     async def flush(self, objects: Optional[Sequence[Any]] = None) -> None:
         """Flush all the object changes to the database.
 
@@ -1122,7 +1150,7 @@ def __iter__(self) -> Iterator[object]:
 
         return self._proxied.__iter__()
 
-    def add(self, instance: object, _warn: bool = True) -> None:
+    def add(self, instance: object, *, _warn: bool = True) -> None:
         r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
@@ -327,9 +327,7 @@ def merge_frozen_result(session, statement, frozen_result, load=True):
         statement, legacy=False
     )
 
-    autoflush = session.autoflush
-    try:
-        session.autoflush = False
+    with session.no_autoflush:
         mapped_entities = [
             i
             for i, e in enumerate(ctx._entities)
@@ -356,8 +354,6 @@ def merge_frozen_result(session, statement, frozen_result, load=True):
             result.append(keyed_tuple(newrow))
 
         return frozen_result.with_new_rows(result)
-    finally:
-        session.autoflush = autoflush
 
 
 @util.became_legacy_20(
diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
@@ -116,6 +116,7 @@ def __get__(self, instance: Any, owner: Type[_T]) -> Query[_T]: ...
         "commit",
         "connection",
         "delete",
+        "delete_all",
         "execute",
         "expire",
         "expire_all",
@@ -130,6 +131,7 @@ def __get__(self, instance: Any, owner: Type[_T]) -> Query[_T]: ...
         "bulk_insert_mappings",
         "bulk_update_mappings",
         "merge",
+        "merge_all",
         "query",
         "refresh",
         "rollback",
@@ -350,7 +352,7 @@ def __iter__(self) -> Iterator[object]:
 
         return self._proxied.__iter__()
 
-    def add(self, instance: object, _warn: bool = True) -> None:
+    def add(self, instance: object, *, _warn: bool = True) -> None:
         r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
@@ -673,11 +675,32 @@ def delete(self, instance: object) -> None:
 
             :ref:`session_deleting` - at :ref:`session_basics`
 
+            :meth:`.Session.delete_all` - multiple instance version
+
 
         """  # noqa: E501
 
         return self._proxied.delete(instance)
 
+    def delete_all(self, instances: Iterable[object]) -> None:
+        r"""Calls :meth:`.Session.delete` on multiple instances.
+
+        .. container:: class_bases
+
+            Proxied for the :class:`_orm.Session` class on
+            behalf of the :class:`_orm.scoping.scoped_session` class.
+
+        .. seealso::
+
+            :meth:`.Session.delete` - main documentation on delete
+
+        .. versionadded: 2.1
+
+
+        """  # noqa: E501
+
+        return self._proxied.delete_all(instances)
+
     @overload
     def execute(
         self,
@@ -1567,11 +1590,38 @@ def merge(
             :func:`.make_transient_to_detached` - provides for an alternative
             means of "merging" a single object into the :class:`.Session`
 
+            :meth:`.Session.merge_all` - multiple instance version
+
 
         """  # noqa: E501
 
         return self._proxied.merge(instance, load=load, options=options)
 
+    def merge_all(
+        self,
+        instances: Iterable[_O],
+        *,
+        load: bool = True,
+        options: Optional[Sequence[ORMOption]] = None,
+    ) -> Sequence[_O]:
+        r"""Calls :meth:`.Session.merge` on multiple instances.
+
+        .. container:: class_bases
+
+            Proxied for the :class:`_orm.Session` class on
+            behalf of the :class:`_orm.scoping.scoped_session` class.
+
+        .. seealso::
+
+            :meth:`.Session.merge` - main documentation on merge
+
+        .. versionadded: 2.1
+
+
+        """  # noqa: E501
+
+        return self._proxied.merge_all(instances, load=load, options=options)
+
     @overload
     def query(self, _entity: _EntityType[_O]) -> Query[_O]: ...
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
@@ -3459,7 +3459,7 @@ def _remove_newly_deleted(
             if persistent_to_deleted is not None:
                 persistent_to_deleted(self, state)
 
-    def add(self, instance: object, _warn: bool = True) -> None:
+    def add(self, instance: object, *, _warn: bool = True) -> None:
         """Place an object into this :class:`_orm.Session`.
 
         Objects that are in the :term:`transient` state when passed to the
@@ -3544,16 +3544,30 @@ def delete(self, instance: object) -> None:
 
             :ref:`session_deleting` - at :ref:`session_basics`
 
+            :meth:`.Session.delete_all` - multiple instance version
+
         """
         if self._warn_on_events:
             self._flush_warning("Session.delete()")
 
-        try:
-            state = attributes.instance_state(instance)
-        except exc.NO_STATE as err:
-            raise exc.UnmappedInstanceError(instance) from err
+        self._delete_impl(object_state(instance), instance, head=True)
+
+    def delete_all(self, instances: Iterable[object]) -> None:
+        """Calls :meth:`.Session.delete` on multiple instances.
 
-        self._delete_impl(state, instance, head=True)
+        .. seealso::
+
+            :meth:`.Session.delete` - main documentation on delete
+
+        .. versionadded: 2.1
+
+        """
+
+        if self._warn_on_events:
+            self._flush_warning("Session.delete_all()")
+
+        for instance in instances:
+            self._delete_impl(object_state(instance), instance, head=True)
 
     def _delete_impl(
         self, state: InstanceState[Any], obj: object, head: bool
@@ -3955,32 +3969,62 @@ def merge(
             :func:`.make_transient_to_detached` - provides for an alternative
             means of "merging" a single object into the :class:`.Session`
 
+            :meth:`.Session.merge_all` - multiple instance version
+
         """
 
         if self._warn_on_events:
             self._flush_warning("Session.merge()")
 
-        _recursive: Dict[InstanceState[Any], object] = {}
-        _resolve_conflict_map: Dict[_IdentityKeyType[Any], object] = {}
-
         if load:
             # flush current contents if we expect to load data
             self._autoflush()
 
-        object_mapper(instance)  # verify mapped
-        autoflush = self.autoflush
-        try:
-            self.autoflush = False
+        with self.no_autoflush:
             return self._merge(
-                attributes.instance_state(instance),
+                object_state(instance),
                 attributes.instance_dict(instance),
                 load=load,
                 options=options,
-                _recursive=_recursive,
-                _resolve_conflict_map=_resolve_conflict_map,
+                _recursive={},
+                _resolve_conflict_map={},
             )
-        finally:
-            self.autoflush = autoflush
+
+    def merge_all(
+        self,
+        instances: Iterable[_O],
+        *,
+        load: bool = True,
+        options: Optional[Sequence[ORMOption]] = None,
+    ) -> Sequence[_O]:
+        """Calls :meth:`.Session.merge` on multiple instances.
+
+        .. seealso::
+
+            :meth:`.Session.merge` - main documentation on merge
+
+        .. versionadded: 2.1
+
+        """
+
+        if self._warn_on_events:
+            self._flush_warning("Session.merge_all()")
+
+        if load:
+            # flush current contents if we expect to load data
+            self._autoflush()
+
+        return [
+            self._merge(
+                object_state(instance),
+                attributes.instance_dict(instance),
+                load=load,
+                options=options,
+                _recursive={},
+                _resolve_conflict_map={},
+            )
+            for instance in instances
+        ]
 
     def _merge(
         self,
diff --git a/test/orm/test_merge.py b/test/orm/test_merge.py
diff --git a/test/orm/test_session.py b/test/orm/test_session.py
diff --git a/test/profiles.txt b/test/profiles.txt
