Add docstring examples for Scalar temporal functions

[ntjohnson1]

Which issue does this PR close?

• Part 11 of Add doctests to functions to help humans and agents #1400
• Related to Make it easier for agents to generate datafusion-python code #1394

Rationale for this change

Add example usage to docstrings for Scalar temporal functions to improve documentation.

What changes are included in this PR?

The first PR was basically adding a docstring to everything in functions. I broke it apart into a PR (that already merged) for the infra. I then reviewed and merged an example PR of adding the docstrings in parts. This is now the follow up opening a handful of PRs for the remaining functions in functions.py Everything is co-authored with Claude since I used claude to extend the handwritten examples I wrote for reference and to split apart the large PR rather than doing it manually.

I've reviewed all the code prior to PR.

Are there any user-facing changes?

No

[kosiew]

@ntjohnson1
Thanks for your contribution

[kosiew]

The PR title is Add docstring examples for scalar temporal functions, but to_date, to_time, and to_local_time still have no examples. Since those are public temporal wrappers in the same section, this feels incomplete.

[kosiew]

datepart, extract, and datetrunc are aliases, but each now carries its own full doctest.

I think setting up one example would risk of docs drift between the canonical function and its alias.

[kosiew]

It would be more consistent to use
dfn.functions.date_bin
here

[ntjohnson1]

My network connection on the plane is bad so I can't open the PRs for better discussion. Those missing functions are new since I branched to start this work. The groupings in these PRs were mostly just to make it less painful to review. My preference would be to land them if they are sufficient quality then I'll make a final pass over everything to do any final cleanup for consistency.

…

On Fri, Mar 13, 2026, 10:36 AM kosiew ***@***.***> wrote: ***@***.**** commented on this pull request. @ntjohnson1 <https://github.com/ntjohnson1> Thanks for your contribution ------------------------------ In python/datafusion/functions.py <#1424 (comment)> : > @@ -1393,7 +1584,20 @@ def named_struct(name_pairs: list[tuple[str, Expr]]) -> Expr: def from_unixtime(arg: Expr) -> Expr: - """Converts an integer to RFC3339 timestamp format string.""" + """Converts an integer to RFC3339 timestamp format string. + + Examples: + --------- + >>> ctx = dfn.SessionContext() + >>> df = ctx.from_pydict({"a": [0]}) + >>> result = df.select( + ... dfn.functions.from_unixtime( + ... dfn.col("a") + ... ).alias("ts") + ... ) + >>> str(result.collect_column("ts")[0].as_py()) + '1970-01-01 00:00:00' + """ return Expr(f.from_unixtime(arg.expr)) The PR title is Add docstring examples for scalar temporal functions, but to_date, to_time, and to_local_time still have no examples. Since those are public temporal wrappers in the same section, this feels incomplete. ------------------------------ In python/datafusion/functions.py <#1424 (comment)> : > """ return date_part(part, date) def date_part(part: Expr, date: Expr) -> Expr: - """Extracts a subfield from the date.""" + """Extracts a subfield from the date. + + Examples: + --------- + >>> ctx = dfn.SessionContext() + >>> df = ctx.from_pydict({"a": ["2021-07-15T00:00:00"]}) + >>> df = df.select(dfn.functions.to_timestamp(dfn.col("a")).alias("a")) + >>> result = df.select( + ... dfn.functions.date_part(dfn.lit("year"), dfn.col("a")).alias("y")) + >>> result.collect_column("y")[0].as_py() + 2021 + """ return Expr(f.date_part(part.expr, date.expr)) def extract(part: Expr, date: Expr) -> Expr: """Extracts a subfield from the date. This is an alias for :py:func:`date_part`. datepart, extract, and datetrunc are aliases, but each now carries its own full doctest. I think setting up one example would risk of docs drift between the canonical function and its alias. ------------------------------ In python/datafusion/functions.py <#1424 (comment)> : > """ return date_trunc(part, date) def date_bin(stride: Expr, source: Expr, origin: Expr) -> Expr: - """Coerces an arbitrary timestamp to the start of the nearest specified interval.""" + """Coerces an arbitrary timestamp to the start of the nearest specified interval. + + Examples: + --------- + >>> ctx = dfn.SessionContext() + >>> result = ctx.sql( + ... "SELECT date_bin(interval '1 day'," It would be more consistent to use dfn.functions.date_bin here — Reply to this email directly, view it on GitHub <#1424 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AF4LYOT6XUTRVM3M33LXMP34QPQC3AVCNFSM6AAAAACWOQ54KGVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTSNBTGAZTQMBWGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>