FIX: Make RowMapping lookup/membership agree with iteration

RowMapping.__getitem__ delegated to Row.__getitem__, which resolves case-insensitive names (lowercase mode) and catalog aliases that __iter__ never yields, violating the Mapping contract (e.g. 'MixedCase' in row._mapping was True while list(row._mapping) had only 'mixedcase'). Restrict the view's lookup/membership to the canonical _mapping_keys() so keys, 'in' and '[]' always agree; Row-level case-insensitive access is unchanged. Also document duplicate-label, reserved-name, and fallback-ordering caveats, and add lowercase + catalog-alias regressions.

Author: jahnvi480

mssql_python/row.py

@@ -236,21 +236,43 @@ def __getattr__(self, name: str) -> Any:
 
     @property
     def _mapping(self) -> "RowMapping":
-        """Read-only dict-like view (column name -> value) over this row.
-
-        Returns a ``collections.abc.Mapping``; use ``dict(row._mapping)`` for a plain
-        dict, ``row._mapping.items()`` for name/value pairs, and ``iter(row._mapping)``
-        for column names. Names are order-preserving and de-duplicated (last column
-        wins for a repeated name, matching subscript and attribute access).
+        """Read-only ``dict``-like view (column name -> value) over this row.
+
+        Returns a :class:`RowMapping` (a ``collections.abc.Mapping``). Typical use::
+
+            row = cursor.fetchone()
+            dict(row._mapping)                     # {'id': 1, 'name': 'Alice'}
+            for name, value in row._mapping.items():
+                ...
+            row._mapping["name"]                    # value by column name
+            "name" in row._mapping                  # membership by column name
+
+        Semantics and caveats:
+
+        - Keys are the result set's column names, order-preserving and
+          de-duplicated: when a name repeats, one key is kept and the last column
+          with that name supplies its value (matching ``row[name]`` / ``row.name``).
+          Every duplicate value stays reachable positionally via ``row[i]``.
+        - Lookup and membership use the canonical column names exactly, so the key
+          set, ``in`` and ``[]`` always agree. Unlike ``row[name]`` / ``row.name``,
+          the view does NOT resolve case-insensitive names or catalog aliases; with
+          ``lowercase=True`` the keys are the lowercased names.
+        - ``_mapping`` is a property, so a column literally named ``_mapping`` is
+          shadowed: read it with ``row["_mapping"]`` or ``row._mapping["_mapping"]``.
         """
         return RowMapping(self)
 
     def _mapping_keys(self) -> tuple:
         """Canonical, order-preserving column names backing ``_mapping``.
 
-        Prefers the names snapshotted once by the cursor for the result set. When a
-        row was built without that snapshot, reconstructs names from ``_column_map``
-        (one name per column index); returns ``()`` when neither is available.
+        Prefers the names snapshotted once by the cursor for the result set, which
+        preserve the result set's column order. When a row was built without that
+        snapshot (e.g. a direct ``Row(values, column_map)`` construction), names are
+        reconstructed from ``_column_map`` in column-index order; that order can
+        differ from ``_column_map``'s insertion order, so a directly-constructed row
+        may key differently from an otherwise-equivalent cursor row. Returns ``()``
+        when neither source is available. Normal cursor fetches always supply the
+        snapshot.
         """
         if self._column_names is not None:
             return self._column_names
@@ -310,10 +332,11 @@ def __repr__(self) -> str:
 class RowMapping(Mapping):
     """Read-only ``Mapping`` view over a :class:`Row` (column name -> value).
 
