polars.date_ranges#

Create a column of date ranges.

Parameters:

start

Lower bound of the date range.

end

Upper bound of the date range.

interval

Interval of the range periods, specified as a Python timedelta object or a Polars duration string like 1h30m25s.

Append _saturating to the interval string to restrict resulting invalid dates to valid ranges.

It is common to attempt to create a month-end date series by using the “1mo” offset string with a start date at the end of the month. This will not produce the desired results. See Note #2 below for further information.

closed{‘both’, ‘left’, ‘right’, ‘none’}

Define which sides of the range are closed (inclusive).

time_unit{None, ‘ns’, ‘us’, ‘ms’}

Time unit of the resulting Datetime data type. Only takes effect if the output column is of type Datetime.

time_zone

Time zone of the resulting Datetime data type. Only takes effect if the output column is of type Datetime.

eager

Evaluate immediately and return a Series. If set to False (default), return an expression instead.

Returns:

Expr or Series: Column of data type List(Date) or List(Datetime).

Examples

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "start": [date(2022, 1, 1), date(2022, 1, 2)],
...         "end": date(2022, 1, 3),
...     }
... )
>>> df.with_columns(pl.date_ranges("start", "end"))
shape: (2, 3)
┌────────────┬────────────┬───────────────────────────────────┐
│ start      ┆ end        ┆ date_range                        │
│ ---        ┆ ---        ┆ ---                               │
│ date       ┆ date       ┆ list[date]                        │
╞════════════╪════════════╪═══════════════════════════════════╡
│ 2022-01-01 ┆ 2022-01-03 ┆ [2022-01-01, 2022-01-02, 2022-01… │
│ 2022-01-02 ┆ 2022-01-03 ┆ [2022-01-02, 2022-01-03]          │
└────────────┴────────────┴───────────────────────────────────┘