SQLAlchemy 2.1.0b1__cp313-cp313-win_arm64.whl

sqlalchemy/engine/row.py

@@ -0,0 +1,397 @@
+# engine/row.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+"""Define row constructs including :class:`.Row`."""
+
+from __future__ import annotations
+
+from abc import ABC
+import collections.abc as collections_abc
+import operator
+import typing
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Generic
+from typing import Iterator
+from typing import Mapping
+from typing import Optional
+from typing import Sequence
+from typing import Tuple
+from typing import TYPE_CHECKING
+
+from ._row_cy import BaseRow as BaseRow
+from ..sql import util as sql_util
+from ..util import deprecated
+from ..util.typing import TypeVarTuple
+from ..util.typing import Unpack
+
+if TYPE_CHECKING:
+    from typing import Tuple as _RowBase
+
+    from .result import _KeyType
+    from .result import _ProcessorsType
+    from .result import RMKeyView
+else:
+    _RowBase = Sequence
+
+
+_Ts = TypeVarTuple("_Ts")
+
+
+class Row(BaseRow, _RowBase[Unpack[_Ts]], Generic[Unpack[_Ts]]):  # type: ignore[misc]  # noqa: E501
+    """Represent a single result row.
+
+    The :class:`.Row` object represents a row of a database result.  It is
+    typically associated in the 1.x series of SQLAlchemy with the
+    :class:`_engine.CursorResult` object, however is also used by the ORM for
+    tuple-like results as of SQLAlchemy 1.4.
+
+    The :class:`.Row` object seeks to act as much like a Python named
+    tuple as possible.   For mapping (i.e. dictionary) behavior on a row,
+    such as testing for containment of keys, refer to the :attr:`.Row._mapping`
+    attribute.
+
+    .. seealso::
+
+        :ref:`tutorial_selecting_data` - includes examples of selecting
+        rows from SELECT statements.
+
+    .. versionchanged:: 1.4
+
+        Renamed ``RowProxy`` to :class:`.Row`. :class:`.Row` is no longer a
+        "proxy" object in that it contains the final form of data within it,
+        and now acts mostly like a named tuple. Mapping-like functionality is
+        moved to the :attr:`.Row._mapping` attribute. See
+        :ref:`change_4710_core` for background on this change.
+
+    """
+
+    __slots__ = ()
+
+    @deprecated(
+        "2.1.0",
+        "The :meth:`.Row._tuple` method is deprecated, :class:`.Row` "
+        "now behaves like a tuple and can unpack types directly.",
+    )
+    def _tuple(self) -> Tuple[Unpack[_Ts]]:
+        """Return a 'tuple' form of this :class:`.Row`.
+
+        At runtime, this method returns "self"; the :class:`.Row` object is
+        already a named tuple. However, at the typing level, if this
+        :class:`.Row` is typed, the "tuple" return type will be a :pep:`484`
+        ``Tuple`` datatype that contains typing information about individual
+        elements, supporting typed unpacking and attribute access.
+
+        .. versionadded:: 2.0.19 - The :meth:`.Row._tuple` method supersedes
+           the previous :meth:`.Row.tuple` method, which is now underscored
+           to avoid name conflicts with column names in the same way as other
+           named-tuple methods on :class:`.Row`.
+
+        .. seealso::
+
+            :ref:`change_10635` - describes a migration path from this
+            workaround for SQLAlchemy 2.1.
+
+            :attr:`.Row._t` - shorthand attribute notation
+
+            :meth:`.Result.tuples`
+
+
+        """
+        return self
+
+    @deprecated(
+        "2.0.19",
+        "The :meth:`.Row.tuple` method is deprecated in favor of "
+        ":meth:`.Row._tuple`; all :class:`.Row` "
+        "methods and library-level attributes are intended to be underscored "
+        "to avoid name conflicts.  Please use :meth:`Row._tuple`.",
+    )
+    def tuple(self) -> Tuple[Unpack[_Ts]]:
+        """Return a 'tuple' form of this :class:`.Row`.
+
+        .. versionadded:: 2.0
+
+        .. seealso::
+
+            :ref:`change_10635` - describes a migration path from this
+            workaround for SQLAlchemy 2.1.
+
+        """
+        return self._tuple()
+
+    @property
+    @deprecated(
+        "2.1.0",
+        "The :attr:`.Row._t` attribute is deprecated, :class:`.Row` "
+        "now behaves like a tuple and can unpack types directly.",
+    )
+    def _t(self) -> Tuple[Unpack[_Ts]]:
+        """A synonym for :meth:`.Row._tuple`.
+
+        .. versionadded:: 2.0.19 - The :attr:`.Row._t` attribute supersedes
+           the previous :attr:`.Row.t` attribute, which is now underscored
+           to avoid name conflicts with column names in the same way as other
+           named-tuple methods on :class:`.Row`.
+
+        .. seealso::
+
+            :ref:`change_10635` - describes a migration path from this
+            workaround for SQLAlchemy 2.1.
+
+            :attr:`.Result.t`
+        """
+        return self
+
+    @property
+    @deprecated(
+        "2.0.19",
+        "The :attr:`.Row.t` attribute is deprecated in favor of "
+        ":attr:`.Row._t`; all :class:`.Row` "
+        "methods and library-level attributes are intended to be underscored "
+        "to avoid name conflicts.  Please use :attr:`Row._t`.",
+    )
+    def t(self) -> Tuple[Unpack[_Ts]]:
+        """A synonym for :meth:`.Row._tuple`.
+
+        .. versionadded:: 2.0
+
+        .. seealso::
+
+            :ref:`change_10635` - describes a migration path from this
+            workaround for SQLAlchemy 2.1.
+
+        """
+        return self._t
+
+    @property
+    def _mapping(self) -> RowMapping:
+        """Return a :class:`.RowMapping` for this :class:`.Row`.
+
+        This object provides a consistent Python mapping (i.e. dictionary)
+        interface for the data contained within the row.   The :class:`.Row`
+        by itself behaves like a named tuple.
+
+        .. seealso::
+
+            :attr:`.Row._fields`
+
+        .. versionadded:: 1.4
+
+        """
+        return RowMapping(self._parent, None, self._key_to_index, self._data)
+
+    def _filter_on_values(
+        self, processor: Optional[_ProcessorsType]
+    ) -> Row[Unpack[_Ts]]:
+        return Row(self._parent, processor, self._key_to_index, self._data)
+
+    if not TYPE_CHECKING:
+
+        def _special_name_accessor(name: str) -> Any:
+            """Handle ambiguous names such as "count" and "index" """
+
+            @property
+            def go(self: Row) -> Any:
+                if self._parent._has_key(name):
+                    return self.__getattr__(name)
+                else:
+
+                    def meth(*arg: Any, **kw: Any) -> Any:
+                        return getattr(collections_abc.Sequence, name)(
+                            self, *arg, **kw
+                        )
+
+                    return meth
+
+            return go
+
+        count = _special_name_accessor("count")
+        index = _special_name_accessor("index")
+
+    def _op(self, other: Any, op: Callable[[Any, Any], bool]) -> bool:
+        return (
+            op(self._to_tuple_instance(), other._to_tuple_instance())
+            if isinstance(other, Row)
+            else op(self._to_tuple_instance(), other)
+        )
+
+    __hash__ = BaseRow.__hash__
+
+    def __lt__(self, other: Any) -> bool:
+        return self._op(other, operator.lt)
+
+    def __le__(self, other: Any) -> bool:
+        return self._op(other, operator.le)
+
+    def __ge__(self, other: Any) -> bool:
+        return self._op(other, operator.ge)
+
+    def __gt__(self, other: Any) -> bool:
+        return self._op(other, operator.gt)
+
+    def __eq__(self, other: Any) -> bool:
+        return self._op(other, operator.eq)
+
+    def __ne__(self, other: Any) -> bool:
+        return self._op(other, operator.ne)
+
+    def __repr__(self) -> str:
+        return repr(sql_util._repr_row(self))
+
+    @property
+    def _fields(self) -> Tuple[str, ...]:
+        """Return a tuple of string keys as represented by this
+        :class:`.Row`.
+
+        The keys can represent the labels of the columns returned by a core
+        statement or the names of the orm classes returned by an orm
+        execution.
+
+        This attribute is analogous to the Python named tuple ``._fields``
+        attribute.
+
+        .. versionadded:: 1.4
+
+        .. seealso::
+
+            :attr:`.Row._mapping`
+
+        """
+        return tuple([k for k in self._parent.keys if k is not None])
+
+    def _asdict(self) -> Dict[str, Any]:
+        """Return a new dict which maps field names to their corresponding
+        values.
+
+        This method is analogous to the Python named tuple ``._asdict()``
+        method, and works by applying the ``dict()`` constructor to the
+        :attr:`.Row._mapping` attribute.
+
+        .. versionadded:: 1.4
+
+        .. seealso::
+
+            :attr:`.Row._mapping`
+
+        """
+        return dict(self._mapping)
+
+
+BaseRowProxy = BaseRow
+RowProxy = Row
+
+
+class ROMappingView(ABC):
+    __slots__ = ()
+
+    _items: Sequence[Any]
+    _mapping: Mapping["_KeyType", Any]
+
+    def __init__(
+        self, mapping: Mapping["_KeyType", Any], items: Sequence[Any]
+    ):
+        self._mapping = mapping  # type: ignore[misc]
+        self._items = items  # type: ignore[misc]
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __repr__(self) -> str:
+        return "{0.__class__.__name__}({0._mapping!r})".format(self)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._items)
+
+    def __contains__(self, item: Any) -> bool:
+        return item in self._items
+
+    def __eq__(self, other: Any) -> bool:
+        return list(other) == list(self)
+
+    def __ne__(self, other: Any) -> bool:
+        return list(other) != list(self)
+
+
+class ROMappingKeysValuesView(
+    ROMappingView, typing.KeysView["_KeyType"], typing.ValuesView[Any]
+):
+    __slots__ = ("_items",)  # mapping slot is provided by KeysView
+
+
+class ROMappingItemsView(ROMappingView, typing.ItemsView["_KeyType", Any]):
+    __slots__ = ("_items",)  # mapping slot is provided by ItemsView
+
+
+class RowMapping(BaseRow, typing.Mapping["_KeyType", Any]):
+    """A ``Mapping`` that maps column names and objects to :class:`.Row`
+    values.
+
+    The :class:`.RowMapping` is available from a :class:`.Row` via the
+    :attr:`.Row._mapping` attribute, as well as from the iterable interface
+    provided by the :class:`.MappingResult` object returned by the
+    :meth:`_engine.Result.mappings` method.
+
+    :class:`.RowMapping` supplies Python mapping (i.e. dictionary) access to
+    the  contents of the row.   This includes support for testing of
+    containment of specific keys (string column names or objects), as well
+    as iteration of keys, values, and items::
+
+        for row in result:
+            if "a" in row._mapping:
+                print("Column 'a': %s" % row._mapping["a"])
+
+            print("Column b: %s" % row._mapping[table.c.b])
+
+    .. versionadded:: 1.4 The :class:`.RowMapping` object replaces the
+       mapping-like access previously provided by a database result row,
+       which now seeks to behave mostly like a named tuple.
+
+    """
+
+    __slots__ = ()
+
+    if TYPE_CHECKING:
+
+        def __getitem__(self, key: _KeyType) -> Any: ...
+
+    else:
+        __getitem__ = BaseRow._get_by_key_impl_mapping
+
+    def __iter__(self) -> Iterator[str]:
+        return (k for k in self._parent.keys if k is not None)
+
+    def __contains__(self, key: object) -> bool:
+        return self._parent._has_key(key)
+
+    def __repr__(self) -> str:
+        return repr(dict(self))
+
+    def items(self) -> ROMappingItemsView:
+        """Return a view of key/value tuples for the elements in the
+        underlying :class:`.Row`.
+
+        """
+        return ROMappingItemsView(
+            self, [(key, self[key]) for key in self.keys()]
+        )
+
+    def keys(self) -> RMKeyView:
+        """Return a view of 'keys' for string column names represented
+        by the underlying :class:`.Row`.
+
+        """
+
+        return self._parent.keys
+
+    def values(self) -> ROMappingKeysValuesView:
+        """Return a view of values for the values represented in the
+        underlying :class:`.Row`.
+
+        """
+        return ROMappingKeysValuesView(self, self._values_impl())

sqlalchemy/engine/strategies.py

@@ -0,0 +1,16 @@
+# engine/strategies.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+"""Deprecated mock engine strategy used by Alembic."""
+
+from __future__ import annotations
+
+from .mock import MockConnection  # noqa
+
+
+class MockEngineStrategy:
+    MockConnection = MockConnection