SQLAlchemy 2.0.53__py3-none-any.whl → 2.0.55__py3-none-any.whl

sqlalchemy/__init__.py

@@ -269,7 +269,7 @@ from .types import Uuid as Uuid
 from .types import VARBINARY as VARBINARY
 from .types import VARCHAR as VARCHAR
 
-__version__ = "2.0.53"
+__version__ = "2.0.55"
 
 
 def __go(lcls: Any) -> None:

sqlalchemy/dialects/mssql/base.py

@@ -2080,6 +2080,13 @@ class MSSQLCompiler(compiler.SQLCompiler):
             self.process(binary.right, **kw),
         )
 
+    def visit_truediv_binary(self, binary, operator, **kw):
+        return (
+            self.process(binary.left, **kw)
+            + " / "
+            + f"({self.process(binary.right, **kw)} + 0.0)"
+        )
+
     def visit_true(self, expr, **kw):
         return "1"
 
@@ -3243,6 +3250,27 @@ class MSDialect(default.DefaultDialect):
         finally:
             cursor.close()
 
+    def min_year_for_type(self, typeobj):
+        typeobj = sqltypes.to_instance(typeobj)
+
+        if isinstance(typeobj, SMALLDATETIME):
+            return 1900
+        elif isinstance(typeobj, (DATETIME2, DATETIMEOFFSET)):
+            return datetime.MINYEAR
+        elif isinstance(typeobj, sqltypes.DateTime):
+            # DateTime renders DATETIMEOFFSET with timezone=True,
+            # else DATETIME
+            return datetime.MINYEAR if typeobj.timezone else 1753
+        elif (
+            isinstance(typeobj, sqltypes.Date)
+            and not isinstance(typeobj, sqltypes.DATE)
+            and self.server_version_info < MS_2008_VERSION
+        ):
+            # Date renders DATETIME before SQL Server 2008
+            return 1753
+        else:
+            return datetime.MINYEAR
+
     def initialize(self, connection):
         super().initialize(connection)
         self._setup_version_attributes()

sqlalchemy/dialects/mssql/pyodbc.py

@@ -493,15 +493,12 @@ class _ODBCDateTimeBindProcessor:
             else:
                 # for DATETIMEOFFSET or DateTime(timezone=True)
                 #
-                # Convert to string format required by T-SQL
-                dto_string = value.strftime("%Y-%m-%d %H:%M:%S.%f %z")
-                # offset needs a colon, e.g., -0700 -> -07:00
-                # "UTC offset in the form (+-)HHMM[SS[.ffffff]]"
-                # backend currently rejects seconds / fractional seconds
-                dto_string = re.sub(
-                    r"([\+\-]\d{2})([\d\.]+)$", r"\1:\2", dto_string
-                )
-                return dto_string
+                # Convert to string format required by T-SQL.  isoformat()
+                # zero-pads the year, which strftime("%Y") does not do on
+                # all platforms, and renders the offset with a colon,
+                # e.g. -07:00.  backend currently rejects seconds /
+                # fractional seconds in the offset
+                return value.isoformat(sep=" ", timespec="microseconds")
 
         return process
 

sqlalchemy/dialects/oracle/base.py

@@ -2108,7 +2108,10 @@ class OracleDialect(default.DefaultDialect):
             return self.get_isolation_level(dbapi_conn)
         except NotImplementedError:
             raise
