[SPARK-58087][PYTHON][DOCS] Document accepted input and return types in the PySpark functions API#57185
Open
HyukjinKwon wants to merge 1 commit into
Open
[SPARK-58087][PYTHON][DOCS] Document accepted input and return types in the PySpark functions API#57185HyukjinKwon wants to merge 1 commit into
HyukjinKwon wants to merge 1 commit into
Conversation
…in the PySpark functions API ### What changes were proposed in this pull request? This documents, for every built-in function in the PySpark `functions` API (`builtin.py`), the accepted input type of each argument (`Parameters`) and the return type of each function (`Returns`), using the numeric umbrella where numeric subtypes cast in and `timestamp` for TIMESTAMP_NTZ in type phrases. Subtask of SPARK-57999, split out from apache#57079 for reviewability. This PR covers only the PySpark `builtin.py` surface. ### Why are the changes needed? The PySpark `functions` docstrings previously had no per-argument type information for most functions. This fills that gap. ### Does this PR introduce _any_ user-facing change? Yes, documentation only. No behavioral or API change. ### How was this patch tested? Python lint (flake8 + black) and the docstring doctests pass. Types were derived from and verified against the analyzer's behavior and each expression's `inputTypes` / `dataType`. Co-authored-by: Isaac
dongjoon-hyun
requested changes
Jul 10, 2026
Comment on lines
14483
to
+14486
| the column for computed results. | ||
|
|
||
| .. versionadded:: 1.5.0 | ||
| Returns a column that evaluates to a long. |
Member
There was a problem hiding this comment.
The return-type phrase was inserted under the .. versionadded:: 1.5.0 directive, so Sphinx renders it as "New in version 1.5.0: Returns a column that evaluates to a long." instead of as part of the Returns description. Shall we move like the following?
Suggested change
| the column for computed results. | |
| .. versionadded:: 1.5.0 | |
| Returns a column that evaluates to a long. | |
| the column for computed results. | |
| Returns a column that evaluates to a long. | |
| .. versionadded:: 1.5.0 |
|
|
||
| Returns | ||
| ------- | ||
| :class:`~pyspark.sql.Column` | ||
| value from first column or second if first is NaN . | ||
| Returns a column that evaluates to a double. |
Member
There was a problem hiding this comment.
NaNvl.dataType is left.dataType, and both inputs accept DoubleType or FloatType — so when both inputs are floats the result is a float, not a double.
Suggested change
| Returns a column that evaluates to a double. | |
| Returns a column of the same type as the first input. |
| @@ -10907,6 +11152,7 @@ def extract(field: Column, source: "ColumnOrName") -> Column: | |||
| ------- | |||
| :class:`~pyspark.sql.Column` | |||
| a part of the date/timestamp or interval source. | |||
| Returns a column that evaluates to a double. | |||
Member
There was a problem hiding this comment.
The result type of extract depends on the field, and is never a double — DatePart.parseExtractField resolves to Year/Month/... (integer) for most fields and SecondWithFraction (decimal(8,6)) for SECOND. The doctest right below also shows year=2015 (integer) and second=15.000000 (decimal).
Suggested change
| Returns a column that evaluates to a double. | |
| Returns a column whose type depends on the field to extract, e.g. an integer | |
| for ``YEAR`` and a decimal for ``SECOND``. |
| @@ -10962,6 +11208,7 @@ def date_part(field: Column, source: "ColumnOrName") -> Column: | |||
| ------- | |||
| :class:`~pyspark.sql.Column` | |||
| a part of the date/timestamp or interval source. | |||
| Returns a column that evaluates to a double. | |||
Member
There was a problem hiding this comment.
Same as extract above — the result type depends on the field (integer for most fields, decimal(8,6) for SECOND), never a double.
Suggested change
| Returns a column that evaluates to a double. | |
| Returns a column whose type depends on the field to extract, e.g. an integer | |
| for ``YEAR`` and a decimal for ``SECOND``. |
| @@ -11017,6 +11264,7 @@ def datepart(field: Column, source: "ColumnOrName") -> Column: | |||
| ------- | |||
| :class:`~pyspark.sql.Column` | |||
| a part of the date/timestamp or interval source. | |||
| Returns a column that evaluates to a double. | |||
Member
There was a problem hiding this comment.
Same as extract/date_part above — the result type depends on the field, never a double.
Suggested change
| Returns a column that evaluates to a double. | |
| Returns a column whose type depends on the field to extract, e.g. an integer | |
| for ``YEAR`` and a decimal for ``SECOND``. |
Member
Author
|
Thank you @dongjoon-hyun for review. Let me try to take a look throughoutly. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes were proposed in this pull request?
This documents, for every built-in function in the PySpark
functionsAPI (builtin.py), theaccepted input type of each argument (
Parameters) and the return type of each function(
Returns), using the numeric umbrella where numeric subtypes cast in andtimestampforTIMESTAMP_NTZ in type phrases.
Subtask of SPARK-57999, split out from #57079 for reviewability. This PR covers only
the PySpark
builtin.pysurface.Why are the changes needed?
The PySpark
functionsdocstrings previously had no per-argument type information for mostfunctions. This fills that gap.
Does this PR introduce any user-facing change?
Yes, documentation only. No behavioral or API change.
How was this patch tested?
Python lint (flake8 + black) and the docstring doctests pass. Types were derived from and verified
against the analyzer's behavior and each expression's
inputTypes/dataType.Co-authored-by: Isaac