DOC: Fixes DataFrame.replace documentation (#55762)

* fix replace docs * fix replace docs * move description to examples * fix spacing * fix dicts * fix line size * fix whitespace * remove trailling whitespaces * fix df * fix df * Update pandas/core/shared_docs.py Co-authored-by: Matthew Roeschke <[email protected]> * Update pandas/core/shared_docs.py Co-authored-by: Matthew Roeschke <[email protected]> --------- Co-authored-by: Matthew Roeschke <[email protected]>
pandas-dev · Nov 3, 2023 · dd7441b · dd7441b
1 parent 2c1d4bb
commit dd7441b
Showing 1 changed file with 27 additions and 2 deletions.
diff --git a/pandas/core/shared_docs.py b/pandas/core/shared_docs.py
@@ -570,8 +570,7 @@
         .. deprecated:: 2.1.0
     regex : bool or same types as `to_replace`, default False
         Whether to interpret `to_replace` and/or `value` as regular
-        expressions. If this is ``True`` then `to_replace` *must* be a
-        string. Alternatively, this could be a regular expression or a
+        expressions. Alternatively, this could be a regular expression or a
         list, dict, or array of regular expressions in which case
         `to_replace` must be ``None``.
     method : {{'pad', 'ffill', 'bfill'}}
@@ -790,6 +789,32 @@
 
         .. versionchanged:: 1.4.0
             Previously the explicit ``None`` was silently ignored.
+
+    When ``regex=True``, ``value`` is not ``None`` and `to_replace` is a string,
+    the replacement will be applied in all columns of the DataFrame.
+
+    >>> df = pd.DataFrame({{'A': [0, 1, 2, 3, 4],
+    ...                    'B': ['a', 'b', 'c', 'd', 'e'],
+    ...                    'C': ['f', 'g', 'h', 'i', 'j']}})
+
+    >>> df.replace(to_replace='^[a-g]', value = 'e', regex=True)
+        A  B  C
+    0  0  e  e
+    1  1  e  e
+    2  2  e  h
+    3  3  e  i
+    4  4  e  j
+
+    If ``value`` is not ``None`` and `to_replace` is a dictionary, the dictionary
+    keys will be the DataFrame columns that the replacement will be applied.
+
+    >>> df.replace(to_replace={{'B': '^[a-c]', 'C': '^[h-j]'}}, value = 'e', regex=True)
+        A  B  C
+    0  0  e  f
+    1  1  e  g
+    2  2  e  e
+    3  3  d  e
+    4  4  e  e
 """
 
 _shared_docs[