diff --git a/spec/API_specification/dataframe_api/dataframe_object.py b/spec/API_specification/dataframe_api/dataframe_object.py index 92c46410..664efa73 100644 --- a/spec/API_specification/dataframe_api/dataframe_object.py +++ b/spec/API_specification/dataframe_api/dataframe_object.py @@ -180,9 +180,9 @@ def get_rows_by_mask(self, mask: Column[Bool]) -> DataFrame: """ ... - def insert_column(self, column: Column[Any]) -> DataFrame: + def insert_columns(self, columns: Column[Any] | Sequence[Column[Any]]) -> DataFrame: """ - Insert column into DataFrame at rightmost location. + Insert column(s) into DataFrame at rightmost 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`, @@ -203,9 +203,24 @@ def insert_column(self, column: Column[Any]) -> DataFrame: df = df.insert_column(new_column.rename('a_plus_1')) df = df.get_columns_by_name(new_column_names) + If inserting multiple columns, then the order in which they are inserted + is not guaranteed and may vary across implementations. For example, the + following + + .. code-block:: python + + new_column_1 = df.get_column_by_name('a').rename('b') + new_column_2 = (new_column_1 + 2).rename('c') + df.insert_columns([new_column_1, new_column_2]) + + is not supported, as `new_column_2` is derived from `new_column_1`, which may + not be part of the dataframe if `new_column_2` is inserted first. + Parameters ---------- - column : Column + columns : Column | Sequence[Column] + Column(s) to insert. These will appear at the rightmost location, but + insertion order is not guaranteed. """ ...