`narwhals.Series.dt`

`convert_time_zone(time_zone: str) -> SeriesT`

Convert time zone.

If converting from a time-zone-naive column, then conversion happens as if converting from UTC.

Parameters:

Name	Type	Description	Default
`time_zone`	`str`	Target time zone.	required

Returns:

Type	Description
`SeriesT`	A new Series with the specified time zone.

Examples:

>>> from datetime import datetime, timezone
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2024, 1, 1, tzinfo=timezone.utc),
...         datetime(2024, 1, 2, tzinfo=timezone.utc),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.convert_time_zone("Asia/Kathmandu").to_native()
0   2024-01-01 05:45:00+05:45
1   2024-01-02 05:45:00+05:45
dtype: datetime64[ns, Asia/Kathmandu]

`date() -> SeriesT`

Get the date in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series with the date portion of the datetime values.

Raises:

Type	Description
`NotImplementedError`	If pandas default backend is being used.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2012, 1, 7, 10, 20), datetime(2023, 3, 10, 11, 32)]
... ).convert_dtypes(dtype_backend="pyarrow")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.date().to_native()
0    2012-01-07
1    2023-03-10
dtype: date32[day][pyarrow]

`day() -> SeriesT`

Extracts the day in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the day component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2022, 1, 1), datetime(2022, 1, 5)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.day().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    5
  ]
]

`hour() -> SeriesT`

Extracts the hour in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the hour component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.hour().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    5,
    9
  ]
]

`microsecond() -> SeriesT`

Extracts the microseconds in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the microsecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.microsecond().alias("datetime").to_native()
0    400000
1         0
Name: datetime, dtype: int32

`millisecond() -> SeriesT`

Extracts the milliseconds in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the millisecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.millisecond().alias("datetime").to_native()
0    400
1      0
Name: datetime, dtype: int32

`minute() -> SeriesT`

Extracts the minute in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the minute component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.minute().to_native()
0     3
1    12
dtype: int32

`month() -> SeriesT`

Gets the month in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the month component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([datetime(2012, 1, 7), datetime(2023, 3, 10)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.month().to_native()
shape: (2,)
Series: '' [i8]
[
        1
        3
]

`nanosecond() -> SeriesT`

Extract the nanoseconds in a date series.

Returns:

Type	Description
`SeriesT`	A new Series containing the nanosecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.nanosecond().alias("datetime").to_native()
0    400000000
1            0
Name: datetime, dtype: int32

`ordinal_day() -> SeriesT`

Get ordinal day.

Returns:

Type	Description
`SeriesT`	A new Series containing the ordinal day (day of year) for each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2020, 1, 1), datetime(2020, 8, 3)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.ordinal_day().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    216
  ]
]

`replace_time_zone(time_zone: str | None) -> SeriesT`

Replace time zone.

Parameters:

Name	Type	Description	Default
`time_zone`	`str \| None`	Target time zone.	required

Returns:

Type	Description
`SeriesT`	A new Series with the specified time zone.

Examples:

>>> from datetime import datetime, timezone
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         datetime(2024, 1, 1, tzinfo=timezone.utc),
...         datetime(2024, 1, 2, tzinfo=timezone.utc),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.replace_time_zone(
...     "Asia/Kathmandu"
... ).to_native()
shape: (2,)
Series: '' [datetime[μs, Asia/Kathmandu]]
[
        2024-01-01 00:00:00 +0545
        2024-01-02 00:00:00 +0545
]

`second() -> SeriesT`

Extracts the seconds in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the second component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2022, 1, 1, 5, 3, 10), datetime(2022, 1, 5, 9, 12, 4)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.second().to_native()
0    10
1     4
dtype: int32

`timestamp(time_unit: TimeUnit) -> SeriesT`

Return a timestamp in the given time unit.

Parameters:

Name	Type	Description	Default
`time_unit`	`TimeUnit`	{'ns', 'us', 'ms'} Time unit.	required

