FEAT: Add to_dict(), keys(), values(), items(), __contains__ to Row

mssql_python/row.py

@@ -16,14 +16,21 @@ class Row:
  A row of data from a cursor fetch operation. Provides both tuple-like indexing
  and attribute access to column values.
 
+ Row supports dict-like access via keys(), values(), items(), and to_dict().
+ However, iteration (for x in row) yields values, not keys — consistent with
+ pyodbc.Row and sqlite3.Row. Use row.keys() to iterate column names.
+
  Column attribute access behavior depends on the global 'lowercase' setting:
  - When enabled: Case-insensitive attribute access
  - When disabled (default): Case-sensitive attribute access matching original column names
 
  Example:
  row = cursor.fetchone()
- print(row[0]) # Access by index
- print(row.column_name) # Access by column name (case sensitivity varies)
+ print(row[0]) # Access by index
+ print(row.column_name) # Access by column name
+ print(row.to_dict()) # Convert to dict
+ for value in row: # Iterates values, not keys
+ print(value)
  """
 
  def __init__(
@@ -73,6 +80,7 @@ def __init__(
  # Lowercase map is pre-built once per result set in the cursor and shared
  # across all rows. None when lowercase is off (the default) — zero cost.
  self._column_map_lower = column_map_lower
+ self._column_names = None # Lazy-computed on first access via _get_column_names()
 
  def _stringify_uuids(self, indices):
  """
@@ -209,6 +217,41 @@ def __getattr__(self, name: str) -> Any:
 
  raise AttributeError(f"Row has no attribute '{name}'")
 