-    Created via :attr:`Row._mapping`. Keys are the row's column names, order-
-    preserving and de-duplicated (last column wins for a repeated name, matching
-    ``row[name]`` / ``row.name``). The view reflects the row it wraps and copies
-    no values.
+    Created via :attr:`Row._mapping`. Keys are the row's canonical column names,
+    order-preserving and de-duplicated (last column wins for a repeated name).
+    Lookup and membership use those names exactly -- no case-insensitive or catalog
+    alias resolution -- so iteration, ``in`` and ``[]`` always agree. The view
+    reflects the row it wraps and copies no values.
     """
 
     __slots__ = ("_row",)
@@ -322,11 +345,13 @@ def __init__(self, row: "Row") -> None:
         self._row = row
 
     def __getitem__(self, key: str) -> Any:
-        if isinstance(key, str):
-            try:
-                return self._row[key]
-            except KeyError:
-                raise KeyError(key) from None
+        # Restrict lookups to the canonical column names yielded by __iter__ so
+        # membership and lookup agree with iteration (proper Mapping semantics).
+        # Row.__getitem__ additionally accepts case-insensitive names and catalog
+        # aliases, but those are not iterated keys, so the view must not resolve
+        # them here.
+        if isinstance(key, str) and key in self._row._mapping_keys():
+            return self._row[key]
         raise KeyError(key)
 
     def __iter__(self):

tests/test_001_globals.py

@@ -1059,3 +1059,41 @@ def test_row_string_key_case_insensitive_with_lowercase():
     # Non-existent attribute raises AttributeError
     with pytest.raises(AttributeError):
         row.nonexistent
+
+
+def test_row_mapping_lookup_agrees_with_iteration_aliases():
+    """RowMapping ignores case-insensitive names and catalog aliases (Mapping contract).
+
+    Metadata result sets store several keys per column index in _column_map (exact,
+    lowercase, and ODBC 2.x/3.x aliases). The mapping view must expose only the
+    canonical snapshot names it iterates, so lookup and membership never accept a
+    name the view does not yield.
+    """
+    from mssql_python.row import Row
+
+    # One physical column at index 0, reachable in _column_map under several names.
+    column_map = {"TABLE_NAME": 0, "table_name": 0, "TABLE_QUALIFIER": 0}
+    row = Row(
+        ["dbo"],
+        column_map,
+        cursor=None,
+        column_names=("TABLE_NAME",),
+    )
+    mapping = row._mapping
+
+    # Canonical key set == iteration == the snapshot.
+    assert list(mapping) == ["TABLE_NAME"]
+    assert dict(mapping) == {"TABLE_NAME": "dbo"}
+    assert mapping["TABLE_NAME"] == "dbo"
+    assert "TABLE_NAME" in mapping
+
+    # Row still resolves the aliases directly (unchanged behavior)...
+    assert row["table_name"] == "dbo"
+    assert row["TABLE_QUALIFIER"] == "dbo"
+    # ...but the mapping view does NOT, so its keys agree with membership/lookup.
+    assert "table_name" not in mapping
+    assert "TABLE_QUALIFIER" not in mapping
+    with pytest.raises(KeyError):
+        mapping["table_name"]
+    assert mapping.get("TABLE_QUALIFIER") is None
+    assert mapping.get("table_name", "fallback") == "fallback"

tests/test_004_cursor.py

@@ -3929,6 +3929,49 @@ def test_row_mapping_lowercase_setting(db_connection):
             cursor.close()
 
 
+def test_row_mapping_lookup_agrees_with_iteration_lowercase(db_connection):
+    """_mapping lookup/membership must agree with iteration (Mapping contract).
+
+    With lowercase=True the canonical keys are lowercased. Row itself still
+    resolves the original mixed-case name (case-insensitive), but the mapping
+    view must NOT: its keys, ``in`` and ``[]`` are restricted to the iterated
+    canonical names, so it can never accept a name it does not yield.
+    """
+    original = mssql_python.lowercase
+    cursor = None
+    try:
+        mssql_python.lowercase = True
+        cursor = db_connection.cursor()
+        cursor.execute("SELECT 1 AS MixedCase")
+        row = cursor.fetchone()
+        mapping = row._mapping
+
+        # Row-level access is unchanged: case-insensitive name still resolves.
+        assert row["MixedCase"] == 1
+        assert row.MixedCase == 1
+
+        # The mapping view yields only the canonical lowercased key.
+        assert list(mapping) == ["mixedcase"]
+        assert mapping["mixedcase"] == 1
+
+        # The non-canonical mixed-case name is NOT a member and NOT subscriptable,
+        # so the key set agrees with membership and lookup.
+        assert "MixedCase" not in mapping
+        with pytest.raises(KeyError):
+            mapping["MixedCase"]
+        assert mapping.get("MixedCase") is None
+        assert mapping.get("MixedCase", "fallback") == "fallback"
+
+        # Every iterated key is a member and is subscriptable (contract holds).
+        for name in mapping:
+            assert name in mapping
+            assert mapping[name] == mapping.get(name)
+    finally:
+        mssql_python.lowercase = original
+        if cursor is not None:
+            cursor.close()
+
+
 def test_row_comparison_with_list(cursor, db_connection):
     """Test comparing Row objects with lists (__eq__ method)"""
     try: