From cafa8fd58b329dc2bd85c14d7619181fa88c8d23 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Tue, 22 Aug 2023 09:29:57 +0100
Subject: [PATCH] rename insert, remove label argument (#230)

---
 .../dataframe_api/dataframe_object.py             | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/spec/API_specification/dataframe_api/dataframe_object.py b/spec/API_specification/dataframe_api/dataframe_object.py
index 8a25a8c1..b0f70b43 100644
--- a/spec/API_specification/dataframe_api/dataframe_object.py
+++ b/spec/API_specification/dataframe_api/dataframe_object.py
@@ -180,17 +180,24 @@ def get_rows_by_mask(self, mask: Column[Bool]) -> DataFrame:
         """
         ...
 
-    def insert(self, loc: int, label: str, value: Column[Any]) -> DataFrame:
+    def insert_column(self, loc: int, column: Column[Any]) -> DataFrame:
         """
         Insert column into DataFrame at specified location.
 
+        The column's name will be used as the label in the resulting dataframe.
+        To insert the column with a different name, combine with `Column.rename`,
+        e.g.:
+
+        .. code-block :: python
+
+            new_column = df.get_column_by_name('a') + 1
+            df = df.insert(0, new_column.rename('a_plus_1'))
+
         Parameters
         ----------
         loc : int
             Insertion index. Must verify 0 <= loc <= len(columns).
-        label : str
-            Label of the inserted column.
-        value : Column
+        column : Column
         """
         ...