MINOR: [Doc][Python] Clarify behavior of pyarrow.compute.fill_value (#…

…35813) Discussed in #35624, particularly at #35624 (comment). Doesn't close that issue, but it came up in discussion. Lead-authored-by: Spencer Nelson <[email protected]> Co-authored-by: Antoine Pitrou <[email protected]> Signed-off-by: Antoine Pitrou <[email protected]>
apache · May 30, 2023 · e628ca5 · e628ca5
1 parent 2695293
commit e628ca5
Showing 1 changed file with 21 additions and 5 deletions.
diff --git a/python/pyarrow/compute.py b/python/pyarrow/compute.py
@@ -483,10 +483,16 @@ def take(data, indices, *, boundscheck=True, memory_pool=None):
 
 
 def fill_null(values, fill_value):
-    """
-    Replace each null element in values with fill_value. The fill_value must be
-    the same type as values or able to be implicitly casted to the array's
-    type.
+    """Replace each null element in values with a corresponding
+    element from fill_value.
+
+    If fill_value is scalar-like, then every null element in values
+    will be replaced with fill_value. If fill_value is array-like,
+    then the i-th element in values will be replaced with the i-th
+    element in fill_value.
+
+    The fill_value's type must be the same as that of values, or it
+    must be able to be implicitly casted to the array's type.
 
     This is an alias for :func:`coalesce`.
 
@@ -496,7 +502,7 @@ def fill_null(values, fill_value):
         Each null element is replaced with the corresponding value
         from fill_value.
     fill_value : Array, ChunkedArray, or Scalar-like object
-        If not same type as data will attempt to cast.
+        If not same type as values, will attempt to cast.
 
     Returns
     -------
@@ -516,6 +522,16 @@ def fill_null(values, fill_value):
       5,
       3
     ]
+    >>> arr = pa.array([1, 2, None, 4, None])
+    >>> arr.fill_null(pa.array([10, 20, 30, 40, 50]))
+    <pyarrow.lib.Int64Array object at ...>
+    [
+      1,
+      2,
+      30,
+      4,
+      50
+    ]
     """
     if not isinstance(fill_value, (pa.Array, pa.ChunkedArray, pa.Scalar)):
         fill_value = pa.scalar(fill_value, type=values.type)