From: proto-atlas <278522736+proto-atlas@users.noreply.github.com>
Date: Thu, 21 May 2026 17:29:59 +0000 (+0900)
Subject: Fix bulk mapping annotations for mapped classes
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=refs%2Fpull%2F13322%2Fhead;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Fix bulk mapping annotations for mapped classes
---

diff --git a/doc/build/changelog/unreleased_21/9256.rst b/doc/build/changelog/unreleased_21/9256.rst
new file mode 100644
index 0000000000..435624865a
--- /dev/null
+++ b/doc/build/changelog/unreleased_21/9256.rst
@@ -0,0 +1,9 @@
+.. change::
+    :tags: bug, orm, typing
+    :tickets: 9256
+
+    Adjusted the type annotations for
+    :meth:`_orm.Session.bulk_insert_mappings` and
+    :meth:`_orm.Session.bulk_update_mappings` to accept a mapped class as well
+    as a :class:`_orm.Mapper`, matching the documented and runtime behavior of
+    these legacy methods.
diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index 4d0a034872..bbebee5c42 100644
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -43,7 +43,6 @@ if TYPE_CHECKING:
     from ._typing import OrmExecuteOptionsParameter
     from .identity import IdentityMap
     from .interfaces import ORMOption
-    from .mapper import Mapper
     from .query import Query
     from .query import RowReturningQuery
     from .session import _BindArguments
@@ -1392,7 +1391,7 @@ class scoped_session(Generic[_S]):
 
     def bulk_insert_mappings(
         self,
-        mapper: Mapper[Any],
+        mapper: _EntityBindKey[Any],
         mappings: Iterable[Dict[str, Any]],
         return_defaults: bool = False,
         render_nulls: bool = False,
@@ -1478,7 +1477,7 @@ class scoped_session(Generic[_S]):
         )
 
     def bulk_update_mappings(
-        self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]
+        self, mapper: _EntityBindKey[Any], mappings: Iterable[Dict[str, Any]]
     ) -> None:
         r"""Perform a bulk update of the given list of mapping dictionaries.
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index cb37588ede..6d6599007e 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -4711,7 +4711,7 @@ class Session(_SessionClassMethods, EventTarget):
 
     def bulk_insert_mappings(
         self,
-        mapper: Mapper[Any],
+        mapper: _EntityBindKey[Any],
         mappings: Iterable[Dict[str, Any]],
         return_defaults: bool = False,
         render_nulls: bool = False,
@@ -4793,7 +4793,7 @@ class Session(_SessionClassMethods, EventTarget):
         )
 
     def bulk_update_mappings(
-        self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]
+        self, mapper: _EntityBindKey[Any], mappings: Iterable[Dict[str, Any]]
     ) -> None:
         """Perform a bulk update of the given list of mapping dictionaries.
 
@@ -4842,7 +4842,7 @@ class Session(_SessionClassMethods, EventTarget):
 
     def _bulk_save_mappings(
         self,
-        mapper: Mapper[_O],
+        mapper: _EntityBindKey[_O],
         mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]],
         *,
         isupdate: bool,
diff --git a/test/typing/plain_files/orm/session.py b/test/typing/plain_files/orm/session.py
index 311c522a6d..9937e5da2b 100644
--- a/test/typing/plain_files/orm/session.py
+++ b/test/typing/plain_files/orm/session.py
@@ -11,6 +11,7 @@ from sqlalchemy import Column
 from sqlalchemy import create_engine
 from sqlalchemy import ForeignKey
 from sqlalchemy import Integer
+from sqlalchemy import inspect
 from sqlalchemy import MetaData
 from sqlalchemy import Result
 from sqlalchemy import Select
@@ -120,6 +121,13 @@ with Session(e) as sess:
     with sess.begin() as tx:
         assert_type(tx, SessionTransaction)
 
+    # test #9256
+
+    sess.bulk_insert_mappings(User, [{"id": 1, "name": "u1"}])
+    sess.bulk_update_mappings(User, [{"id": 1, "name": "u1"}])
+    sess.bulk_insert_mappings(inspect(User), [{"id": 2, "name": "u2"}])
+    sess.bulk_update_mappings(inspect(User), [{"id": 2, "name": "u2"}])
+
 # more result tests in typed_results.py