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

sqlalchemy/dialects/mssql/base.py

@@ -3315,6 +3315,27 @@ class MSDialect(default._BackendsMultiReflection, 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

@@ -489,15 +489,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/postgresql/base.py

@@ -4846,8 +4846,12 @@ class PGDialect(default._BackendsMultiReflection, 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"),
@@ -5039,8 +5043,12 @@ class PGDialect(default._BackendsMultiReflection, 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,
@@ -5632,8 +5640,12 @@ class PGDialect(default._BackendsMultiReflection, 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/engine/_row_cy.py

@@ -69,7 +69,7 @@ class BaseRow:
             (
                 _apply_processors(processors, data)
                 if processors is not None
-                else data if isinstance(data, tuple) else tuple(data)
+                else data if type(data) is tuple else tuple(data)
             ),
         )
 

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
@@ -829,6 +830,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

sqlalchemy/engine/interfaces.py

@@ -1465,6 +1465,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.
@@ -3437,7 +3454,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
@@ -24,6 +23,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
@@ -606,8 +606,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(
@@ -913,8 +912,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
@@ -30,6 +29,7 @@ from typing import Union
 
 from . import engine
 from . import exc as async_exc
+from .base import _run_to_completion
 from .base import ReversibleProxy
 from .base import StartableContext
 from .result import _ensure_sync_result
@@ -1375,8 +1375,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)
@@ -2121,8 +2120,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/orm/relationships.py

@@ -2620,24 +2620,41 @@ class _JoinCondition:
         return self._has_annotation(self.primaryjoin, "remote")
 
     @util.memoized_property
-    def secondary_covers_parent_primary_key(self) -> bool:
-        """Return True if the "secondary" selectable's join to the parent
-        table contains columns that encompass the complete primary key
-        value of the parent.
+    def secondary_can_be_used_for_related_join(self) -> bool:
+        """Return True if the "secondary" selectable may be joined directly
+        to the related entity in order to load related rows for a set of
+        parent primary key values, omitting the parent table.
 
-        Used in optimizing the selectinload loader strategy to indicate
-        the parent table need not be included in the query, as a complete
-        primary key can be derived from the secondary table.
+        This is the case when the primaryjoin consists only of equality
+        comparisons between the complete primary key of the parent and
+        columns of the secondary.  If the primaryjoin contains any other
+        criteria, it would be lost when the parent table is omitted.
+
+        Used by the selectinload loader strategy for its ``omit_join``
+        optimization.
 
         """
         if self.secondary is None:
             return False
 
-        secondary_synced_parent_cols = util.column_set(
-            l for (l, _) in self.synchronize_pairs
-        )
-        return self.prop.parent._local_pk_cols.issubset(
-            secondary_synced_parent_cols
+        parent_pk_cols = self.prop.parent._local_pk_cols
+        if not parent_pk_cols.issubset(l for (l, _) in self.synchronize_pairs):
+            return False
+
+        # compare against the parent primary key comparisons only; any
+        # other criteria in the primaryjoin, including comparisons of
+        # non-primary key parent columns to the secondary, make the
+        # comparison fail.  compare() treats AND as unordered and "==" as
+        # commutative, so the primaryjoin may state these comparisons in
+        # any order or orientation
+        return self.primaryjoin.compare(
+            sql.and_(
+                *[
+                    l == r
+                    for (l, r) in self.synchronize_pairs
+                    if l in parent_pk_cols
+                ]
+            )
         )
 
     def _annotate_fks(self) -> None:

sqlalchemy/orm/strategies.py

@@ -3029,7 +3029,9 @@ class _SelectInLoader(_PostLoader, util.MemoizedSlots):
                 self.omit_join = lazyloader.use_get
             elif is_m2m and not self.parent_property._is_self_referential:
                 join_cond = self.parent_property._join_condition
-                self.omit_join = join_cond.secondary_covers_parent_primary_key
+                self.omit_join = (
+                    join_cond.secondary_can_be_used_for_related_join
+                )
             else:
                 self.omit_join = self.parent._get_clause[0].compare(
                     lazyloader._rev_lazywhere,

sqlalchemy/pool/base.py

@@ -733,10 +733,21 @@ class _ConnectionRecord(ConnectionPoolEntry):
     def _checkin_failed(
         self, err: BaseException, _fairy_was_created: bool = True
     ) -> None:
-        self.invalidate(e=err)
-        self.checkin(
-            _fairy_was_created=_fairy_was_created,
-        )
+        try:
+            self.invalidate(e=err)
+        finally:
+            if self.dbapi_connection is not None:
+                # invalidate() was itself interrupted, such as by a second
+                # cancellation, before it could close the connection.  keep
+                # the connection so that its close can be retried, but
+                # have the next checkout recycle it rather than use it
+                self._soft_invalidate_time = time.time()
+
+            # the record must be returned in any case; nothing else will
+            # ever return it, as no _ConnectionFairy refers to it
+            self.checkin(
+                _fairy_was_created=_fairy_was_created,
+            )
 
     def checkin(self, _fairy_was_created: bool = True) -> None:
         if self.fairy_ref is None and _fairy_was_created:
@@ -1017,10 +1028,15 @@ def _finalize_fairy(
             pool.logger.error(
                 "Exception during reset or similar", exc_info=True
             )
-            if connection_record:
-                connection_record.invalidate(e=e)
             if not isinstance(e, Exception):
+                # a cancellation or similar propagates from here, so the
+                # checkin() below is not reached; return the record now,
+                # rather than leaving it to garbage collection of the fairy
+                if connection_record:
+                    connection_record._checkin_failed(e)
                 raise
+            if connection_record:
+                connection_record.invalidate(e=e)
         finally:
             if detach and is_gc_cleanup and dont_restore_gced:
                 message = (

sqlalchemy/sql/_elements_constructors.py

@@ -1817,6 +1817,12 @@ def text(text: str) -> TextClause:
 
         t = text(r"SELECT * FROM users WHERE name='\:username'")
 
+    .. note:: A name that is immediately followed by another colon,
+       such as ``:this:that`` or ``:value::int``, is currently not
+       interpreted as a bound parameter and is rendered as literal text;
+       whitespace may be used to separate the name from the colon, e.g.
+       ``:value ::int``.  This behavior may change in a future release.
+
     The :class:`_expression.TextClause`
     construct includes methods which can
     provide information about the bound parameters as well as the column
@@ -1910,6 +1916,26 @@ def tstring(template: Template) -> TString:
         some_json = {"foo": "bar"}
         stmt = tstring(t"SELECT {literal(some_json, JSON)}")
 
+    **Literal SQL Text**:
+
+    The plain string portions of the template are rendered exactly as
+    given.  Unlike :func:`_expression.text`, they are not scanned for
+    bound parameter names in the ``:name`` format, and there are no escaping
+    rules such as ``\:`` for colons; a colon in the template, such as within
+    a quoted SQL string, is rendered unchanged.  A named bound parameter
+    whose value is passed at execution time may be embedded explicitly
+    using :func:`_expression.bindparam`::
+
+        from sqlalchemy import tstring, bindparam, Integer
+
+        user_id = bindparam("user_id", type_=Integer)
+        stmt = tstring(t"SELECT * FROM users WHERE id = {user_id}")
+        result = connection.execute(stmt, {"user_id": 42})
+
+    .. versionchanged:: 2.1.2 The plain string portions of a
+       :func:`_expression.tstring` are no longer scanned for bound parameter
+       names or ``\:`` escapes, as was the case in 2.1.0 and 2.1.1.
+
     **Column Specification**:
 
     Like :func:`_expression.text`, the :func:`_expression.tstring` construct

sqlalchemy/sql/compiler.py

@@ -266,8 +266,8 @@ FK_INITIALLY = re.compile(r"^(?:DEFERRED|IMMEDIATE)$", re.I)
 _WINDOW_EXCLUDE_RE = re.compile(
     r"^(?:CURRENT ROW|GROUP|TIES|NO OTHERS)$", re.I
 )
-BIND_PARAMS = re.compile(r"(?<![:\w\$\x5c]):([\w\$]+)(?![:\w\$])", re.UNICODE)
-BIND_PARAMS_ESC = re.compile(r"\x5c(:[\w\$]*)(?![:\w\$])", re.UNICODE)
+BIND_PARAMS = elements.TextClause._bind_params_regex
+BIND_PARAMS_ESC = re.compile(r"\x5c(:\w*)(?![:\w])", re.UNICODE)
 
 _pyformat_template = "%%(%(name)s)s"
 BIND_TEMPLATES = {
@@ -1422,6 +1422,17 @@ class SQLCompiler(Compiled):
     _positional_pattern = re.compile(
         f"{_pyformat_pattern.pattern}|{_post_compile_pattern.pattern}"
     )
+
+    # variants of the above for dialects that double percent signs in
+    # literal text; a "%%" pair is matched first so that an escaped
+    # percent sign is never taken as the start of a bound parameter
+    _pct_escaped_pyformat_pattern = re.compile(
+        f"%%|{_pyformat_pattern.pattern}"
+    )
+    _pct_escaped_positional_pattern = re.compile(
+        f"%%|{_positional_pattern.pattern}"
+    )
+
     _collect_params: Final[bool]
     _collected_params: util.immutabledict[str, Any]
 
@@ -1733,24 +1744,38 @@ class SQLCompiler(Compiled):
             placeholder = "?"
 
         positions = []
+        binds = self.binds
+
+        if self.escaped_bind_names:
+            reverse_escape = {v: k for k, v in self.escaped_bind_names.items()}
+            assert len(self.escaped_bind_names) == len(reverse_escape)
+        else:
+            reverse_escape = {}
+
+        if self.preparer._double_percents:
+            positional_pattern = self._pct_escaped_positional_pattern
+        else:
+            positional_pattern = self._positional_pattern
 
         def find_position(m: re.Match[str]) -> str:
             normal_bind = m.group(1)
             if normal_bind:
+                if reverse_escape.get(normal_bind, normal_bind) not in binds:
+                    # literal text that looks like a bound parameter
+                    return m.group(0)
                 positions.append(normal_bind)
                 return placeholder
-            else:
+            elif m.group(2):
                 # this a post-compile bind
                 positions.append(m.group(2))
                 return m.group(0)
+            else:
+                # an escaped percent sign
+                return m.group(0)
 
-        self.string = re.sub(
-            self._positional_pattern, find_position, self.string
-        )
+        self.string = re.sub(positional_pattern, find_position, self.string)
 
-        if self.escaped_bind_names:
-            reverse_escape = {v: k for k, v in self.escaped_bind_names.items()}
-            assert len(self.escaped_bind_names) == len(reverse_escape)
+        if reverse_escape:
             self.positiontup = [
                 reverse_escape.get(name, name) for name in positions
             ]
@@ -1761,7 +1786,7 @@ class SQLCompiler(Compiled):
             positions = []
 
             single_values_expr = re.sub(
-                self._positional_pattern,
+                positional_pattern,
                 find_position,
                 self._insertmanyvalues.single_values_expr,
             )
@@ -1769,7 +1794,7 @@ class SQLCompiler(Compiled):
                 (
                     v[0],
                     v[1],
-                    re.sub(self._positional_pattern, find_position, v[2]),
+                    re.sub(positional_pattern, find_position, v[2]),
                     v[3],
                 )
                 for v in self._insertmanyvalues.insert_crud_params
@@ -1829,9 +1854,15 @@ class SQLCompiler(Compiled):
             }
             assert len(param_pos) == len_before
 
-        # Can't use format here since % chars are not escaped.
-        self.string = self._pyformat_pattern.sub(
-            lambda m: param_pos[m.group(1)], self.string
+        if self.preparer._double_percents:
+            pyformat_pattern = self._pct_escaped_pyformat_pattern
+        else:
+            pyformat_pattern = self._pyformat_pattern
+
+        # any match not in param_pos is an escaped percent sign or literal
+        # text that looks like a bound parameter
+        self.string = pyformat_pattern.sub(
+            lambda m: param_pos.get(m.group(1), m.group(0)), self.string
         )
 
         if self._insertmanyvalues:
@@ -2277,9 +2308,16 @@ class SQLCompiler(Compiled):
                     numeric_positiontup, self.next_numeric_pos
                 )
             }
-            # Can't use format here since % chars are not escaped.
-            statement = self._pyformat_pattern.sub(
-                lambda m: param_pos[m.group(1)], statement
+            if self.preparer._double_percents:
+                pyformat_pattern = self._pct_escaped_pyformat_pattern
+            else:
+                pyformat_pattern = self._pyformat_pattern
+
+            # only the expanded parameters are replaced; any other
+            # match is an escaped percent sign or literal text that looks
+            # like a bound parameter
+            statement = pyformat_pattern.sub(
+                lambda m: param_pos.get(m.group(1), m.group(0)), statement
             )
             new_positiontup.extend(numeric_positiontup)
 
@@ -2820,6 +2858,9 @@ class SQLCompiler(Compiled):
             ),
         )
 
+    def visit_tstring_text(self, element, **kw):
+        return self.post_process_text(element.text)
+
     def visit_tstring(self, tstring, add_to_result_map=None, **kw):
         if self._collect_params:
             self._add_to_params(tstring)