Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(python): added all missing examples for temporal expressions #6488

Merged
merged 2 commits into from
Jan 27, 2023
Merged

docs(python): added all missing examples for temporal expressions #6488

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
81ac632
added all missing examples for temporal expressions
Jan 27, 2023
6c305f7
fixed failing doctest
Jan 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions py-polars/polars/internals/expr/datetime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,35 @@ def strftime(self, fmt: str) -> pli.Expr:
See `chrono strftime/strptime
<https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_.

Examples
--------
>>> from datetime import timedelta, datetime
>>> df = pl.DataFrame(
... {
... "date": pl.date_range(
... datetime(2020, 3, 1), datetime(2020, 5, 1), "1mo"
... ),
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date")
... .dt.strftime("%Y/%m/%d %H:%M:%S")
... .alias("date_formatted"),
... ]
... )
shape: (3, 2)
┌─────────────────────┬─────────────────────┐
│ date ┆ date_formatted │
│ --- ┆ --- │
│ datetime[μs] ┆ str │
╞═════════════════════╪═════════════════════╡
│ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
│ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
│ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
└─────────────────────┴─────────────────────┘

"""
return pli.wrap_expr(self._pyexpr.strftime(fmt))

Expand Down Expand Up @@ -383,6 +412,35 @@ def iso_year(self) -> pli.Expr:
-------
ISO Year as Int32

Examples
--------
>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2006, 1, 1)
>>> df = pl.DataFrame({"date": pl.date_range(start, stop, timedelta(days=180))})
Comment on lines +418 to +420
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You seem to be a big fan of date_range 😄 I think the examples are fine, but would probably be clearer if you just hardcoded three datetimes in a dataframe. You already specified a start and stop, you're 2/3rds of the way there 😄

Copy link
Contributor Author

@romanovacca romanovacca Jan 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I could do that, but most of the other functions for expressions use date_range to make a couple examples, so I used this so it's in line with the other examples.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I agree I can trim down the amount of rows in this example, the amount now is a bit overkill

>>> df.select(
... [
... pl.col("date"),
... pl.col("date").dt.iso_year().alias("iso_year"),
... ]
... )
shape: (11, 2)
┌─────────────────────┬──────────┐
│ date ┆ iso_year │
│ --- ┆ --- │
│ datetime[μs] ┆ i32 │
╞═════════════════════╪══════════╡
│ 2001-01-01 00:00:00 ┆ 2001 │
│ 2001-06-30 00:00:00 ┆ 2001 │
│ 2001-12-27 00:00:00 ┆ 2001 │
│ 2002-06-25 00:00:00 ┆ 2002 │
│ ... ┆ ... │
│ 2004-06-14 00:00:00 ┆ 2004 │
│ 2004-12-11 00:00:00 ┆ 2004 │
│ 2005-06-09 00:00:00 ┆ 2005 │
│ 2005-12-06 00:00:00 ┆ 2005 │
└─────────────────────┴──────────┘

"""
return pli.wrap_expr(self._pyexpr.iso_year())

Expand Down Expand Up @@ -1148,6 +1206,37 @@ def cast_time_zone(self, tz: str) -> pli.Expr:
tz
Time zone for the `Datetime` Series.

Examples
--------
>>> from datetime import datetime
>>> df = pl.DataFrame(
... {
... "london_timezone": pl.date_range(
... datetime(2020, 3, 1), datetime(2020, 7, 1), "1mo"
... ).dt.with_time_zone(tz="Europe/London"),
... }
... )
>>> df.select(
... [
... pl.col("london_timezone"),
... pl.col("london_timezone")
... .dt.cast_time_zone(tz="Europe/Amsterdam")
... .alias("London_to_Amsterdam"),
... ]
... )
shape: (5, 2)
┌─────────────────────────────┬────────────────────────────────┐
│ london_timezone ┆ London_to_Amsterdam │
│ --- ┆ --- │
│ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
╞═════════════════════════════╪════════════════════════════════╡
│ 2020-03-01 00:00:00 GMT ┆ 2020-03-01 00:00:00 CET │
│ 2020-04-01 01:00:00 BST ┆ 2020-04-01 01:00:00 CEST │
│ 2020-05-01 01:00:00 BST ┆ 2020-05-01 01:00:00 CEST │
│ 2020-06-01 01:00:00 BST ┆ 2020-06-01 01:00:00 CEST │
│ 2020-07-01 01:00:00 BST ┆ 2020-07-01 01:00:00 CEST │
└─────────────────────────────┴────────────────────────────────┘

"""
return pli.wrap_expr(self._pyexpr.dt_cast_time_zone(tz))

Expand All @@ -1163,6 +1252,34 @@ def tz_localize(self, tz: str) -> pli.Expr:
tz
Time zone for the `Datetime` Series.

Examples
--------
>>> from datetime import datetime
>>> df = pl.DataFrame(
... {
... "date": pl.date_range(
... datetime(2020, 3, 1), datetime(2020, 5, 1), "1mo"
... ),
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date")
... .dt.tz_localize(tz="Europe/Amsterdam")
... .alias("tz_localized"),
... ]
... )
shape: (3, 2)
┌─────────────────────┬────────────────────────────────┐
│ date ┆ tz_localized │
│ --- ┆ --- │
│ datetime[μs] ┆ datetime[μs, Europe/Amsterdam] │
╞═════════════════════╪════════════════════════════════╡
│ 2020-03-01 00:00:00 ┆ 2020-03-01 00:00:00 CET │
│ 2020-04-01 00:00:00 ┆ 2020-04-01 00:00:00 CEST │
│ 2020-05-01 00:00:00 ┆ 2020-05-01 00:00:00 CEST │
└─────────────────────┴────────────────────────────────┘
"""
return pli.wrap_expr(self._pyexpr.dt_tz_localize(tz))

Expand Down