+ def _get_column_names(self) -> tuple:
+ """Lazy-compute and cache deduplicated column names on first access."""
+ if self._column_names is not None:
+ return self._column_names
+
+ if self._cursor and hasattr(self._cursor, "description") and self._cursor.description:
+ column_names = tuple(desc[0] for desc in self._cursor.description)
+ elif self._column_map:
+ idx_to_name: dict = {}
+ for name, idx in self._column_map.items():
+ if idx not in idx_to_name:
+ idx_to_name[idx] = name
+ column_names = tuple(idx_to_name[i] for i in sorted(idx_to_name))
+ else:
+ column_names = ()
+
+ self._column_names = column_names
+ return column_names
+
+ def keys(self) -> tuple:
+ """Return column names, like dict.keys()."""
+ return self._get_column_names()
+
+ def values(self) -> tuple:
+ """Return column values as a tuple, like dict.values()."""
+ return tuple(self._values)
+
+ def items(self) -> list:
+ """Return (column_name, value) pairs, like dict.items()."""
+ return list(zip(self._get_column_names(), self._values))
+
+ def to_dict(self) -> dict:
+ """Return the row as a plain dict mapping column names to values."""
+ return dict(zip(self._get_column_names(), self._values))
+
  def __eq__(self, other: Any) -> bool:
  """
  Support comparison with lists for test compatibility.

tests/test_001_globals.py

@@ -996,66 +996,3 @@ def test_stringify_uuids_with_tuple_values():
  assert row[2] == "hello"
  # Internal storage should now be a list (converted from tuple)
  assert isinstance(row._values, list)
-
-
-def test_row_string_key_indexing():
- """Test Row supports string-key indexing via __getitem__ (row['col'])."""
- from mssql_python.row import Row
-
- row = Row(
- [1, "foo", 3.14],
- {"ProductID": 0, "Name": 1, "Price": 2},
- cursor=None,
- )
-
- # String-key access
- assert row["ProductID"] == 1
- assert row["Name"] == "foo"
- assert row["Price"] == 3.14
-
- # Integer index access still works
- assert row[0] == 1
- assert row[1] == "foo"
- assert row[2] == 3.14
-
- # Slice access still works
- assert row[0:2] == [1, "foo"]
-
- # Missing key raises KeyError
- with pytest.raises(KeyError):
- row["nonexistent"]
-
- # Unsupported index types raise TypeError
- with pytest.raises(TypeError):
- row[3.5]
- with pytest.raises(TypeError):
- row[None]
-
-
-def test_row_string_key_case_insensitive_with_lowercase():
- """Test Row string-key indexing is case-insensitive when column_map_lower is provided."""
- from mssql_python.row import Row
-
- column_map = {"productid": 0, "name": 1}
- column_map_lower = {k.lower(): v for k, v in column_map.items()}
-
- row = Row(
- [1, "bar"],
- column_map,
- cursor=None,
- column_map_lower=column_map_lower,
- )
-
- # Exact match via __getitem__
- assert row["productid"] == 1
- # Exact match via __getattr__
- assert row.productid == 1
- # Case-insensitive match via __getitem__
- assert row["ProductID"] == 1
- assert row["NAME"] == "bar"
- # Case-insensitive match via __getattr__ (attribute access)
- assert row.ProductID == 1
- assert row.NAME == "bar"
- # Non-existent attribute raises AttributeError
- with pytest.raises(AttributeError):
- row.nonexistent

tests/test_004_cursor.py

@@ -3381,6 +3381,226 @@ def test_row_string_key_indexing(cursor, db_connection):
  pass
 
 
+def test_row_to_dict(cursor, db_connection):
+ """Test Row.to_dict() returns a plain dict from a real cursor row."""
+ try:
+ cursor.execute(
+ "CREATE TABLE #pytest_row_todict (id INT PRIMARY KEY, name VARCHAR(50), price FLOAT)"
+ )
+ db_connection.commit()
+
+ cursor.execute("INSERT INTO #pytest_row_todict VALUES (1, 'Widget', 9.99)")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_todict")
+ row = cursor.fetchone()
+
+ d = row.to_dict()
+ assert isinstance(d, dict)
+ assert d["id"] == 1
+ assert d["name"] == "Widget"
+ assert d["price"] == 9.99
+ assert len(d) == len(row)
+
+ except Exception as e:
+ pytest.fail(f"Row to_dict test failed: {e}")
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_todict")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
+def test_row_keys_values_items(cursor, db_connection):
+ """Test Row.keys(), values(), items() from a real cursor row."""
+ try:
+ cursor.execute("CREATE TABLE #pytest_row_kvi (id INT PRIMARY KEY, name VARCHAR(50))")
+ db_connection.commit()
+
+ cursor.execute("INSERT INTO #pytest_row_kvi VALUES (42, 'Alice')")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_kvi")
+ row = cursor.fetchone()
+
+ # keys() returns column names matching description
+ keys = list(row.keys())
+ assert len(keys) == 2
+ assert keys == [desc[0] for desc in cursor.description]
+
+ # values() matches positional access
+ vals = list(row.values())
+ assert vals == [row[0], row[1]]
+
+ # items() returns (name, value) pairs
+ items = row.items()
+ assert len(items) == 2
+ assert items[0] == (keys[0], row[0])
+ assert items[1] == (keys[1], row[1])
+
+ # items() is reusable (not one-shot iterator)
+ assert list(items) == list(items)
+
+ # len consistency
+ assert len(keys) == len(row)
+ assert len(vals) == len(row)
+ assert len(items) == len(row)
+
+ except Exception as e:
+ pytest.fail(f"Row keys/values/items test failed: {e}")
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_kvi")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
+def test_row_dict_no_duplicate_keys(cursor, db_connection):
+ """Test that dict-like methods don't produce duplicate keys from cursor rows.
+
+ The cursor may inject lowercase aliases into _column_map, but keys(),
+ items(), and to_dict() must return exactly N entries with original casing.
+ """
+ try:
+ cursor.execute("CREATE TABLE #pytest_row_nodup (ProductID INT, MixedCase VARCHAR(20))")
+ db_connection.commit()
+
+ cursor.execute("INSERT INTO #pytest_row_nodup VALUES (1, 'test')")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_nodup")
+ row = cursor.fetchone()
+
+ keys = list(row.keys())
+ items = row.items()
+ d = row.to_dict()
+
+ # Exactly 2 columns, no duplicates
+ assert len(keys) == 2
+ assert len(items) == 2
+ assert len(d) == 2
+ assert len(keys) == len(row)
+
+ except Exception as e:
+ pytest.fail(f"Row dict no-duplicate-keys test failed: {e}")
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_nodup")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
+def test_row_getitem_type_guard(cursor, db_connection):
+ """Test Row.__getitem__ raises TypeError for unsupported index types."""
+ try:
+ cursor.execute("CREATE TABLE #pytest_row_typeguard (id INT)")
+ db_connection.commit()
+ cursor.execute("INSERT INTO #pytest_row_typeguard VALUES (1)")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_typeguard")
+ row = cursor.fetchone()
+
+ with pytest.raises(TypeError):
+ row[3.5]
+ with pytest.raises(TypeError):
+ row[None]
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_typeguard")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
+def test_row_case_sensitive_access(cursor, db_connection):
+ """Test exact-case access via cursor rows.
+
+ Normal SELECT uses _cached_column_map (original casing only, no lowercase
+ aliases). Case-insensitive access only works when the global lowercase
+ setting is enabled or when rows come from metadata methods.
+ """
+ try:
+ cursor.execute("CREATE TABLE #pytest_row_ci (ProductID INT, Name VARCHAR(50))")
+ db_connection.commit()
+ cursor.execute("INSERT INTO #pytest_row_ci VALUES (1, 'bar')")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_ci")
+ row = cursor.fetchone()
+
+ # Original casing works via all access methods
+ assert row["ProductID"] == 1
+ assert row.ProductID == 1
+
+ assert row["Name"] == "bar"
+ assert row.Name == "bar"
+
+ # Non-existent
+ with pytest.raises(KeyError):
+ row["nonexistent"]
+ with pytest.raises(AttributeError):
+ row.nonexistent
+
+ except Exception as e:
+ pytest.fail(f"Row case-insensitive access test failed: {e}")
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_ci")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
+def test_row_none_column_map():
+ """Test Row edge case with column_map=None (covers _column_names=() branch)."""
+ from mssql_python.row import Row
+
+ row = Row([], None, cursor=None)
+ assert list(row.keys()) == []
+ assert list(row.values()) == []
+ assert list(row.items()) == []
+ assert row.to_dict() == {}
+
+
+def test_row_dict_dedup_fallback():
+ """Test dict-like methods deduplicate _column_map when cursor is None."""
+ from mssql_python.row import Row
+
+ column_map = {"ProductID": 0, "Name": 1}
+ row = Row([1, "foo"], column_map, cursor=None)
+
+ assert list(row.keys()) == ["ProductID", "Name"]
+ assert row.to_dict() == {"ProductID": 1, "Name": "foo"}
+
+
+def test_row_items_is_reusable(cursor, db_connection):
+ """Test items() returns a reusable list, not a one-shot iterator."""
+ try:
+ cursor.execute("CREATE TABLE #pytest_row_reuse (id INT, name VARCHAR(50))")
+ db_connection.commit()
+ cursor.execute("INSERT INTO #pytest_row_reuse VALUES (1, 'foo')")
+ db_connection.commit()
+
+ cursor.execute("SELECT * FROM #pytest_row_reuse")
+ row = cursor.fetchone()
+
+ items = row.items()
+ first = list(items)
+ second = list(items)
+ assert first == second
+ assert len(first) > 0
+ finally:
+ try:
+ cursor.execute("DROP TABLE IF EXISTS #pytest_row_reuse")
+ db_connection.commit()
+ except Exception:
+ pass
+
+
 def test_row_comparison_with_list(cursor, db_connection):
  """Test comparing Row objects with lists (__eq__ method)"""
  try: