← Back
Editing: row.py
# engine/row.py # Copyright (C) 2005-2025 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 List from typing import Mapping from typing import NoReturn from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from ..sql import util as sql_util from ..util import deprecated from ..util._has_cy import HAS_CYEXTENSION if TYPE_CHECKING or not HAS_CYEXTENSION: from ._py_row import BaseRow as BaseRow else: from sqlalchemy.cyextension.resultproxy import BaseRow as BaseRow if TYPE_CHECKING: from .result import _KeyType from .result import _ProcessorsType from .result import RMKeyView _T = TypeVar("_T", bound=Any) _TP = TypeVar("_TP", bound=Tuple[Any, ...]) class Row(BaseRow, Sequence[Any], Generic[_TP]): """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__ = () def __setattr__(self, name: str, value: Any) -> NoReturn: raise AttributeError("can't set attribute") def __delattr__(self, name: str) -> NoReturn: raise AttributeError("can't delete attribute") def _tuple(self) -> _TP: """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:: :attr:`.Row._t` - shorthand attribute notation :meth:`.Result.tuples` """ return self # type: ignore @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) -> _TP: """Return a 'tuple' form of this :class:`.Row`. .. versionadded:: 2.0 """ return self._tuple() @property def _t(self) -> _TP: """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:: :attr:`.Result.t` """ return self # type: ignore @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) -> _TP: """A synonym for :meth:`.Row._tuple`. .. versionadded:: 2.0 """ 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[Any]: 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 __contains__(self, key: Any) -> bool: return key in self._data 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__ if TYPE_CHECKING: @overload def __getitem__(self, index: int) -> Any: ... @overload def __getitem__(self, index: slice) -> Sequence[Any]: ... def __getitem__(self, index: Union[int, slice]) -> Any: ... 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 _values_impl(self) -> List[Any]: return list(self._data) def __iter__(self) -> Iterator[str]: return (k for k in self._parent.keys if k is not None) def __len__(self) -> int: return len(self._data) 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())
Save File
Cancel