SQLAlchemy 2.0.42__py3-none-any.whl → 2.0.44__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.42"
+__version__ = "2.0.44"
 
 
 def __go(lcls: Any) -> None:

sqlalchemy/connectors/asyncio.py

@@ -19,11 +19,15 @@ from typing import Iterator
 from typing import NoReturn
 from typing import Optional
 from typing import Sequence
+from typing import Tuple
+from typing import Type
 from typing import TYPE_CHECKING
 
 from ..engine import AdaptedConnection
+from ..util import EMPTY_DICT
 from ..util.concurrency import await_fallback
 from ..util.concurrency import await_only
+from ..util.concurrency import in_greenlet
 from ..util.typing import Protocol
 
 if TYPE_CHECKING:
@@ -129,8 +133,11 @@ class AsyncAdapt_dbapi_cursor:
         "await_",
         "_cursor",
         "_rows",
+        "_soft_closed_memoized",
     )
 
+    _awaitable_cursor_close: bool = True
+
     _cursor: AsyncIODBAPICursor
     _adapt_connection: AsyncAdapt_dbapi_connection
     _connection: AsyncIODBAPIConnection
@@ -144,7 +151,7 @@ class AsyncAdapt_dbapi_cursor:
 
         cursor = self._make_new_cursor(self._connection)
         self._cursor = self._aenter_cursor(cursor)
-
+        self._soft_closed_memoized = EMPTY_DICT
         if not self.server_side:
             self._rows = collections.deque()
 
@@ -158,6 +165,8 @@ class AsyncAdapt_dbapi_cursor:
 
     @property
     def description(self) -> Optional[_DBAPICursorDescription]:
+        if "description" in self._soft_closed_memoized:
+            return self._soft_closed_memoized["description"]  # type: ignore[no-any-return]  # noqa: E501
         return self._cursor.description
 
     @property
@@ -176,11 +185,40 @@ class AsyncAdapt_dbapi_cursor:
     def lastrowid(self) -> int:
         return self._cursor.lastrowid
 
+    async def _async_soft_close(self) -> None:
+        """close the cursor but keep the results pending, and memoize the
+        description.
+
+        .. versionadded:: 2.0.44
+
+        """
+
+        if not self._awaitable_cursor_close or self.server_side:
+            return
+
+        self._soft_closed_memoized = self._soft_closed_memoized.union(
+            {
+                "description": self._cursor.description,
+            }
+        )
+        await self._cursor.close()
+
     def close(self) -> None:
-        # note we aren't actually closing the cursor here,
-        # we are just letting GC do it.  see notes in aiomysql dialect
         self._rows.clear()
 
