From 2ca4f7bfdc3ed1d0529cab2f2f6d524f25738bcf Mon Sep 17 00:00:00 2001 From: Alexander Beedie Date: Fri, 12 Jan 2024 18:58:44 +0400 Subject: [PATCH] add century/millennium for series, add doc entries --- .../source/reference/expressions/temporal.rst | 8 +- .../docs/source/reference/series/temporal.rst | 8 +- py-polars/polars/series/datetime.py | 76 +++++++++++++++++++ .../tests/unit/namespaces/test_datetime.py | 2 +- 4 files changed, 87 insertions(+), 7 deletions(-) diff --git a/py-polars/docs/source/reference/expressions/temporal.rst b/py-polars/docs/source/reference/expressions/temporal.rst index e976604fd18a6..a8c33bb7cfc97 100644 --- a/py-polars/docs/source/reference/expressions/temporal.rst +++ b/py-polars/docs/source/reference/expressions/temporal.rst @@ -11,8 +11,9 @@ The following methods are available under the `expr.dt` attribute. Expr.dt.base_utc_offset Expr.dt.cast_time_unit - Expr.dt.replace_time_zone + Expr.dt.century Expr.dt.combine + Expr.dt.convert_time_zone Expr.dt.date Expr.dt.datetime Expr.dt.day @@ -25,18 +26,20 @@ The following methods are available under the `expr.dt` attribute. Expr.dt.iso_year Expr.dt.microsecond Expr.dt.microseconds + Expr.dt.millennium Expr.dt.millisecond Expr.dt.milliseconds Expr.dt.minute Expr.dt.minutes Expr.dt.month - Expr.dt.month_start Expr.dt.month_end + Expr.dt.month_start Expr.dt.nanosecond Expr.dt.nanoseconds Expr.dt.offset_by Expr.dt.ordinal_day Expr.dt.quarter + Expr.dt.replace_time_zone Expr.dt.round Expr.dt.second Expr.dt.seconds @@ -55,5 +58,4 @@ The following methods are available under the `expr.dt` attribute. Expr.dt.week Expr.dt.weekday Expr.dt.with_time_unit - Expr.dt.convert_time_zone Expr.dt.year diff --git a/py-polars/docs/source/reference/series/temporal.rst b/py-polars/docs/source/reference/series/temporal.rst index 4467393d90fa6..97e7f77513375 100644 --- a/py-polars/docs/source/reference/series/temporal.rst +++ b/py-polars/docs/source/reference/series/temporal.rst @@ -11,8 +11,9 @@ The following methods are available under the `Series.dt` attribute. Series.dt.base_utc_offset Series.dt.cast_time_unit - Series.dt.replace_time_zone + Series.dt.century Series.dt.combine + Series.dt.convert_time_zone Series.dt.date Series.dt.datetime Series.dt.day @@ -28,19 +29,21 @@ The following methods are available under the `Series.dt` attribute. Series.dt.median Series.dt.microsecond Series.dt.microseconds + Series.dt.millennium Series.dt.millisecond Series.dt.milliseconds Series.dt.min Series.dt.minute Series.dt.minutes Series.dt.month - Series.dt.month_start Series.dt.month_end + Series.dt.month_start Series.dt.nanosecond Series.dt.nanoseconds Series.dt.offset_by Series.dt.ordinal_day Series.dt.quarter + Series.dt.replace_time_zone Series.dt.round Series.dt.second Series.dt.seconds @@ -59,5 +62,4 @@ The following methods are available under the `Series.dt` attribute. Series.dt.week Series.dt.weekday Series.dt.with_time_unit - Series.dt.convert_time_zone Series.dt.year diff --git a/py-polars/polars/series/datetime.py b/py-polars/polars/series/datetime.py index 8e6a4aa1d0944..2b2a6e52244d1 100644 --- a/py-polars/polars/series/datetime.py +++ b/py-polars/polars/series/datetime.py @@ -222,6 +222,82 @@ def strftime(self, format: str) -> Series: """ return self.to_string(format) + def millennium(self) -> Expr: + """ + Extract the millennium from underlying representation. + + Applies to Date and Datetime columns. + + Returns the millennium number in the calendar date. + + Returns + ------- + Expr + Expression of data type :class:`Int32`. + + Examples + -------- + >>> from datetime import date + >>> s = pl.Series( + ... "dt", + ... [ + ... date(999, 12, 31), + ... date(1897, 5, 7), + ... date(2000, 1, 1), + ... date(2001, 7, 5), + ... date(3002, 10, 20), + ... ], + ... ) + >>> s.dt.millennium() + shape: (5,) + Series: 'dt' [i32] + [ + 1 + 2 + 2 + 3 + 4 + ] + """ + + def century(self) -> Expr: + """ + Extract the century from underlying representation. + + Applies to Date and Datetime columns. + + Returns the century number in the calendar date. + + Returns + ------- + Expr + Expression of data type :class:`Int32`. + + Examples + -------- + >>> from datetime import date + >>> s = pl.Series( + ... "dt", + ... [ + ... date(999, 12, 31), + ... date(1897, 5, 7), + ... date(2000, 1, 1), + ... date(2001, 7, 5), + ... date(3002, 10, 20), + ... ], + ... ) + >>> s.dt.century() + shape: (5,) + Series: 'dt' [i32] + [ + 10 + 19 + 20 + 21 + 31 + ] + """ + def year(self) -> Series: """ Extract the year from the underlying date representation. diff --git a/py-polars/tests/unit/namespaces/test_datetime.py b/py-polars/tests/unit/namespaces/test_datetime.py index 855067a61add3..a160bae57c414 100644 --- a/py-polars/tests/unit/namespaces/test_datetime.py +++ b/py-polars/tests/unit/namespaces/test_datetime.py @@ -46,7 +46,7 @@ def test_dt_to_string(series_of_int_dates: pl.Series) -> None: @pytest.mark.parametrize( ("unit_attr", "expected"), [ - ("millennium", pl.Series(values=[1, 2, 2], dtype=pl.Int32)), + ("millennium", pl.Series(values=[2, 3, 3], dtype=pl.Int32)), ("century", pl.Series(values=[20, 21, 21], dtype=pl.Int32)), ("year", pl.Series(values=[1997, 2024, 2052], dtype=pl.Int32)), ("iso_year", pl.Series(values=[1997, 2024, 2052], dtype=pl.Int32)),