add century/millennium for series, add doc entries

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

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

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.

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)),