From dcd9772a4201a238d4bb8c2a316f2861833be405 Mon Sep 17 00:00:00 2001
From: Jim Crist-Harif <jcristharif@gmail.com>
Date: Tue, 29 Aug 2023 14:02:12 -0500
Subject: [PATCH] depr(api): deprecate `Table.relabel` in favor of
 `Table.rename`

---
 ibis/expr/types/relations.py  |  7 +++++++
 ibis/tests/expr/test_table.py | 14 +++++++++-----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/ibis/expr/types/relations.py b/ibis/expr/types/relations.py
index d9e620f8aa44..d5c03e651f24 100644
--- a/ibis/expr/types/relations.py
+++ b/ibis/expr/types/relations.py
@@ -1722,6 +1722,13 @@ def select(
 
     projection = select
 
+    @util.deprecated(
+        as_of="7.0",
+        instead=(
+            "use `Table.rename` instead (if passing a mapping, note the meaning "
+            "of keys and values are swapped in Table.rename)."
+        ),
+    )
     def relabel(
         self,
         substitutions: Mapping[str, str]
diff --git a/ibis/tests/expr/test_table.py b/ibis/tests/expr/test_table.py
index f459eeac8077..e1f6f8648952 100644
--- a/ibis/tests/expr/test_table.py
+++ b/ibis/tests/expr/test_table.py
@@ -378,22 +378,26 @@ def test_relabel():
     table = api.table({"x": "int32", "y": "string", "z": "double"})
 
     # Using a mapping
-    res = table.relabel({"x": "x_1", "y": "y_1"}).schema()
+    with pytest.warns(FutureWarning, match="Table.rename"):
+        res = table.relabel({"x": "x_1", "y": "y_1"}).schema()
     sol = sch.schema({"x_1": "int32", "y_1": "string", "z": "double"})
     assert_equal(res, sol)
 
     # Using a function
-    res = table.relabel(lambda x: None if x == "z" else f"{x}_1").schema()
+    with pytest.warns(FutureWarning, match="Table.rename"):
+        res = table.relabel(lambda x: None if x == "z" else f"{x}_1").schema()
     assert_equal(res, sol)
 
     # Using a format string
-    res = table.relabel("_{name}_")
-    sol = table.relabel({"x": "_x_", "y": "_y_", "z": "_z_"})
+    with pytest.warns(FutureWarning, match="Table.rename"):
+        res = table.relabel("_{name}_")
+        sol = table.relabel({"x": "_x_", "y": "_y_", "z": "_z_"})
     assert_equal(res, sol)
 
     # Mapping with unknown columns errors
     with pytest.raises(com.IbisTypeError, match="'missing' is not found in table"):
-        table.relabel({"missing": "oops"})
+        with pytest.warns(FutureWarning, match="Table.rename"):
+            table.relabel({"missing": "oops"})
 
 
 def test_rename():