This is an automated email from the ASF dual-hosted git repository.
alenka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 8995d61c07 GH-48668: [Python][Docs] Add python examples for compute
functions `min/max/min_max` (#48648)
8995d61c07 is described below
commit 8995d61c0792627a07578f35e5db783eddbdc196
Author: Ruifeng Zheng <[email protected]>
AuthorDate: Sun Jan 11 23:41:15 2026 -0800
GH-48668: [Python][Docs] Add python examples for compute functions
`min/max/min_max` (#48648)
### Rationale for this change
To improve python documentation
### What changes are included in this PR?
Add python examples for compute functions `min/max/min_max`
### Are these changes tested?
Yes, doc-test
### Are there any user-facing changes?
Doc-only changes
* GitHub Issue: #48668
Lead-authored-by: Ruifeng Zheng <[email protected]>
Co-authored-by: Ruifeng Zheng <[email protected]>
Co-authored-by: Alenka Frim <[email protected]>
Signed-off-by: AlenkaF <[email protected]>
---
python/pyarrow/_compute_docstrings.py | 102 ++++++++++++++++++++++++++++++++++
python/pyarrow/tests/test_compute.py | 32 +++++++++++
2 files changed, 134 insertions(+)
diff --git a/python/pyarrow/_compute_docstrings.py
b/python/pyarrow/_compute_docstrings.py
index 150dbdb117..4b690dd1c5 100644
--- a/python/pyarrow/_compute_docstrings.py
+++ b/python/pyarrow/_compute_docstrings.py
@@ -54,3 +54,105 @@ function_doc_additions["mode"] = """
>>> modes[1]
<pyarrow.StructScalar: [('mode', 1), ('count', 2)]>
"""
+
+function_doc_additions["min"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.min(arr1)
+ <pyarrow.Int64Scalar: 1>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([1.0, None, 2.0, 3.0])
+ >>> pc.min(arr2)
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.min(arr2, skip_nulls=False)
+ <pyarrow.DoubleScalar: None>
+
+ Using ``ScalarAggregateOptions`` to control minimum number of non-null
values.
+
+ >>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
+ >>> pc.min(arr3)
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.DoubleScalar: None>
+
+ This function also works with string values.
+
+ >>> arr4 = pa.array(["z", None, "y", "x"])
+ >>> pc.min(arr4)
+ <pyarrow.StringScalar: 'x'>
+ """
+
+function_doc_additions["max"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.max(arr1)
+ <pyarrow.Int64Scalar: 3>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([1.0, None, 2.0, 3.0])
+ >>> pc.max(arr2)
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.max(arr2, skip_nulls=False)
+ <pyarrow.DoubleScalar: None>
+
+ Using ``ScalarAggregateOptions`` to control minimum number of non-null
values.
+
+ >>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
+ >>> pc.max(arr3)
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.DoubleScalar: None>
+
+ This function also works with string values.
+
+ >>> arr4 = pa.array(["z", None, "y", "x"])
+ >>> pc.max(arr4)
+ <pyarrow.StringScalar: 'z'>
+ """
+
+function_doc_additions["min_max"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.min_max(arr1)
+ <pyarrow.StructScalar: [('min', 1), ('max', 3)]>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([1.0, None, 2.0, 3.0])
+ >>> pc.min_max(arr2)
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr2, skip_nulls=False)
+ <pyarrow.StructScalar: [('min', None), ('max', None)]>
+
+ Using ``ScalarAggregateOptions`` to control minimum number of non-null
values.
+
+ >>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
+ >>> pc.min_max(arr3)
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.StructScalar: [('min', None), ('max', None)]>
+
+ This function also works with string values.
+
+ >>> arr4 = pa.array(["z", None, "y", "x"])
+ >>> pc.min_max(arr4)
+ <pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
+ """
diff --git a/python/pyarrow/tests/test_compute.py
b/python/pyarrow/tests/test_compute.py
index c6b17e4791..d8a1c4d093 100644
--- a/python/pyarrow/tests/test_compute.py
+++ b/python/pyarrow/tests/test_compute.py
@@ -883,6 +883,38 @@ def test_generated_docstrings():
Alternative way of passing options.
memory_pool : pyarrow.MemoryPool, optional
If not passed, will allocate memory from the default memory pool.
+
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.min_max(arr1)
+ <pyarrow.StructScalar: [('min', 1), ('max', 3)]>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([1.0, None, 2.0, 3.0])
+ >>> pc.min_max(arr2)
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr2, skip_nulls=False)
+ <pyarrow.StructScalar: [('min', None), ('max', None)]>
+
+ Using ``ScalarAggregateOptions`` to control minimum number of non-null
values.
+
+ >>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
+ >>> pc.min_max(arr3)
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
+ >>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.StructScalar: [('min', None), ('max', None)]>
+
+ This function also works with string values.
+
+ >>> arr4 = pa.array(["z", None, "y", "x"])
+ >>> pc.min_max(arr4)
+ <pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
""")
# Without options
assert pc.add.__doc__ == textwrap.dedent("""\