Returns:

Type	Description
`SeriesT`	A new Series with timestamps in the specified time unit.

Examples:

>>> from datetime import date
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [date(2001, 1, 1), None, date(2001, 1, 3)], dtype="datetime64[ns]"
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.timestamp("ms").to_native()
0    9.783072e+11
1             NaN
2    9.784800e+11
dtype: float64

`total_microseconds() -> SeriesT`

Get total microseconds.

Returns:

Type	Description
`SeriesT`	A new Series containing the total number of microseconds for each timedelta value.

Notes

The function outputs the total microseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         timedelta(microseconds=10),
...         timedelta(milliseconds=1, microseconds=200),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_microseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        1200
]

`total_milliseconds() -> SeriesT`

Get total milliseconds.

Notes

The function outputs the total milliseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
`SeriesT`	A new Series containing the total number of milliseconds for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         timedelta(milliseconds=10),
...         timedelta(milliseconds=20, microseconds=40),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_milliseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        20
]

`total_minutes() -> SeriesT`

Get total minutes.

Notes

The function outputs the total minutes in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
`SeriesT`	A new Series containing the total number of minutes for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_minutes().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        20
]

`total_nanoseconds() -> SeriesT`

Get total nanoseconds.

Notes

The function outputs the total nanoseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
`SeriesT`	A new Series containing the total number of nanoseconds for each timedelta value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     ["2024-01-01 00:00:00.000000001", "2024-01-01 00:00:00.000000002"]
... ).str.to_datetime(time_unit="ns")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.diff().dt.total_nanoseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        null
        1
]

`total_seconds() -> SeriesT`

Get total seconds.

Notes

The function outputs the total seconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
`SeriesT`	A new Series containing the total number of seconds for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_seconds().to_native()
shape: (2,)
Series: '' [i64]
[
        600
        1240
]

`to_string(format: str) -> SeriesT`

Convert a Date/Time/Datetime series into a String series with the given format.

Parameters:

Name	Type	Description	Default
`format`	`str`	Format string for converting the datetime to string.	required

Returns:

Type	Description
`SeriesT`	A new Series with the datetime values formatted as strings according to the specified format.

Notes

Unfortunately, different libraries interpret format directives a bit differently.

Chrono, the library used by Polars, uses "%.f" for fractional seconds, whereas pandas and Python stdlib use ".%f".
PyArrow interprets "%S" as "seconds, including fractional seconds" whereas most other tools interpret it as "just seconds, as 2 digits".

Therefore, we make the following adjustments:

for pandas-like libraries, we replace "%S.%f" with "%S%.f".
for PyArrow, we replace "%S.%f" with "%S".

Workarounds like these don't make us happy, and we try to avoid them as much as possible, but here we feel like it's the best compromise.

If you just want to format a date/datetime Series as a local datetime string, and have it work as consistently as possible across libraries, we suggest using:

"%Y-%m-%dT%H:%M:%S%.f" for datetimes
"%Y-%m-%d" for dates

though note that, even then, different tools may return a different number of trailing zeros. Nonetheless, this is probably consistent enough for most applications.

If you have an application where this is not enough, please open an issue and let us know.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [
...         [
...             datetime(2020, 3, 1),
...             datetime(2020, 4, 1),
...         ]
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.to_string("%Y/%m/%d").to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    "2020/03/01",
    "2020/04/01"
  ]
]

`weekday() -> SeriesT`

Extract the week day in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the week day for each datetime value.
`SeriesT`	Returns the ISO weekday number where monday = 1 and sunday = 7

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2020, 1, 1), datetime(2020, 8, 3)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.weekday().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    3,
    1
  ]
]

`year() -> SeriesT`

Get the year in a datetime series.

Returns:

Type	Description
`SeriesT`	A new Series containing the year component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([datetime(2012, 1, 7), datetime(2023, 3, 10)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.year().to_native()
shape: (2,)
Series: '' [i32]
[
        2012
        2023
]