feat: Add dt.replace

[mcrumiller]

Closes #8879.

@MarcoGorelli since this involves constructing new Date/Datetime chunked arrays, I moved some of the fn datetime() construction code that needed to be reused into DateChunked::new_from_parts and DatetimeChunked::new_from_parts.

Examples

import polars as pl
from polars import col
from datetime import date, datetime

# -- Series
s = pl.Series([date(2024, 1, 1), date(2024, 1, 2), date(2024, 1, 3)])
s.dt.replace(month=2, day=15)
# shape: (3,)
# Series: '' [date]
# [
#         2024-02-15
#         2024-02-15
#         2024-02-15
# ]

# -- Expr
df = pl.DataFrame({
    "a": [datetime(1, 1, 1, 1, 1, 1, 1)],
})
df.with_columns(
    col("a").dt.replace(year=2024).alias("year"),
    col("a").dt.replace(year=2015, day=23, second=45, microsecond=5000).alias("many"),
)
# shape: (1, 3)
# ┌────────────────────────────┬────────────────────────────┬─────────────────────────┐
# │ a                          ┆ year                       ┆ many                    │
# │ ---                        ┆ ---                        ┆ ---                     │
# │ datetime[μs]               ┆ datetime[μs]               ┆ datetime[μs]            │
# ╞════════════════════════════╪════════════════════════════╪═════════════════════════╡
# │ 0001-01-01 01:01:01.000001 ┆ 2024-01-01 01:01:01.000001 ┆ 2015-01-23 01:01:45.005 │
# └────────────────────────────┴────────────────────────────┴─────────────────────────┘

# -- Expr using other columns
df = pl.DataFrame({
    "date": [date(2024, 1, 1), date(2024, 1, 2)],
    "day": [6, 13],
})
df.with_columns(
    col("date").dt.replace(day="day")
)
# shape: (2, 2)
# ┌────────────┬─────┐
# │ date       ┆ day │
# │ ---        ┆ --- │
# │ date       ┆ i64 │
# ╞════════════╪═════╡
# │ 2024-01-06 ┆ 6   │
# │ 2024-01-13 ┆ 13  │
# └────────────┴─────┘

[mcrumiller]

@MarcoGorelli I could also perhaps use some help creating tests to cover the non_existent parameter and the ambiguous parameter, neither of which my tests cover.

[MarcoGorelli]

@MarcoGorelli I could also perhaps use some help creating tests to cover the non_existent parameter and the ambiguous parameter, neither of which my tests cover.

sure - would it work to start with

datetime(2020, 10, 25)

and then do .dt.replace(hour=1)?

[mcrumiller]

sure - would it work to start with

datetime(2020, 10, 25)

and then do .dt.replace(hour=1)?

Thanks--looks like I need to use Europe/London for this to work (found in another unit test).

[codecov]

Codecov Report

Attention: Patch coverage is 98.56115% with 4 lines in your changes missing coverage. Please review.

Project coverage is 79.63%. Comparing base (91ad299) to head (33019a1).
Report is 36 commits behind head on main.

Files with missing lines	Patch %	Lines
...ates/polars-plan/src/dsl/function_expr/datetime.rs	94.59%	2 Missing ⚠️
.../polars-python/src/lazyframe/visitor/expr_nodes.rs	0.00%	1 Missing ⚠️
crates/polars-time/src/chunkedarray/datetime.rs	97.87%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #19708      +/-   ##
==========================================
+ Coverage   79.60%   79.63%   +0.02%     
==========================================
  Files        1567     1568       +1     
  Lines      218398   218628     +230     
  Branches     2465     2465              
==========================================
+ Hits       173866   174095     +229     
- Misses      43963    43964       +1     
  Partials      569      569              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[MarcoGorelli]

thanks for working on this, it'll probably be useful to people

[MarcoGorelli]

thanks - the microsecond / nanosecond part looks a bit off?

In [12]: df = pl.DataFrame({'a': ['2020-01-01T00:00:00.123456789']*2}).select(pl.col('a').str.to_dat
    ...: etime(time_unit='ns'))

In [13]: df
Out[13]: 
shape: (2, 1)
┌───────────────────────────────┐
│ a                             │
│ ---                           │
│ datetime[ns]                  │
╞═══════════════════════════════╡
│ 2020-01-01 00:00:00.123456789 │
│ 2020-01-01 00:00:00.123456789 │
└───────────────────────────────┘

In [14]: df['a'].dt.replace(year=2021)
Out[14]: 
shape: (2,)
Series: 'a' [datetime[ns]]
[
        2021-01-01 00:00:00.123456
        2021-01-01 00:00:00.123456
]

[MarcoGorelli]

print statement

[MarcoGorelli]

😄 no worries, thanks for updating

looks like there's another merge conflict, sorry

[mcrumiller]

looks like there's another merge conflict, sorry

Figured that would happen that with that PR. Updated.

[MarcoGorelli]

Nice one, thanks @mcrumiller !

Leaving open a bit in case there's objections

separately to this PR, as a follow-up, py-polars/tests/unit/operations/namespaces/temporal/test_datetime.py has become very big, I think it'd be worth splitting these dt.replace tests into a separate test file

[MarcoGorelli]

There's been no objections, and I think this feature would be really ergonomic (and higher-perf than some current alternatives involving strftime / strptime string hacking), so I'd say let's ship it - thanks @mcrumiller !