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 bf8d1754c9 GH-49269: [Python][Docs] Add code examples for compute
function first/last/first_last (#49270)
bf8d1754c9 is described below
commit bf8d1754c9bdfd0664c8a5362f2ee22d02c93e73
Author: Ruifeng Zheng <[email protected]>
AuthorDate: Thu Mar 5 04:12:49 2026 -0800
GH-49269: [Python][Docs] Add code examples for compute function
first/last/first_last (#49270)
### Rationale for this change
To improve python documentation
### What changes are included in this PR?
Add code examples for compute function first/last/first_last
### Are these changes tested?
Yes, doc-test
### Are there any user-facing changes?
Yes, doc-only changes
* GitHub Issue: #49269
Authored-by: Ruifeng Zheng <[email protected]>
Signed-off-by: AlenkaF <[email protected]>
---
python/pyarrow/_compute_docstrings.py | 99 +++++++++++++++++++++++++++++++++++
1 file changed, 99 insertions(+)
diff --git a/python/pyarrow/_compute_docstrings.py
b/python/pyarrow/_compute_docstrings.py
index 4b690dd1c5..079f00db7d 100644
--- a/python/pyarrow/_compute_docstrings.py
+++ b/python/pyarrow/_compute_docstrings.py
@@ -156,3 +156,102 @@ function_doc_additions["min_max"] = """
>>> pc.min_max(arr4)
<pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
"""
+
+function_doc_additions["first"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.first(arr1)
+ <pyarrow.Int64Scalar: 1>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([None, 1.0, 2.0, 3.0])
+ >>> pc.first(arr2)
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.first(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.first(arr3)
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.first(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.DoubleScalar: 1.0>
+ >>> pc.first(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.DoubleScalar: None>
+
+ See Also
+ --------
+ pyarrow.compute.first_last
+ pyarrow.compute.last
+ """
+
+function_doc_additions["last"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.last(arr1)
+ <pyarrow.Int64Scalar: 2>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([1.0, 2.0, 3.0, None])
+ >>> pc.last(arr2)
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.last(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.last(arr3)
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.last(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.DoubleScalar: 3.0>
+ >>> pc.last(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.DoubleScalar: None>
+
+ See Also
+ --------
+ pyarrow.compute.first
+ pyarrow.compute.first_last
+ """
+
+function_doc_additions["first_last"] = """
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> import pyarrow.compute as pc
+ >>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
+ >>> pc.first_last(arr1)
+ <pyarrow.StructScalar: [('first', 1), ('last', 2)]>
+
+ Using ``skip_nulls`` to handle null values.
+
+ >>> arr2 = pa.array([None, 2.0, 3.0, None])
+ >>> pc.first_last(arr2)
+ <pyarrow.StructScalar: [('first', 2.0), ('last', 3.0)]>
+ >>> pc.first_last(arr2, skip_nulls=False)
+ <pyarrow.StructScalar: [('first', None), ('last', None)]>
+
+ Using ``ScalarAggregateOptions`` to control minimum number of non-null
values.
+
+ >>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
+ >>> pc.first_last(arr3)
+ <pyarrow.StructScalar: [('first', 1.0), ('last', 3.0)]>
+ >>> pc.first_last(arr3, options=pc.ScalarAggregateOptions(min_count=3))
+ <pyarrow.StructScalar: [('first', 1.0), ('last', 3.0)]>
+ >>> pc.first_last(arr3, options=pc.ScalarAggregateOptions(min_count=4))
+ <pyarrow.StructScalar: [('first', None), ('last', None)]>
+
+ See Also
+ --------
+ pyarrow.compute.first
+ pyarrow.compute.last
+ """
