You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by "HyukjinKwon (via GitHub)" <gi...@apache.org> on 2024/03/28 05:55:29 UTC
[PR] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
HyukjinKwon opened a new pull request, #45745:
URL: https://github.com/apache/spark/pull/45745
### What changes were proposed in this pull request?
This PR refines docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` with more descriptive examples.
### Why are the changes needed?
For better API reference documentation.
### Does this PR introduce _any_ user-facing change?
Yes, it fixes user-facing documentation.
### How was this patch tested?
Manually tested. GitHub Actions should verify them.
### Was this patch authored or co-authored using generative AI tooling?
No
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng closed pull request #45745: [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean`
URL: https://github.com/apache/spark/pull/45745
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "MaxGekk (via GitHub)" <gi...@apache.org>.
MaxGekk commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542464507
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,55 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 3: Calculating the average age with None
Review Comment:
What's the difference between this and the above example?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "HyukjinKwon (via GitHub)" <gi...@apache.org>.
HyukjinKwon commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542517014
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,55 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 3: Calculating the average age with None
Review Comment:
```suggestion
Example 2: Calculating the average age with None
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "HyukjinKwon (via GitHub)" <gi...@apache.org>.
HyukjinKwon commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542518086
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,44 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 4: Overflow results in NULL when ANSI mode is on
Review Comment:
```suggestion
Example 3: Overflow results in NULL when ANSI mode is on
```
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,55 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 3: Calculating the average age with None
Review Comment:
thanks for pointing it out
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "HyukjinKwon (via GitHub)" <gi...@apache.org>.
HyukjinKwon commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542518086
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,44 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 4: Overflow results in NULL when ANSI mode is on
Review Comment:
```suggestion
Example 3: Overflow results in NULL when ANSI mode is on
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "HyukjinKwon (via GitHub)" <gi...@apache.org>.
HyukjinKwon commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542517267
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -720,13 +760,54 @@ def try_sum(col: "ColumnOrName") -> Column:
Examples
--------
- >>> import pyspark.sql.functions as sf
- >>> spark.range(10).select(sf.try_sum("id")).show()
+ Example 1: Calculating the sum of values in a column
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.range(10)
+ >>> df.select(sf.try_sum(df["id"])).show()
+-----------+
|try_sum(id)|
+-----------+
| 45|
+-----------+
+
+ Example 2: Using a plus expression together to calculate the sum
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, 2), (3, 4)], ["A", "B"])
+ >>> df.select(sf.try_sum(sf.col("A") + sf.col("B"))).show()
+ +----------------+
+ |try_sum((A + B))|
+ +----------------+
+ | 10|
+ +----------------+
+
+ Example 3: Calculating the summation of ages with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_sum("age")).show()
+ +------------+
+ |try_sum(age)|
+ +------------+
+ | 6|
+ +------------+
+
+ Example 4: Overflow results in NULL when ANSI mode is on
Review Comment:
```suggestion
Example 3: Overflow results in NULL when ANSI mode is on
```
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -720,13 +760,54 @@ def try_sum(col: "ColumnOrName") -> Column:
Examples
--------
- >>> import pyspark.sql.functions as sf
- >>> spark.range(10).select(sf.try_sum("id")).show()
+ Example 1: Calculating the sum of values in a column
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.range(10)
+ >>> df.select(sf.try_sum(df["id"])).show()
+-----------+
|try_sum(id)|
+-----------+
| 45|
+-----------+
+
+ Example 2: Using a plus expression together to calculate the sum
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, 2), (3, 4)], ["A", "B"])
+ >>> df.select(sf.try_sum(sf.col("A") + sf.col("B"))).show()
+ +----------------+
+ |try_sum((A + B))|
+ +----------------+
+ | 10|
+ +----------------+
+
+ Example 3: Calculating the summation of ages with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_sum("age")).show()
+ +------------+
+ |try_sum(age)|
+ +------------+
+ | 6|
+ +------------+
+
+ Example 4: Overflow results in NULL when ANSI mode is on
Review Comment:
```suggestion
Example 3: Overflow results in NULL when ANSI mode is on
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "HyukjinKwon (via GitHub)" <gi...@apache.org>.
HyukjinKwon commented on code in PR #45745:
URL: https://github.com/apache/spark/pull/45745#discussion_r1542517014
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -528,15 +528,55 @@ def try_avg(col: "ColumnOrName") -> Column:
Examples
--------
+ Example 1: Calculating the average age
+
>>> import pyspark.sql.functions as sf
- >>> spark.createDataFrame(
- ... [(1982, 15), (1990, 2)], ["birth", "age"]
- ... ).select(sf.try_avg("age")).show()
+ >>> df = spark.createDataFrame([(1982, 15), (1990, 2)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+------------+
|try_avg(age)|
+------------+
| 8.5|
+------------+
+
+ Example 2: Calculating the average age with None
+
+ >>> import pyspark.sql.functions as sf
+ >>> df = spark.createDataFrame([(1982, None), (1990, 2), (2000, 4)], ["birth", "age"])
+ >>> df.select(sf.try_avg("age")).show()
+ +------------+
+ |try_avg(age)|
+ +------------+
+ | 3.0|
+ +------------+
+
+ Example 3: Calculating the average age with None
Review Comment:
```suggestion
Example 2: Calculating the average age with None
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-47621][PYTHON][DOCS] Refine docstring of `try_sum`, `try_avg`, `avg`, `sum`, `mean` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on PR #45745:
URL: https://github.com/apache/spark/pull/45745#issuecomment-2025064658
merged to master
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org