feat(python): Allow bare .row() on a single-row DataFrame, equivalent to .item() on a single-element DataFrame

Author: alexander-beedie

py-polars/src/polars/dataframe/frame.py

@@ -1683,9 +1683,8 @@ def item(self, row: int | None = None, column: int | str | None = None) -> Any:
         if row is None and column is None:
             if self.shape != (1, 1):
                 msg = (
-                    "can only call `.item()` if the dataframe is of shape (1, 1),"
-                    " or if explicit row/col values are provided;"
-                    f" frame has shape {self.shape!r}"
+                    'can only call `.item()` without "row" or "column" values if the '
+                    f"DataFrame has a single element; shape={self.shape!r}"
                 )
                 raise ValueError(msg)
             return self._df.to_series(0).get_index(0)
@@ -11450,7 +11449,16 @@ def row(
         >>> df.row(by_predicate=(pl.col("ham") == "b"))
         (2, 7, 'b')
         """
-        if index is not None and by_predicate is not None:
+        if index is None and by_predicate is None:
+            if self.height == 1:
+                index = 0
+            else:
+                msg = (
+                    'can only call `.row()` without "index" or "by_predicate" values '
+                    f"if the DataFrame has a single row; shape={self.shape!r}"
+                )
+                raise ValueError(msg)
+        elif index is not None and by_predicate is not None:
             msg = "cannot set both 'index' and 'by_predicate'; mutually exclusive"
             raise ValueError(msg)
         elif isinstance(index, pl.Expr):

py-polars/tests/unit/dataframe/test_item.py

@@ -12,19 +12,19 @@ def test_df_item() -> None:
 
 def test_df_item_empty() -> None:
     df = pl.DataFrame()
-    with pytest.raises(ValueError, match=r".* frame has shape \(0, 0\)"):
+    with pytest.raises(ValueError, match=r".* shape=\(0, 0\)"):
         df.item()
 
 
 def test_df_item_incorrect_shape_rows() -> None:
     df = pl.DataFrame({"a": [1, 2]})
-    with pytest.raises(ValueError, match=r".* frame has shape \(2, 1\)"):
+    with pytest.raises(ValueError, match=r".* shape=\(2, 1\)"):
         df.item()
 
 
 def test_df_item_incorrect_shape_columns() -> None:
     df = pl.DataFrame({"a": [1], "b": [2]})
-    with pytest.raises(ValueError, match=r".* frame has shape \(1, 2\)"):
+    with pytest.raises(ValueError, match=r".* shape=\(1, 2\)"):
         df.item()
 
 

py-polars/tests/unit/test_rows.py

@@ -255,3 +255,18 @@ def test_physical_row_encoding() -> None:
             "files": ["AGG_202307.xlsx"],
         }
     ]
+
+
+def test_row_with_no_arguments() -> None:
+    # confirm that calling bare `.row()` on a single-row frame behaves
+    # consistently with calling `item()` on a single element frame
+    df = pl.DataFrame({"tag": ["xx"], "n": [1]})
+    assert df.row() == ("xx", 1)
+
+    # however, cannot call bare '.row()' if the frame does NOT have a single row
+    df = pl.DataFrame({"tag": ["xx", "yy"], "n": [1, 2]})
+    with pytest.raises(
+        ValueError,
+        match=r'can only call `\.row\(\)` without "index" or "by_predicate"',
+    ):
+        df.row()