SQLAlchemy 2.1.4__py3-none-any.whl → 2.1.5__py3-none-any.whl

sqlalchemy/__init__.py

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

sqlalchemy/dialects/oracle/base.py

@@ -2279,7 +2279,10 @@ class OracleDialect(default._BackendsMultiReflection, 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

@@ -5070,8 +5070,9 @@ class PGDialect(default._BackendsMultiReflection, 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|"
@@ -5089,9 +5090,11 @@ class PGDialect(default._BackendsMultiReflection, default.DefaultDialect):
 
         (
             constrained_columns,
+            constrained_period_column,
             referred_schema,
             referred_table,
             referred_columns,
+            referred_period_column,
             _,
             match,
             upddelkey1,
@@ -5103,6 +5106,13 @@ class PGDialect(default._BackendsMultiReflection, 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"

sqlalchemy/engine/base.py

@@ -758,12 +758,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/create.py

@@ -747,16 +747,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/orm/__init__.py

@@ -37,6 +37,7 @@ from ._orm_constructors import outerjoin as outerjoin
 from ._orm_constructors import query_expression as query_expression
 from ._orm_constructors import relationship as relationship
 from ._orm_constructors import synonym as synonym
+from ._orm_constructors import unmapped_column as unmapped_column
 from ._orm_constructors import with_loader_criteria as with_loader_criteria
 from ._orm_constructors import with_polymorphic as with_polymorphic
 from .attributes import AttributeEventToken as AttributeEventToken
@@ -51,6 +52,7 @@ from .base import NotExtension as NotExtension
 from .base import ORMDescriptor as ORMDescriptor
 from .base import PassiveFlag as PassiveFlag
 from .base import SQLORMExpression as SQLORMExpression
+from .base import Unmapped as Unmapped
 from .base import WriteOnlyMapped as WriteOnlyMapped
 from .context import FromStatement as FromStatement
 from .context import QueryContext as QueryContext

sqlalchemy/orm/_orm_constructors.py

@@ -29,6 +29,7 @@ from .descriptor_props import Synonym
 from .interfaces import _AttributeOptions
 from .properties import MappedColumn
 from .properties import MappedSQLExpression
+from .properties import UnmappedColumn
 from .query import AliasOption
 from .relationships import _RelationshipArgumentType
 from .relationships import _RelationshipBackPopulatesArgument
@@ -395,6 +396,139 @@ def mapped_column(
     )
 
 
+def unmapped_column(
+    __name_pos: Optional[
+        Union[str, _TypeEngineArgument[Any], SchemaEventTarget]
+    ] = None,
+    __type_pos: Optional[
+        Union[_TypeEngineArgument[Any], SchemaEventTarget]
+    ] = None,
+    /,
+    *args: SchemaEventTarget,
+    init: Literal[False] = False,
+    nullable: Optional[
+        Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]
+    ] = SchemaConst.NULL_UNSPECIFIED,
+    primary_key: Optional[bool] = False,
+    autoincrement: _AutoIncrementType = "auto",
+    use_existing_column: bool = False,
+    name: Optional[str] = None,
+    type_: Optional[_TypeEngineArgument[Any]] = None,
+    index: Optional[bool] = None,
+    unique: Optional[bool] = None,
+    info: Optional[_InfoType] = None,
+    default: Optional[Any] = _NoArg.NO_ARG,
+    insert_default: Optional[Any] = _NoArg.NO_ARG,
+    onupdate: Optional[Any] = None,
+    server_default: Optional[_ServerDefaultArgument] = None,
+    server_onupdate: Optional[_ServerOnUpdateArgument] = None,
+    quote: Optional[bool] = None,
+    system: bool = False,
+    comment: Optional[str] = None,
+    sort_order: Union[_NoArg, int] = _NoArg.NO_ARG,
+    **kw: Any,
+) -> UnmappedColumn[Any]:
+    r"""declare a :class:`_schema.Column` that is part of the
+    :class:`_schema.Table` for a :ref:`Declarative Table
+    <orm_declarative_table>` mapping, but which is not mapped by the ORM.
+
+    :func:`_orm.unmapped_column` is used with the :class:`_orm.Unmapped`
+    annotation::
+
+        class User(Base):
+            __tablename__ = "user"
+
+            id: Mapped[int] = mapped_column(primary_key=True)
+            name: Mapped[str]
+
+            legacy_name: Unmapped[str | None] = unmapped_column()
+
+    The resulting :class:`_schema.Column` is added to the
+    :class:`_schema.Table` in the same way as one produced by
+    :func:`_orm.mapped_column`, deriving its type and nullability from the
+    annotation, so that the column is present in DDL as well as for schema
+    comparison tools such as Alembic autogenerate.  However, the column is
+    excluded from the mapping, the attribute is removed from the class, and
+    when using :ref:`orm_declarative_native_dataclasses` it is not part of
+    the dataclass.
+
+    A bare ``Unmapped[]`` annotation with no right-hand side is equivalent
+    to ``unmapped_column()`` with no arguments; however, see the note at
+    :class:`_orm.Unmapped` regarding typing tools and dataclasses.
+
+    As the attribute is not part of the Python model, ORM and dataclass
+    oriented arguments of :func:`_orm.mapped_column`, such as
+    ``default_factory`` and ``deferred``, are not part of
+    :func:`_orm.unmapped_column`.
+
+    .. versionadded:: 2.1.5
+
+    .. seealso::
+
+        :ref:`orm_declarative_unmapped_column`
+
+    :param __name: String name to give to the :class:`_schema.Column`;
+     defaults to the attribute name.
+    :param __type: :class:`_types.TypeEngine` type or instance for the
+     :class:`_schema.Column`; if omitted, it is derived from the
+     annotation, or from a :class:`_schema.ForeignKey` if present.
+    :param \*args: Additional positional arguments such as
+     :class:`_schema.ForeignKey` and :class:`_schema.CheckConstraint`,
+     passed through to the :class:`_schema.Column`.
+    :param init: Always ``False``; this parameter is present so that
+     :pep:`681` typing tools omit the attribute from the ``__init__()``
+     method of :ref:`ORM mapped dataclasses
+     <orm_declarative_native_dataclasses>`.
+    :param nullable: whether the column is "NULL" or "NOT NULL"; if omitted,
+     derived from the annotation as with :func:`_orm.mapped_column`.
+    :param primary_key: indicates the :class:`_schema.Column` is part of the
+     table's primary key.  As the mapper requires that its primary key
+     columns be mapped, the columns that the mapper should use for the
+     identity of the class must then be indicated using the
+     :paramref:`_orm.Mapper.primary_key` parameter; see
+     :ref:`orm_declarative_unmapped_column` for an example.
+    :param autoincrement: Passed directly to the
+     :paramref:`_schema.Column.autoincrement` parameter.
+    :param use_existing_column: see
+     :paramref:`_orm.mapped_column.use_existing_column`.
+    :param default: Passed directly to the :paramref:`_schema.Column.default`
+     parameter.  As the attribute is not part of a dataclass, this is
+     strictly a Core column default.
+    :param insert_default: synonym for
+     :paramref:`_orm.unmapped_column.default`.
+    :param sort_order: see :paramref:`_orm.mapped_column.sort_order`.
+    :param \**kw: All remaining keyword arguments are passed through to the
+     constructor for the :class:`_schema.Column`, including dialect-specific
+     arguments.
+
+    """
+
+    return UnmappedColumn(
+        __name_pos,
+        __type_pos,
+        *args,
+        name=name,
+        type_=type_,
+        default=default,
+        insert_default=insert_default,
+        index=index,
+        unique=unique,
+        info=info,
+        nullable=nullable,
+        primary_key=primary_key,
+        autoincrement=autoincrement,
+        onupdate=onupdate,
+        server_default=server_default,
+        server_onupdate=server_onupdate,
+        use_existing_column=use_existing_column,
+        quote=quote,
+        comment=comment,
+        system=system,
+        sort_order=sort_order,
+        **kw,
+    )
+
+
 def orm_insert_sentinel(
     name: Optional[str] = None,
     type_: Optional[_TypeEngineArgument[Any]] = None,

sqlalchemy/orm/base.py

@@ -881,6 +881,60 @@ class _DeclarativeMapped(Mapped[_T_co], _MappedAttribute[_T_co]):
         return NotImplemented
 
 
+class Unmapped(_MappedAnnotationBase[_T_co]):
+    """Represent a database column that is part of the mapped
+    :class:`_schema.Table`, but is not mapped by the ORM.
+
+    The :class:`_orm.Unmapped` type annotation is used in an
+    :ref:`Annotated Declarative Table <orm_declarative_mapped_column>`
+    mapping, in conjunction with the :func:`_orm.unmapped_column`
+    construct, to indicate a column that should be present in the
+    :class:`_schema.Table` generated for the class, while not being part
+    of the Python model at all.  The type and nullability of the
+    :class:`_schema.Column` are derived from the annotation in the same
+    way as for :class:`_orm.Mapped`.
+
+    E.g.::
+
+        class User(Base):
+            __tablename__ = "user"
+
+            id: Mapped[int] = mapped_column(primary_key=True)
+            name: Mapped[str]
+
+            legacy_name: Unmapped[str | None] = unmapped_column()
+
+    The ``legacy_name`` column is part of ``User.__table__``, but there is
+    no ``User.legacy_name`` attribute, and when using
+    :ref:`orm_declarative_native_dataclasses`, it is not part of the
+    dataclass.
+
+    A bare ``Unmapped[]`` annotation with no right-hand side is equivalent to
+    ``unmapped_column()`` with no arguments.  When using
+    :ref:`orm_declarative_native_dataclasses`, the attribute is omitted from
+    the dataclass and its ``__init__()`` method in both cases; however,
+    :pep:`681` typing tools are only able to determine this when
+    :func:`_orm.unmapped_column` is present, and otherwise see the attribute
+    as a required ``__init__()`` argument, so it should always be included
+    in that case.
+
+    .. versionadded:: 2.1.5
+
+    .. seealso::
+
+        :ref:`orm_declarative_unmapped_column`
+
+        :func:`_orm.unmapped_column`
+
+    """
+
+    __slots__ = ()
+
+
+def _is_unmapped_container(mapped_container: Optional[type]) -> bool:
+    return mapped_container is Unmapped
+
+
 class DynamicMapped(_MappedAnnotationBase[_T_co]):
     """Represent the ORM mapped attribute type for a "dynamic" relationship.
 

sqlalchemy/orm/bulk_persistence.py

@@ -1933,9 +1933,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

@@ -43,6 +43,7 @@ from ._orm_constructors import deferred
 from ._orm_constructors import mapped_column
 from ._orm_constructors import relationship
 from ._orm_constructors import synonym
+from ._orm_constructors import unmapped_column
 from .attributes import InstrumentedAttribute
 from .base import _inspect_mapped_class
 from .base import _is_mapped_class
@@ -166,6 +167,7 @@ class DeclarativeAttributeIntercept(
         Composite,
         Synonym,
         mapped_column,
+        unmapped_column,
         relationship,
         composite,
         synonym,
@@ -361,6 +363,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")
 
@@ -371,6 +374,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()
 
@@ -388,6 +392,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 {
@@ -401,11 +406,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]
@@ -416,6 +418,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.
@@ -1701,6 +1715,7 @@ class registry(EventTarget):
             Composite,
             Synonym,
             mapped_column,
+            unmapped_column,
             relationship,
             composite,
             synonym,
@@ -2165,6 +2180,7 @@ def as_declarative(**kw: Any) -> Callable[[Type[_T]], Type[_T]]:
         Composite,
         Synonym,
         mapped_column,
+        unmapped_column,
         relationship,
         composite,
         synonym,
@@ -2250,6 +2266,7 @@ def _inspect_decl_meta(cls: Type[Any]) -> Optional[Mapper[Any]]:
         Composite,
         Synonym,
         mapped_column,
+        unmapped_column,
         relationship,
         composite,
         synonym,