kosiew commented on code in PR #1419:
URL:
https://github.com/apache/datafusion-python/pull/1419#discussion_r2929678794
##########
python/datafusion/functions.py:
##########
@@ -295,37 +295,94 @@
def isnan(expr: Expr) -> Expr:
- """Returns true if a given number is +NaN or -NaN otherwise returns
false."""
+ """Returns true if a given number is +NaN or -NaN otherwise returns false.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": [1.0, np.nan]})
+ >>> result = df.select(dfn.functions.isnan(dfn.col("a")).alias("isnan"))
+ >>> result.collect_column("isnan")[1].as_py()
+ True
+ """
return Expr(f.isnan(expr.expr))
def nullif(expr1: Expr, expr2: Expr) -> Expr:
"""Returns NULL if expr1 equals expr2; otherwise it returns expr1.
This can be used to perform the inverse operation of the COALESCE
expression.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": [1, 2], "b": [1, 3]})
+ >>> result = df.select(
+ ... dfn.functions.nullif(dfn.col("a"), dfn.col("b")).alias("nullif"))
+ >>> result.collect_column("nullif").to_pylist()
+ [None, 2]
"""
return Expr(f.nullif(expr1.expr, expr2.expr))
def encode(expr: Expr, encoding: Expr) -> Expr:
- """Encode the ``input``, using the ``encoding``. encoding can be base64 or
hex."""
+ """Encode the ``input``, using the ``encoding``. encoding can be base64 or
hex.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": ["hello"]})
+ >>> result = df.select(
+ ... dfn.functions.encode(dfn.col("a"), dfn.lit("base64")).alias("enc"))
+ >>> result.collect_column("enc")[0].as_py()
+ 'aGVsbG8'
+ """
return Expr(f.encode(expr.expr, encoding.expr))
def decode(expr: Expr, encoding: Expr) -> Expr:
- """Decode the ``input``, using the ``encoding``. encoding can be base64 or
hex."""
+ """Decode the ``input``, using the ``encoding``. encoding can be base64 or
hex.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": ["aGVsbG8="]})
+ >>> result = df.select(
+ ... dfn.functions.decode(dfn.col("a"), dfn.lit("base64")).alias("dec"))
+ >>> result.collect_column("dec")[0].as_py()
+ b'hello'
+ """
return Expr(f.decode(expr.expr, encoding.expr))
def array_to_string(expr: Expr, delimiter: Expr) -> Expr:
- """Converts each element to its text representation."""
+ """Converts each element to its text representation.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": [[1, 2, 3]]})
+ >>> result = df.select(
+ ... dfn.functions.array_to_string(dfn.col("a"),
dfn.lit(",")).alias("s"))
+ >>> result.collect_column("s")[0].as_py()
+ '1,2,3'
+ """
return Expr(f.array_to_string(expr.expr, delimiter.expr.cast(pa.string())))
def array_join(expr: Expr, delimiter: Expr) -> Expr:
"""Converts each element to its text representation.
This is an alias for :py:func:`array_to_string`.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": [[1, 2, 3]]})
+ >>> result = df.select(
+ ... dfn.functions.array_join(dfn.col("a"), dfn.lit("-")).alias("s"))
Review Comment:
`array_join`, `list_to_string`, and `list_join` are all aliases of
`array_to_string`, but each now carries its own slightly different example.
I think keeping the full runnable example on the canonical function and
letting the aliases point to it to avoid three extra snippets to maintain
whenever the preferred usage changes.
##########
python/datafusion/functions.py:
##########
@@ -374,32 +476,61 @@ def concat_ws(separator: str, *args: Expr) -> Expr:
"""Concatenates the list ``args`` with the separator.
``NULL`` arguments are ignored. ``separator`` should not be ``NULL``.
+
+ Examples:
+ ---------
+ >>> ctx = dfn.SessionContext()
+ >>> df = ctx.from_pydict({"a": ["hello"], "b": ["world"]})
+ >>> result = df.select(
+ ... dfn.functions.concat_ws("-", dfn.col("a"),
dfn.col("b")).alias("c"))
+ >>> result.collect_column("c")[0].as_py()
+ 'hello-world'
"""
args = [arg.expr for arg in args]
return Expr(f.concat_ws(separator, args))
def order_by(expr: Expr, ascending: bool = True, nulls_first: bool = True) ->
SortExpr:
- """Creates a new sort expression."""
+ """Creates a new sort expression.
+
+ Examples:
+ ---------
+ >>> sort_expr = dfn.functions.order_by(dfn.col("a"), ascending=False)
+ >>> sort_expr.ascending()
+ False
+ """
return SortExpr(expr, ascending=ascending, nulls_first=nulls_first)
def alias(expr: Expr, name: str, metadata: dict[str, str] | None = None) ->
Expr:
"""Creates an alias expression with an optional metadata dictionary.
- Args:
+ Parameters:
+ -----------
Review Comment:
This docstring switches from the file’s more common `Args:` convention to
`Parameters:`.
It would be cleaner to keep the surrounding style consistent and add the
example without changing the docstring format for just this one helper.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
