docs(python): note that only one name operation per expression (#14075

)
pola-rs · Jan 30, 2024 · ab8a00b · ab8a00b
1 parent 24a21c3
commit ab8a00b
Showing 1 changed file with 25 additions and 5 deletions.
diff --git a/py-polars/polars/expr/name.py b/py-polars/polars/expr/name.py
@@ -21,8 +21,11 @@ def keep(self) -> Expr:
 
         Notes
         -----
+        This will undo any previous renaming operations on the expression.
+
         Due to implementation constraints, this method can only be called as the last
-        expression in a chain.
+        expression in a chain. Only one name operation per expression will work.
+        Consider using `.name.map` for advanced renaming.
 
         See Also
         --------
@@ -69,6 +72,14 @@ def map(self, function: Callable[[str], str]) -> Expr:
         """
         Rename the output of an expression by mapping a function over the root name.
 
+        Notes
+        -----
+        This will undo any previous renaming operations on the expression.
+
+        Due to implementation constraints, this method can only be called as the last
+        expression in a chain. Only one name operation per expression will work.
+
+
         Parameters
         ----------
         function
@@ -115,12 +126,14 @@ def prefix(self, prefix: str) -> Expr:
         prefix
             Prefix to add to the root column name.
 
+
         Notes
         -----
         This will undo any previous renaming operations on the expression.
 
         Due to implementation constraints, this method can only be called as the last
-        expression in a chain.
+        expression in a chain. Only one name operation per expression will work.
+        Consider using `.name.map` for advanced renaming.
 
         See Also
         --------
@@ -162,7 +175,8 @@ def suffix(self, suffix: str) -> Expr:
         This will undo any previous renaming operations on the expression.
 
         Due to implementation constraints, this method can only be called as the last
-        expression in a chain.
+        expression in a chain. Only one name operation per expression will work.
+        Consider using `.name.map` for advanced renaming.
 
         See Also
         --------
@@ -196,8 +210,11 @@ def to_lowercase(self) -> Expr:
 
         Notes
         -----
+        This will undo any previous renaming operations on the expression.
+
         Due to implementation constraints, this method can only be called as the last
-        expression in a chain.
+        expression in a chain. Only one name operation per expression will work.
+        Consider using `.name.map` for advanced renaming.
 
         See Also
         --------
@@ -233,8 +250,11 @@ def to_uppercase(self) -> Expr:
 
         Notes
         -----
+        This will undo any previous renaming operations on the expression.
+
         Due to implementation constraints, this method can only be called as the last
-        expression in a chain.
+        expression in a chain. Only one name operation per expression will work.
+        Consider using `.name.map` for advanced renaming.
 
         See Also
         --------