+        # updated as of 2.0.44
+        # try to "close" the cursor based on what we know about the driver
+        # and if we are able to.  otherwise, hope that the asyncio
+        # extension called _async_soft_close() if the cursor is going into
+        # a sync context
+        if self._cursor is None or bool(self._soft_closed_memoized):
+            return
+
+        if not self._awaitable_cursor_close:
+            self._cursor.close()  # type: ignore[unused-coroutine]
+        elif in_greenlet():
+            self.await_(self._cursor.close())
+
     def execute(
         self,
         operation: Any,
@@ -349,3 +387,43 @@ class AsyncAdaptFallback_dbapi_connection(AsyncAdapt_dbapi_connection):
     __slots__ = ()
 
     await_ = staticmethod(await_fallback)
+
+
+class AsyncAdapt_terminate:
+    """Mixin for a AsyncAdapt_dbapi_connection to add terminate support."""
+
+    __slots__ = ()
+
+    def terminate(self) -> None:
+        if in_greenlet():
+            # in a greenlet; this is the connection was invalidated case.
+            try:
+                # try to gracefully close; see #10717
+                self.await_(asyncio.shield(self._terminate_graceful_close()))  # type: ignore[attr-defined] # noqa: E501
+            except self._terminate_handled_exceptions() as e:
+                # in the case where we are recycling an old connection
+                # that may have already been disconnected, close() will
+                # fail.  In this case, terminate
+                # the connection without any further waiting.
+                # see issue #8419
+                self._terminate_force_close()
+                if isinstance(e, asyncio.CancelledError):
+                    # re-raise CancelledError if we were cancelled
+                    raise
+        else:
+            # not in a greenlet; this is the gc cleanup case
+            self._terminate_force_close()
+
+    def _terminate_handled_exceptions(self) -> Tuple[Type[BaseException], ...]:
+        """Returns the exceptions that should be handled when
+        calling _graceful_close.
+        """
+        return (asyncio.TimeoutError, asyncio.CancelledError, OSError)
+
+    async def _terminate_graceful_close(self) -> None:
+        """Try to close connection gracefully"""
+        raise NotImplementedError
+
+    def _terminate_force_close(self) -> None:
+        """Terminate the connection"""
+        raise NotImplementedError

sqlalchemy/connectors/pyodbc.py

@@ -243,3 +243,8 @@ class PyODBCConnector(Connector):
         else:
             dbapi_connection.autocommit = False
             super().set_isolation_level(dbapi_connection, level)
+
+    def detect_autocommit_setting(
+        self, dbapi_conn: interfaces.DBAPIConnection
+    ) -> bool:
+        return bool(dbapi_conn.autocommit)

sqlalchemy/dialects/mssql/base.py

@@ -3503,6 +3503,9 @@ join sys.schemas as sch on
 where
     tab.name = :tabname
     and sch.name = :schname
+order by
+    ind_col.index_id,
+    ind_col.key_ordinal
             """
             )
             .bindparams(
@@ -3998,6 +4001,8 @@ index_info AS (
             index_info.index_schema = fk_info.unique_constraint_schema
             AND index_info.index_name = fk_info.unique_constraint_name
             AND index_info.ordinal_position = fk_info.ordinal_position
+            AND NOT (index_info.table_schema = fk_info.table_schema
+                     AND index_info.table_name = fk_info.table_name)
 
     ORDER BY fk_info.constraint_schema, fk_info.constraint_name,
         fk_info.ordinal_position

sqlalchemy/dialects/mysql/aiomysql.py

@@ -45,6 +45,7 @@ from ...connectors.asyncio import AsyncAdapt_dbapi_connection
 from ...connectors.asyncio import AsyncAdapt_dbapi_cursor
 from ...connectors.asyncio import AsyncAdapt_dbapi_module
 from ...connectors.asyncio import AsyncAdapt_dbapi_ss_cursor
+from ...connectors.asyncio import AsyncAdapt_terminate
 from ...util.concurrency import await_fallback
 from ...util.concurrency import await_only
 
@@ -82,7 +83,9 @@ class AsyncAdapt_aiomysql_ss_cursor(
         )
 
 
-class AsyncAdapt_aiomysql_connection(AsyncAdapt_dbapi_connection):
+class AsyncAdapt_aiomysql_connection(
+    AsyncAdapt_terminate, AsyncAdapt_dbapi_connection
+):
     __slots__ = ()
 
     _cursor_cls = AsyncAdapt_aiomysql_cursor
@@ -98,13 +101,19 @@ class AsyncAdapt_aiomysql_connection(AsyncAdapt_dbapi_connection):
     def autocommit(self, value: Any) -> None:
         self.await_(self._connection.autocommit(value))
 
-    def terminate(self) -> None:
-        # it's not awaitable.
-        self._connection.close()
+    def get_autocommit(self) -> bool:
+        return self._connection.get_autocommit()  # type: ignore
 
     def close(self) -> None:
         self.await_(self._connection.ensure_closed())
 
+    async def _terminate_graceful_close(self) -> None:
+        await self._connection.ensure_closed()
+
+    def _terminate_force_close(self) -> None:
+        # it's not awaitable.
+        self._connection.close()
+
 
 class AsyncAdaptFallback_aiomysql_connection(AsyncAdapt_aiomysql_connection):
     __slots__ = ()

sqlalchemy/dialects/mysql/asyncmy.py

@@ -42,6 +42,7 @@ from ...connectors.asyncio import AsyncAdapt_dbapi_connection
 from ...connectors.asyncio import AsyncAdapt_dbapi_cursor
 from ...connectors.asyncio import AsyncAdapt_dbapi_module
 from ...connectors.asyncio import AsyncAdapt_dbapi_ss_cursor
+from ...connectors.asyncio import AsyncAdapt_terminate
 from ...util.concurrency import await_fallback
 from ...util.concurrency import await_only
 
@@ -73,7 +74,9 @@ class AsyncAdapt_asyncmy_ss_cursor(
         )
 
 
-class AsyncAdapt_asyncmy_connection(AsyncAdapt_dbapi_connection):
+class AsyncAdapt_asyncmy_connection(
+    AsyncAdapt_terminate, AsyncAdapt_dbapi_connection
+):
     __slots__ = ()
 
     _cursor_cls = AsyncAdapt_asyncmy_cursor
@@ -104,13 +107,19 @@ class AsyncAdapt_asyncmy_connection(AsyncAdapt_dbapi_connection):
     def autocommit(self, value: Any) -> None:
         self.await_(self._connection.autocommit(value))
 
-    def terminate(self) -> None:
-        # it's not awaitable.
-        self._connection.close()
+    def get_autocommit(self) -> bool:
+        return self._connection.get_autocommit()  # type: ignore
 
     def close(self) -> None:
         self.await_(self._connection.ensure_closed())
 
+    async def _terminate_graceful_close(self) -> None:
+        await self._connection.ensure_closed()
+
+    def _terminate_force_close(self) -> None:
+        # it's not awaitable.
+        self._connection.close()
+
 
 class AsyncAdaptFallback_asyncmy_connection(AsyncAdapt_asyncmy_connection):
     __slots__ = ()

sqlalchemy/dialects/mysql/mariadbconnector.py

@@ -253,6 +253,9 @@ class MySQLDialect_mariadbconnector(MySQLDialect):
             "AUTOCOMMIT",
         )
 
+    def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
+        return bool(dbapi_conn.autocommit)
+
     def set_isolation_level(
         self, dbapi_connection: DBAPIConnection, level: IsolationLevel
     ) -> None:

sqlalchemy/dialects/mysql/mysqlconnector.py

@@ -277,6 +277,9 @@ class MySQLDialect_mysqlconnector(MySQLDialect):
             "AUTOCOMMIT",
         )
 
+    def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
+        return bool(dbapi_conn.autocommit)
+
     def set_isolation_level(
         self, dbapi_connection: DBAPIConnection, level: IsolationLevel
     ) -> None:

sqlalchemy/dialects/mysql/mysqldb.py

@@ -298,6 +298,9 @@ class MySQLDialect_mysqldb(MySQLDialect):
             "AUTOCOMMIT",
         )
 
+    def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
+        return dbapi_conn.get_autocommit()  # type: ignore[no-any-return]
+
     def set_isolation_level(
         self, dbapi_connection: DBAPIConnection, level: IsolationLevel
     ) -> None:

sqlalchemy/dialects/oracle/__init__.py

@@ -35,8 +35,10 @@ from .base import VARCHAR2
 from .base import VECTOR
 from .base import VectorIndexConfig
 from .base import VectorIndexType
+from .vector import SparseVector
 from .vector import VectorDistanceType
 from .vector import VectorStorageFormat
+from .vector import VectorStorageType
 
 # Alias oracledb also as oracledb_async
 oracledb_async = type(
@@ -74,4 +76,6 @@ __all__ = (
     "VectorIndexType",
     "VectorIndexConfig",
     "VectorStorageFormat",
+    "VectorStorageType",
+    "SparseVector",
 )

sqlalchemy/dialects/oracle/base.py

@@ -729,8 +729,22 @@ VECTOR Datatype
 
 Oracle Database 23ai introduced a new VECTOR datatype for artificial intelligence
 and machine learning search operations. The VECTOR datatype is a homogeneous array
-of 8-bit signed integers, 8-bit unsigned integers (binary), 32-bit floating-point numbers,
-or 64-bit floating-point numbers.
+of 8-bit signed integers, 8-bit unsigned integers (binary), 32-bit floating-point
+numbers, or 64-bit floating-point numbers.
+
+A vector's storage type can be either DENSE or SPARSE. A dense vector contains
+meaningful values in most or all of its dimensions. In contrast, a sparse vector
+has non-zero values in only a few dimensions, with the majority being zero.
+
+Sparse vectors are represented by the total number of vector dimensions, an array
+of indices, and an array of values where each value’s location in the vector is
+indicated by the corresponding indices array position. All other vector values are
+treated as zero.
+
+The storage formats that can be used with sparse vectors are float32, float64, and
+int8. Note that the binary storage format cannot be used with sparse vectors.
+
+Sparse vectors are supported when you are using Oracle Database 23.7 or later.
 
 .. seealso::
 
@@ -738,17 +752,26 @@ or 64-bit floating-point numbers.
     <https://python-oracledb.readthedocs.io/en/latest/user_guide/vector_data_type.html>`_ - in the documentation
     for the :ref:`oracledb` driver.
 
-.. versionadded:: 2.0.41
+.. versionadded:: 2.0.41 - Added VECTOR datatype
+
+.. versionadded:: 2.0.43 - Added DENSE/SPARSE support
 
 CREATE TABLE support for VECTOR
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-With the :class:`.VECTOR` datatype, you can specify the dimension for the data
-and the storage format. Valid values for storage format are enum values from
-:class:`.VectorStorageFormat`. To create a table that includes a
-:class:`.VECTOR` column::
+With the :class:`.VECTOR` datatype, you can specify the number of dimensions,
+the storage format, and the storage type for the data. Valid values for the
+storage format are enum members of :class:`.VectorStorageFormat`. Valid values
+for the storage type are enum members of :class:`.VectorStorageType`. If
+storage type is not specified, a DENSE vector is created by default.
+
+To create a table that includes a :class:`.VECTOR` column::
 
-    from sqlalchemy.dialects.oracle import VECTOR, VectorStorageFormat
+    from sqlalchemy.dialects.oracle import (
+        VECTOR,
+        VectorStorageFormat,
+        VectorStorageType,
+    )
 
     t = Table(
         "t1",
@@ -756,7 +779,11 @@ and the storage format. Valid values for storage format are enum values from
         Column("id", Integer, primary_key=True),
         Column(
             "embedding",
-            VECTOR(dim=3, storage_format=VectorStorageFormat.FLOAT32),
+            VECTOR(
+                dim=3,
+                storage_format=VectorStorageFormat.FLOAT32,
+                storage_type=VectorStorageType.SPARSE,
+            ),
         ),
         Column(...),
         ...,
@@ -764,31 +791,40 @@ and the storage format. Valid values for storage format are enum values from
 
 Vectors can also be defined with an arbitrary number of dimensions and formats.
 This allows you to specify vectors of different dimensions with the various
-storage formats mentioned above.
+storage formats mentioned below.
 
 **Examples**
 
-* In this case, the storage format is flexible, allowing any vector type data to be inserted,
-  such as INT8 or BINARY etc::
+* In this case, the storage format is flexible, allowing any vector type data to be
+  inserted, such as INT8 or BINARY etc::
 
     vector_col: Mapped[array.array] = mapped_column(VECTOR(dim=3))
 
-* The dimension is flexible in this case, meaning that any dimension vector can be used::
+* The dimension is flexible in this case, meaning that any dimension vector can
+  be used::
 
     vector_col: Mapped[array.array] = mapped_column(
         VECTOR(storage_format=VectorStorageType.INT8)
     )
 
-* Both the dimensions and the storage format are flexible::
+* Both the dimensions and the storage format are flexible. It creates a DENSE vector::
 
     vector_col: Mapped[array.array] = mapped_column(VECTOR)
 
+* To create a SPARSE vector with both dimensions and the storage format as flexible,
+  use the :attr:`.VectorStorageType.SPARSE` storage type::
+
+    vector_col: Mapped[array.array] = mapped_column(
+        VECTOR(storage_type=VectorStorageType.SPARSE)
+    )
+
 Python Datatypes for VECTOR
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 VECTOR data can be inserted using Python list or Python ``array.array()`` objects.
-Python arrays of type FLOAT (32-bit), DOUBLE (64-bit), or INT (8-bit signed integer)
-are used as bind values when inserting VECTOR columns::
+Python arrays of type FLOAT (32-bit), DOUBLE (64-bit), INT (8-bit signed integers),
+or BINARY (8-bit unsigned integers) are used as bind values when inserting
+VECTOR columns::
 
     from sqlalchemy import insert, select
 
@@ -798,6 +834,21 @@ are used as bind values when inserting VECTOR columns::
             {"id": 1, "embedding": [1, 2, 3]},
         )
 
+Data can be inserted into a sparse vector using the :class:`_oracle.SparseVector`
+class, creating an object consisting of the number of dimensions, an array of indices, and a
+corresponding array of values::
+
+    from sqlalchemy import insert, select
+    from sqlalchemy.dialects.oracle import SparseVector
+
+    sparse_val = SparseVector(10, [1, 2], array.array("d", [23.45, 221.22]))
+
+    with engine.begin() as conn:
+        conn.execute(
+            insert(t1),
+            {"id": 1, "embedding": sparse_val},
+        )
+
 VECTOR Indexes
 ~~~~~~~~~~~~~~
 
@@ -805,6 +856,8 @@ The VECTOR feature supports an Oracle-specific parameter ``oracle_vector``
 on the :class:`.Index` construct, which allows the construction of VECTOR
 indexes.
 
+SPARSE vectors cannot be used in the creation of vector indexes.
+
 To utilize VECTOR indexing, set the ``oracle_vector`` parameter to True to use
 the default values provided by Oracle. HNSW is the default indexing method::
 
@@ -1157,14 +1210,16 @@ class OracleTypeCompiler(compiler.GenericTypeCompiler):
         return "ROWID"
 
     def visit_VECTOR(self, type_, **kw):
-        if type_.dim is None and type_.storage_format is None:
-            return "VECTOR(*,*)"
-        elif type_.storage_format is None:
-            return f"VECTOR({type_.dim},*)"
-        elif type_.dim is None:
-            return f"VECTOR(*,{type_.storage_format.value})"
-        else:
-            return f"VECTOR({type_.dim},{type_.storage_format.value})"
+        dim = type_.dim if type_.dim is not None else "*"
+        storage_format = (
+            type_.storage_format.value
+            if type_.storage_format is not None
+            else "*"
+        )
+        storage_type = (
+            type_.storage_type.value if type_.storage_type is not None else "*"
+        )
+        return f"VECTOR({dim},{storage_format},{storage_type})"
 
 
 class OracleCompiler(compiler.SQLCompiler):

sqlalchemy/dialects/oracle/cx_oracle.py

@@ -1234,6 +1234,9 @@ class OracleDialect_cx_oracle(OracleDialect):
             with dbapi_connection.cursor() as cursor:
                 cursor.execute(f"ALTER SESSION SET ISOLATION_LEVEL={level}")
 
+    def detect_autocommit_setting(self, dbapi_conn) -> bool:
+        return bool(dbapi_conn.autocommit)
+
     def _detect_decimal_char(self, connection):
         # we have the option to change this setting upon connect,
         # or just look at what it is upon connect and convert.

sqlalchemy/dialects/oracle/oracledb.py

@@ -736,6 +736,8 @@ class OracleDialect_oracledb(_cx_oracle.OracleDialect_cx_oracle):
 
 class AsyncAdapt_oracledb_cursor(AsyncAdapt_dbapi_cursor):
     _cursor: AsyncCursor
+    _awaitable_cursor_close: bool = False
+
     __slots__ = ()
 
     @property
@@ -749,10 +751,6 @@ class AsyncAdapt_oracledb_cursor(AsyncAdapt_dbapi_cursor):
     def var(self, *args, **kwargs):
         return self._cursor.var(*args, **kwargs)
 
-    def close(self):
-        self._rows.clear()
-        self._cursor.close()
-
     def setinputsizes(self, *args: Any, **kwargs: Any) -> Any:
         return self._cursor.setinputsizes(*args, **kwargs)