note that insertion order is not guaranteed and may vary

Author: MarcoGorelli

spec/API_specification/dataframe_api/dataframe_object.py

@@ -203,22 +203,23 @@ def insert_columns(self, columns: Column[Any] | Sequence[Column[Any]]) -> DataFr
             df = df.insert_column(new_column.rename('a_plus_1'))
             df = df.get_columns_by_name(new_column_names)
 
-        If inserting multiple columns, they must be indepedent.
-        For example, 
+        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 allowed, as `new_column_2` depends on `new_column_1`.
+        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
         ----------
         columns : Column | Sequence[Column]
-            Column(s) to insert. Must be independent of each other, so that insertion
-            can happen in parallel in some implementations.
+            Column(s) to insert. Insertion order is not guaranteed.
         """
         ...