-        except:
+        except Exception:
+            # Exception only; a bare except here also caught
+            # asyncio.CancelledError and KeyboardInterrupt, returning the
+            # default in place of propagating them
             return "READ COMMITTED"
 
     def _execute_reflection(

sqlalchemy/dialects/postgresql/base.py

@@ -4379,8 +4379,12 @@ class PGDialect(default.DefaultDialect):
             )
             .outerjoin(
                 pg_catalog.pg_description,
-                pg_catalog.pg_description.c.objoid
-                == pg_catalog.pg_constraint.c.oid,
+                sql.and_(
+                    pg_catalog.pg_description.c.objoid
+                    == pg_catalog.pg_constraint.c.oid,
+                    pg_catalog.pg_description.c.classoid
+                    == sql.func.cast("pg_catalog.pg_constraint", REGCLASS),
+                ),
             )
             .where(
                 pg_catalog.pg_constraint.c.contype == bindparam("contype"),
@@ -4604,8 +4608,12 @@ class PGDialect(default.DefaultDialect):
             )
             .outerjoin(
                 pg_catalog.pg_description,
-                pg_catalog.pg_description.c.objoid
-                == pg_catalog.pg_constraint.c.oid,
+                sql.and_(
+                    pg_catalog.pg_description.c.objoid
+                    == pg_catalog.pg_constraint.c.oid,
+                    pg_catalog.pg_description.c.classoid
+                    == sql.func.cast("pg_catalog.pg_constraint", REGCLASS),
+                ),
             )
             .order_by(
                 pg_catalog.pg_class.c.relname,
@@ -4627,8 +4635,9 @@ class PGDialect(default.DefaultDialect):
 
         # https://www.postgresql.org/docs/current/static/sql-createtable.html
         return re.compile(
-            r"FOREIGN KEY \((.*?)\) "
-            rf"REFERENCES (?:({qtoken})\.)?({qtoken})\(((?:{qtoken}(?: *, *)?)+)\)"  # noqa: E501
+            rf"FOREIGN KEY \((.*?)(?:, PERIOD ({qtoken}))?\) "
+            rf"REFERENCES (?:({qtoken})\.)?({qtoken})"
+            rf"\(((?:{qtoken}(?: *, *)?)+)(?:, PERIOD ({qtoken}))?\)"
             r"[\s]?(MATCH (FULL|PARTIAL|SIMPLE)+)?"
             r"[\s]?(?:ON (UPDATE|DELETE) "
             r"(CASCADE|RESTRICT|NO ACTION|"
@@ -4646,9 +4655,11 @@ class PGDialect(default.DefaultDialect):
 
         (
             constrained_columns,
+            constrained_period_column,
             referred_schema,
             referred_table,
             referred_columns,
+            referred_period_column,
             _,
             match,
             upddelkey1,
@@ -4660,6 +4671,13 @@ class PGDialect(default.DefaultDialect):
             initially,
         ) = m
 
+        # TODO: the PERIOD designation of a temporal foreign key
+        # (PostgreSQL 18+) is not yet reflected
+        if constrained_period_column:
+            constrained_columns += f", {constrained_period_column}"
+        if referred_period_column:
+            referred_columns += f", {referred_period_column}"
+
         onupdate = (
             upddelval1
             if upddelkey1 == "UPDATE"
@@ -5245,8 +5263,12 @@ class PGDialect(default.DefaultDialect):
             )
             .outerjoin(
                 pg_catalog.pg_description,
-                pg_catalog.pg_description.c.objoid
-                == pg_catalog.pg_constraint.c.oid,
+                sql.and_(
+                    pg_catalog.pg_description.c.objoid
+                    == pg_catalog.pg_constraint.c.oid,
+                    pg_catalog.pg_description.c.classoid
+                    == sql.func.cast("pg_catalog.pg_constraint", REGCLASS),
+                ),
             )
             .order_by(
                 pg_catalog.pg_class.c.relname,

sqlalchemy/dialects/postgresql/named_types.py

@@ -341,6 +341,9 @@ class ENUM(NamedType, type_api.NativeForEmulated, sqltypes.Enum):
         kw.setdefault("_create_events", False)
         kw.setdefault("values_callable", impl.values_callable)
         kw.setdefault("omit_aliases", impl._omit_aliases)
+        kw.setdefault("sort_key_function", impl._sort_key_function)
+        kw.setdefault("create_constraint", impl.create_constraint)
+        kw.setdefault("length", impl.length)
         kw.setdefault("_adapted_from", impl)
         if type_api._is_native_for_emulated(impl.__class__):
             kw.setdefault("create_type", impl.create_type)
@@ -503,6 +506,18 @@ class DOMAIN(NamedType, sqltypes.SchemaType):
     def __test_init__(cls):
         return cls("name", sqltypes.Integer)
 
+    def adapt(self, cls, **kw):
+        # the DOMAIN-specific arguments are keyword-only, which are not
+        # picked up by util.constructor_copy(); pass them explicitly so
+        # that copy(), to_metadata() and dialect adaptation retain them
+        kw.setdefault("collation", self.collation)
+        kw.setdefault("default", self.default)
+        kw.setdefault("constraint_name", self.constraint_name)
+        kw.setdefault("not_null", self.not_null)
+        kw.setdefault("check", self.check)
+        kw.setdefault("create_type", self.create_type)
+        return super().adapt(cls, **kw)
+
 
 class CreateEnumType(schema._CreateDropBase):
     __visit_name__ = "create_enum_type"

sqlalchemy/engine/base.py

@@ -742,12 +742,19 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         if self.closed:
             raise exc.ResourceClosedError("This Connection is closed")
 
-        if self._still_open_and_dbapi_connection_is_valid:
-            pool_proxied_connection = self._dbapi_connection
-            assert pool_proxied_connection is not None
-            pool_proxied_connection.invalidate(exception)
-
-        self._dbapi_connection = None
+        try:
+            if self._still_open_and_dbapi_connection_is_valid:
+                pool_proxied_connection = self._dbapi_connection
+                assert pool_proxied_connection is not None
+                pool_proxied_connection.invalidate(exception)
+        finally:
+            # this is always a hard invalidation, which closes the DBAPI
+            # connection; for an asyncio driver that close is an awaited
+            # terminate() which a cancellation can interrupt.  this
+            # Connection is invalidated regardless, so that nothing
+            # further, such as a rollback, is emitted on the DBAPI
+            # connection
+            self._dbapi_connection = None
 
     def detach(self) -> None:
         """Detach the underlying DB-API connection from its connection pool.

sqlalchemy/engine/characteristics.py

@@ -142,7 +142,7 @@ class LoggingTokenCharacteristic(ConnectionCharacteristic):
         if value:
             conn._message_formatter = lambda msg: "[%s] %s" % (value, msg)
         else:
-            del conn._message_formatter
+            conn._message_formatter = None
 
     def get_characteristic(
         self, dialect: Dialect, dbapi_conn: DBAPIConnection

sqlalchemy/engine/create.py

@@ -769,16 +769,26 @@ def create_engine(url: Union[str, _url.URL], **kwargs: Any) -> Engine:
             )
             c._execution_options = util.EMPTY_DICT
 
-            try:
-                dialect.initialize(c)
-            finally:
-                # note that "invalidated" and "closed" are mutually
-                # exclusive in 1.4 Connection.
-                if not c.invalidated and not c.closed:
-                    # transaction is rolled back otherwise, tested by
-                    # test/dialect/postgresql/test_dialect.py
-                    # ::MiscBackendTest::test_initial_transaction_state
-                    dialect.do_rollback(c.connection)
+            dialect.initialize(c)
+
+            # roll back only once initialize() has succeeded, rather than
+            # in a finally: block.  when initialize() raises, the DBAPI
+            # connection may be partway through an operation that c
+            # doesn't know about, such as psycopg's TypeInfo.fetch()
+            # interrupted by a cancellation; the rollback then fails
+            # and its error replaces the original one.  the pool closes
+            # the connection in that case, so there's nothing to roll
+            # back.
+            #
+            # note that "invalidated" and "closed" are mutually
+            # exclusive in 1.4 Connection.  c may be invalidated here if
+            # initialize() caught an error on a statement that was a
+            # disconnect.
+            if not c.invalidated and not c.closed:
+                # transaction is rolled back otherwise, tested by
+                # test/dialect/postgresql/test_dialect.py
+                # ::MiscBackendTest::test_initial_transaction_state
+                dialect.do_rollback(c.connection)
 
         # previously, the "first_connect" event was used here, which was then
         # scaled back if the "on_connect" handler were present.  now,

sqlalchemy/engine/default.py

@@ -16,6 +16,7 @@ as the base class for their own corresponding classes.
 
 from __future__ import annotations
 
+import datetime
 import functools
 import operator
 import random
@@ -602,6 +603,17 @@ class DefaultDialect(Dialect):
         """
         return type_api.adapt_type(typeobj, self.colspecs)
 
+    def min_year_for_type(self, typeobj: TypeEngine[Any]) -> int:
+        """Return the earliest year the database accepts for the given
+        date or datetime type.
+
+        The default implementation returns ``datetime.MINYEAR``.
+
+        .. versionadded:: 2.0.55
+
+        """
+        return datetime.MINYEAR
+
     def has_index(self, connection, table_name, index_name, schema=None, **kw):
         if not self.has_table(connection, table_name, schema=schema, **kw):
             return False
@@ -1883,6 +1895,15 @@ class DefaultExecutionContext(ExecutionContext):
         ):
             self._setup_out_parameters(result)
 
+        if not result._soft_closed and not result._metadata.returns_rows:
+            # no results, get rowcount (which requires open cursor on
+            # some drivers) and release the cursor.  this applies to all
+            # statements that don't return rows, including DML, text(),
+            # DDL and SAVEPOINT
+            if self._rowcount is None:
+                self._rowcount = self.cursor.rowcount
+            result._soft_close()
+
         self._soft_closed = result._soft_closed
 
         if yp:
@@ -2021,12 +2042,6 @@ class DefaultExecutionContext(ExecutionContext):
             # the rows have all been fetched however.
             assert result._metadata.returns_rows
 
-        elif not result._metadata.returns_rows:
-            # no results, get rowcount
-            # (which requires open cursor on some drivers)
-            if self._rowcount is None:
-                self._rowcount = self.cursor.rowcount
-            result._soft_close()
         elif self.isupdate or self.isdelete:
             if self._rowcount is None:
                 self._rowcount = self.cursor.rowcount

sqlalchemy/engine/interfaces.py

@@ -1304,6 +1304,23 @@ class Dialect(EventTarget):
 
         raise NotImplementedError()
 
+    def min_year_for_type(self, typeobj: TypeEngine[Any]) -> int:
+        """Return the earliest year the database accepts for the given
+        date or datetime type.
+
+        The type may be a generic type such as :class:`.DateTime`, in
+        which case the limit is that of the database type the dialect
+        renders for it.  Dialects whose date or datetime types don't
+        accept all years from ``datetime.MINYEAR`` forward override this
+        method; e.g. SQL Server's ``DATETIME`` type, which the dialect
+        renders for :class:`.DateTime`, accepts years from 1753 forward.
+
+        .. versionadded:: 2.0.55
+
+        """
+
+        raise NotImplementedError()
+
     def initialize(self, connection: Connection) -> None:
         """Called during strategized creation of the dialect with a
         connection.
@@ -3261,7 +3278,8 @@ class ExceptionContext:
 
     """
 
-    __slots__ = ()
+    if not TYPE_CHECKING:
+        __slots__ = ()
 
     dialect: Dialect
     """The :class:`_engine.Dialect` in use.

sqlalchemy/ext/asyncio/base.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import abc
+import asyncio
 import functools
 from typing import Any
 from typing import AsyncGenerator
@@ -15,6 +16,7 @@ from typing import AsyncIterator
 from typing import Awaitable
 from typing import Callable
 from typing import ClassVar
+from typing import Coroutine
 from typing import Dict
 from typing import Generator
 from typing import Generic
@@ -37,6 +39,35 @@ _T_co = TypeVar("_T_co", bound=Any, covariant=True)
 _PT = TypeVar("_PT", bound=Any)
 
 
+async def _run_to_completion(coro: Coroutine[Any, Any, _T]) -> _T:
+    """Run ``coro`` in a task of its own and wait for it to complete, even
+    if the calling task is cancelled meanwhile.
+
+    Used for cleanup, such as the ``close()`` performed by an async context
+    manager on exit, that must not be abandoned partway through.  A
+    cancellation received while waiting is re-raised once ``coro`` has
+    completed, so that the caller does not return before its cleanup has
+    finished; were it to return early, the cleanup would carry on in the
+    background, where for example it could return a connection into a pool
+    that the application has meanwhile disposed of.
+
+    """
+    task = asyncio.create_task(coro)
+    cancelled = None
+    while True:
+        try:
+            result = await asyncio.shield(task)
+        except asyncio.CancelledError as err:
+            if task.done():
+                raise
+            cancelled = err
+        else:
+            break
+    if cancelled is not None:
+        raise cancelled
+    return result
+
+
 class ReversibleProxy(Generic[_PT]):
     _proxy_objects: ClassVar[
         Dict[weakref.ref[Any], weakref.ref[ReversibleProxy[Any]]]

sqlalchemy/ext/asyncio/engine.py

@@ -6,7 +6,6 @@
 # the MIT License: https://www.opensource.org/licenses/mit-license.php
 from __future__ import annotations
 
-import asyncio
 import contextlib
 from typing import Any
 from typing import AsyncIterator
@@ -23,6 +22,7 @@ from typing import TypeVar
 from typing import Union
 
 from . import exc as async_exc
+from .base import _run_to_completion
 from .base import asyncstartablecontext
 from .base import GeneratorStartableContext
 from .base import ProxyComparable
@@ -597,8 +597,7 @@ class AsyncConnection(  # type: ignore[misc]
         except GeneratorExit:
             pass
         else:
-            task = asyncio.create_task(ar.close())
-            await asyncio.shield(task)
+            await _run_to_completion(ar.close())
 
     @overload
     async def execute(
@@ -893,8 +892,7 @@ class AsyncConnection(  # type: ignore[misc]
         return self.start().__await__()
 
     async def __aexit__(self, type_: Any, value: Any, traceback: Any) -> None:
-        task = asyncio.create_task(self.close())
-        await asyncio.shield(task)
+        await _run_to_completion(self.close())
 
     # START PROXY METHODS AsyncConnection
 

sqlalchemy/ext/asyncio/session.py

@@ -6,7 +6,6 @@
 # the MIT License: https://www.opensource.org/licenses/mit-license.php
 from __future__ import annotations
 
-import asyncio
 from typing import Any
 from typing import Awaitable
 from typing import Callable
@@ -26,6 +25,7 @@ from typing import TypeVar
 from typing import Union
 
 from . import engine
+from .base import _run_to_completion
 from .base import ReversibleProxy
 from .base import StartableContext
 from .result import _ensure_sync_result
@@ -1067,8 +1067,7 @@ class AsyncSession(ReversibleProxy[Session]):
         return self
 
     async def __aexit__(self, type_: Any, value: Any, traceback: Any) -> None:
-        task = asyncio.create_task(self.close())
-        await asyncio.shield(task)
+        await _run_to_completion(self.close())
 
     def _maker_context_manager(self: _AS) -> _AsyncSessionContextManager[_AS]:
         return _AsyncSessionContextManager(self)
@@ -1800,8 +1799,7 @@ class _AsyncSessionContextManager(Generic[_AS]):
             await self.trans.__aexit__(type_, value, traceback)
             await self.async_session.__aexit__(type_, value, traceback)
 
-        task = asyncio.create_task(go())
-        await asyncio.shield(task)
+        await _run_to_completion(go())
 
 
 class AsyncSessionTransaction(

sqlalchemy/ext/automap.py

@@ -1661,11 +1661,11 @@ def _m2m_relationship(
             overlaps=overlaps,
             secondary=table,
             primaryjoin=and_(
-                fk.column == fk.parent for fk in m2m_const[0].elements
-            ),  # type: ignore [arg-type]
+                *(fk.column == fk.parent for fk in m2m_const[0].elements)
+            ),
             secondaryjoin=and_(
-                fk.column == fk.parent for fk in m2m_const[1].elements
-            ),  # type: ignore [arg-type]
+                *(fk.column == fk.parent for fk in m2m_const[1].elements)
+            ),
             backref=backref_obj,
             collection_class=collection_class,
         )
@@ -1687,11 +1687,11 @@ def _m2m_relationship(
             overlaps=overlaps,
             secondary=table,
             primaryjoin=and_(
-                fk.column == fk.parent for fk in m2m_const[1].elements
-            ),  # type: ignore [arg-type]
+                *(fk.column == fk.parent for fk in m2m_const[1].elements)
+            ),
             secondaryjoin=and_(
-                fk.column == fk.parent for fk in m2m_const[0].elements
-            ),  # type: ignore [arg-type]
+                *(fk.column == fk.parent for fk in m2m_const[0].elements)
+            ),
             back_populates=relationship_name,
             collection_class=collection_class,
         )

sqlalchemy/ext/mutable.py

@@ -844,6 +844,12 @@ class MutableDict(Mutable, Dict[_KT, _VT]):
         dict.update(self, *a, **kw)
         self.changed()
 
+    def __ior__(  # type: ignore[override,misc]
+        self, other: Any
+    ) -> MutableDict[_KT, _VT]:
+        self.update(other)
+        return self
+
     if TYPE_CHECKING:
 
         @overload
@@ -953,6 +959,11 @@ class MutableList(Mutable, List[_T]):
         self.extend(x)
         return self
 
+    def __imul__(self, n: SupportsIndex) -> MutableList[_T]:
+        list.__imul__(self, n)
+        self.changed()
+        return self
+
     def insert(self, i: SupportsIndex, x: _T) -> None:
         list.insert(self, i, x)
         self.changed()

sqlalchemy/orm/bulk_persistence.py

@@ -1916,9 +1916,11 @@ class BulkORMUpdate(BulkUDCompileState, UpdateDMLState):
             # attributes that were formerly modified instead get expired.
             # this only gets hit if the session had pending changes
             # and autoflush were set to False.
-            to_expire = attrib.intersection(dict_).difference(to_evaluate)
-            if to_expire:
-                state._expire_attributes(dict_, to_expire)
+            formerly_modified = attrib.intersection(dict_).difference(
+                to_evaluate
+            )
+            if formerly_modified:
+                state._expire_attributes(dict_, formerly_modified)
 
             states.add(state)
         session._register_altered(states)

sqlalchemy/orm/decl_api.py

@@ -356,6 +356,7 @@ class declared_attr(interfaces._MappedAttribute[_T_co], _declared_attr_common):
             user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id"))
 
             @declared_attr
+            @classmethod
             def user(cls) -> Mapped["User"]:
                 return relationship("User")
 
@@ -366,6 +367,7 @@ class declared_attr(interfaces._MappedAttribute[_T_co], _declared_attr_common):
 
         class CreateTableName:
             @declared_attr.directive
+            @classmethod
             def __tablename__(cls) -> str:
                 return cls.__name__.lower()
 
@@ -383,6 +385,7 @@ class declared_attr(interfaces._MappedAttribute[_T_co], _declared_attr_common):
             type: Mapped[str] = mapped_column(String(50))
 
             @declared_attr.directive
+            @classmethod
             def __mapper_args__(cls) -> Dict[str, Any]:
                 if cls.__name__ == "Employee":
                     return {
@@ -396,11 +399,8 @@ class declared_attr(interfaces._MappedAttribute[_T_co], _declared_attr_common):
         class Engineer(Employee):
             pass
 
-    :class:`_orm.declared_attr` supports decorating functions that are
-    explicitly decorated with ``@classmethod``. This is never necessary from a
-    runtime perspective, however may be needed in order to support :pep:`484`
-    typing tools that don't otherwise recognize the decorated function as
-    having class-level behaviors for the ``cls`` parameter::
+    :class:`_orm.declared_attr` can also be applied to non-directive
+    attributes such as :func:`_orm.column_property`::
 
         class SomethingMixin:
             x: Mapped[int]
@@ -411,6 +411,18 @@ class declared_attr(interfaces._MappedAttribute[_T_co], _declared_attr_common):
             def x_plus_y(cls) -> Mapped[int]:
                 return column_property(cls.x + cls.y)
 
+    .. tip::
+
+       The examples above also apply the ``@classmethod`` decorator.  This is
+       not required at runtime, however :pep:`484` typing tools have no way to
+       recognize ``def foo(cls)`` as a classmethod unless ``@classmethod`` is
+       present.  Adding ``@classmethod`` allows typing tools to correctly
+       infer the ``cls`` parameter as the class, which is important when
+       accessing mapped attributes such as ``cls.ph1`` inside the body of
+       the method.  :class:`_orm.declared_attr` supports both
+       ``@declared_attr`` and ``@declared_attr.directive`` being combined
+       with ``@classmethod``.
+
     .. versionadded:: 2.0 - :class:`_orm.declared_attr` can accommodate a
        function decorated with ``@classmethod`` to help with :pep:`484`
        integration where needed.

sqlalchemy/orm/util.py

@@ -2360,6 +2360,30 @@ def _cleanup_mapped_str_annotation(
     return annotation
 
 
+def _unresolved_annotation_is_mapped(
+    raw_annotation: _AnnotationScanType,
+) -> bool:
+    """given an un-resolvable annotation, guess if its outermost element
+    is ``Mapped[]``.
+
+    Used only to decide whether a ``NameError`` raised while de-stringifying
+    is worth reporting as a mapping error.  The annotation may be a plain
+    string (``__future__`` annotations / explicitly quoted), a ``ForwardRef``
+    (:pep:`649` deferred annotations on Python 3.14 and above), or an
+    already-resolved object.
+
+    """
+    if isinstance(raw_annotation, str):
+        return "Mapped[" in raw_annotation
+    elif isinstance(raw_annotation, typing.ForwardRef):
+        return "Mapped[" in raw_annotation.__forward_arg__
+    else:
+        origin = typing.get_origin(raw_annotation)
+        return isinstance(origin, type) and issubclass(
+            origin, _MappedAnnotationBase
+        )
+
+
 def _extract_mapped_subtype(
     raw_annotation: Optional[_AnnotationScanType],
     cls: type,
@@ -2406,7 +2430,7 @@ def _extract_mapped_subtype(
             "module level. See chained stack trace for more hints."
         ) from ce
     except NameError as ne:
-        if raiseerr and "Mapped[" in raw_annotation:  # type: ignore
+        if raiseerr and _unresolved_annotation_is_mapped(raw_annotation):
             raise orm_exc.MappedAnnotationError(
                 f"Could not interpret annotation {raw_annotation}.  "
                 "Check that it uses names that are correctly imported at the "