Skip to content

Commit 8995d61

Browse files
zhengruifengAlenkaF
zhengruifeng
and
AlenkaF
authored
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 <ruifengz@apache.org> Co-authored-by: Ruifeng Zheng <ruifengz@foxmail.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Signed-off-by: AlenkaF <frim.alenka@gmail.com>
1 parent ec56b37 commit 8995d61

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

‎python/pyarrow/_compute_docstrings.py‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,105 @@
5454
>>> modes[1]
5555
<pyarrow.StructScalar: [('mode', 1), ('count', 2)]>
5656
"""
57+
58+
function_doc_additions["min"] = """
59+
Examples
60+
--------
61+
>>> import pyarrow as pa
62+
>>> import pyarrow.compute as pc
63+
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
64+
>>> pc.min(arr1)
65+
<pyarrow.Int64Scalar: 1>
66+
67+
Using ``skip_nulls`` to handle null values.
68+
69+
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
70+
>>> pc.min(arr2)
71+
<pyarrow.DoubleScalar: 1.0>
72+
>>> pc.min(arr2, skip_nulls=False)
73+
<pyarrow.DoubleScalar: None>
74+
75+
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
76+
77+
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
78+
>>> pc.min(arr3)
79+
<pyarrow.DoubleScalar: 1.0>
80+
>>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=3))
81+
<pyarrow.DoubleScalar: 1.0>
82+
>>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=4))
83+
<pyarrow.DoubleScalar: None>
84+
85+
This function also works with string values.
86+
87+
>>> arr4 = pa.array(["z", None, "y", "x"])
88+
>>> pc.min(arr4)
89+
<pyarrow.StringScalar: 'x'>
90+
"""
91+
92+
function_doc_additions["max"] = """
93+
Examples
94+
--------
95+
>>> import pyarrow as pa
96+
>>> import pyarrow.compute as pc
97+
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
98+
>>> pc.max(arr1)
99+
<pyarrow.Int64Scalar: 3>
100+
101+
Using ``skip_nulls`` to handle null values.
102+
103+
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
104+
>>> pc.max(arr2)
105+
<pyarrow.DoubleScalar: 3.0>
106+
>>> pc.max(arr2, skip_nulls=False)
107+
<pyarrow.DoubleScalar: None>
108+
109+
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
110+
111+
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
112+
>>> pc.max(arr3)
113+
<pyarrow.DoubleScalar: 3.0>
114+
>>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
115+
<pyarrow.DoubleScalar: 3.0>
116+
>>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
117+
<pyarrow.DoubleScalar: None>
118+
119+
This function also works with string values.
120+
121+
>>> arr4 = pa.array(["z", None, "y", "x"])
122+
>>> pc.max(arr4)
123+
<pyarrow.StringScalar: 'z'>
124+
"""
125+
126+
function_doc_additions["min_max"] = """
127+
Examples
128+
--------
129+
>>> import pyarrow as pa
130+
>>> import pyarrow.compute as pc
131+
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
132+
>>> pc.min_max(arr1)
133+
<pyarrow.StructScalar: [('min', 1), ('max', 3)]>
134+
135+
Using ``skip_nulls`` to handle null values.
136+
137+
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
138+
>>> pc.min_max(arr2)
139+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
140+
>>> pc.min_max(arr2, skip_nulls=False)
141+
<pyarrow.StructScalar: [('min', None), ('max', None)]>
142+
143+
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
144+
145+
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
146+
>>> pc.min_max(arr3)
147+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
148+
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
149+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
150+
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
151+
<pyarrow.StructScalar: [('min', None), ('max', None)]>
152+
153+
This function also works with string values.
154+
155+
>>> arr4 = pa.array(["z", None, "y", "x"])
156+
>>> pc.min_max(arr4)
157+
<pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
158+
"""

‎python/pyarrow/tests/test_compute.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -883,6 +883,38 @@ def test_generated_docstrings():
883883
Alternative way of passing options.
884884
memory_pool : pyarrow.MemoryPool, optional
885885
If not passed, will allocate memory from the default memory pool.
886+
887+
Examples
888+
--------
889+
>>> import pyarrow as pa
890+
>>> import pyarrow.compute as pc
891+
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
892+
>>> pc.min_max(arr1)
893+
<pyarrow.StructScalar: [('min', 1), ('max', 3)]>
894+
895+
Using ``skip_nulls`` to handle null values.
896+
897+
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
898+
>>> pc.min_max(arr2)
899+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
900+
>>> pc.min_max(arr2, skip_nulls=False)
901+
<pyarrow.StructScalar: [('min', None), ('max', None)]>
902+
903+
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
904+
905+
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
906+
>>> pc.min_max(arr3)
907+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
908+
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
909+
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
910+
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
911+
<pyarrow.StructScalar: [('min', None), ('max', None)]>
912+
913+
This function also works with string values.
914+
915+
>>> arr4 = pa.array(["z", None, "y", "x"])
916+
>>> pc.min_max(arr4)
917+
<pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
886918
""")
887919
# Without options
888920
assert pc.add.__doc__ == textwrap.dedent("""\

0 commit comments

Comments
 (0)