hZSSKJr SSKJr SSKJr SSKJr SSKJr \(a SSKJr SSK J r \"SS S 9r "S S \\ 5r g )) annotations) TYPE_CHECKING)Any)Generic)TypeVar)Series)TimeUnitSeriesTz Series[Any])boundc\rSrSrSSjrSSjrSSjrSSjrSSjrSSjr SSjr SS jr SS jr SS jr SS jrSS jrSSjrSSjrSSjrSSjrSSjrSSjrSSjrSSjrSSjrSSjrSrg) SeriesDateTimeNamespacecXlg)N_narwhals_series)selfseriess D/var/www/html/env/lib/python3.13/site-packages/narwhals/series_dt.py__init__ SeriesDateTimeNamespace.__init__s &cURRURRRR 55$)a[Get the date in a datetime series. Returns: A new Series with the date portion of the datetime values. Raises: 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] )r_with_compliant_compliant_seriesdtdaters rrSeriesDateTimeNamespace.dates;,$$44  ! ! 3 3 6 6 ; ; =  rcURRURRRR 55$)aGet the year in a datetime series. Returns: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i32] [ 2012 2023 ] )rrrryearrs rr SeriesDateTimeNamespace.year-s;($$44  ! ! 3 3 6 6 ; ; =  rcURRURRRR 55$)aGets the month in a datetime series. Returns: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 1 3 ] )rrrrmonthrs rr#SeriesDateTimeNamespace.monthEs;($$44  ! ! 3 3 6 6 < < >  rcURRURRRR 55$)aExtracts the day in a datetime series. Returns: 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() # doctest: +ELLIPSIS [ [ 1, 5 ] ] )rrrrdayrs rr&SeriesDateTimeNamespace.day]s;.$$44  ! ! 3 3 6 6 : : <  rcURRURRRR 55$)a'Extracts the hour in a datetime series. Returns: 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() # doctest: +ELLIPSIS [ [ 5, 9 ] ] )rrrrhourrs rr)SeriesDateTimeNamespace.hourxs;.$$44  ! ! 3 3 6 6 ; ; =  rcURRURRRR 55$)aExtracts the minute in a datetime series. Returns: 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 )rrrrminuters rr,SeriesDateTimeNamespace.minute;&$$44  ! ! 3 3 6 6 = = ?  rcURRURRRR 55$)aExtracts the seconds in a datetime series. Returns: 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 )rrrrsecondrs rr0SeriesDateTimeNamespace.secondr.rcURRURRRR 55$)aKExtracts the milliseconds in a datetime series. Returns: 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 )rrrr millisecondrs rr3#SeriesDateTimeNamespace.milliseconds;,$$44  ! ! 3 3 6 6 B B D  rcURRURRRR 55$)aRExtracts the microseconds in a datetime series. Returns: 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 )rrrr microsecondrs rr6#SeriesDateTimeNamespace.microsecond;.$$44  ! ! 3 3 6 6 B B D  rcURRURRRR 55$)aOExtract the nanoseconds in a date series. Returns: 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 )rrrr nanosecondrs rr:"SeriesDateTimeNamespace.nanoseconds;,$$44  ! ! 3 3 6 6 A A C  rcURRURRRR 55$)aGet ordinal day. Returns: 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() # doctest: +ELLIPSIS [ [ 1, 216 ] ] )rrrr ordinal_dayrs rr=#SeriesDateTimeNamespace.ordinal_dayr8rcURRURRRR 55$)a^Extract the week day in a datetime series. Returns: A new Series containing the week day for each datetime value. 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() # doctest: +ELLIPSIS [ [ 3, 1 ] ] )rrrrweekdayrs rr@SeriesDateTimeNamespace.weekday+s;0$$44  ! ! 3 3 6 6 > > @  rcURRURRRR 55$)aGet 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: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 20 ] )rrrr total_minutesrs rrC%SeriesDateTimeNamespace.total_minutesG;6$$44  ! ! 3 3 6 6 D D F  rcURRURRRR 55$)aGet 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: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 600 1240 ] )rrrr total_secondsrs rrG%SeriesDateTimeNamespace.total_secondsfrErcURRURRRR 55$)a=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: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 20 ] )rrrrtotal_millisecondsrs rrJ*SeriesDateTimeNamespace.total_milliseconds;<$$44  ! ! 3 3 6 6 I I K  rcURRURRRR 55$)a?Get total microseconds. Returns: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 1200 ] )rrrrtotal_microsecondsrs rrN*SeriesDateTimeNamespace.total_microsecondsrLrcURRURRRR 55$)a*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: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ null 1 ] )rrrrtotal_nanosecondsrs rrQ)SeriesDateTimeNamespace.total_nanosecondss;6$$44  ! ! 3 3 6 6 H H J  rcURRURRRR U55$)aConvert a Date/Time/Datetime series into a String series with the given format. Arguments: format: Format string for converting the datetime to string. Returns: 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() # doctest: +ELLIPSIS [ [ "2020/03/01", "2020/04/01" ] ] )rrrr to_string)rformats rrT!SeriesDateTimeNamespace.to_strings>|$$44  ! ! 3 3 6 6 @ @ H  rcURRURRRR U55$)uReplace time zone. Arguments: time_zone: Target time zone. Returns: 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() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [datetime[μs, Asia/Kathmandu]] [ 2024-01-01 00:00:00 +0545 2024-01-02 00:00:00 +0545 ] )rrrrreplace_time_zone)r time_zones rrX)SeriesDateTimeNamespace.replace_time_zone*s=<$$44  ! ! 3 3 6 6 H H S  rcUc Sn[U5eURRURRRR U55$)aConvert time zone. If converting from a time-zone-naive column, then conversion happens as if converting from UTC. Arguments: time_zone: Target time zone. Returns: 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] zTarget `time_zone` cannot be `None` in `convert_time_zone`. Please use `replace_time_zone(None)` if you want to remove the time zone.) TypeErrorrrrrconvert_time_zone)rrYmsgs rr])SeriesDateTimeNamespace.convert_time_zoneLsU8  ZCC. $$44  ! ! 3 3 6 6 H H S  rcUS;aSU<S3n[U5eURRURRRR U55$)aFReturn a timestamp in the given time unit. Arguments: time_unit: {'ns', 'us', 'ms'} Time unit. Returns: 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 >msnsusz=invalid `time_unit` Expected one of {'ns', 'us', 'ms'}, got .) ValueErrorrrrr timestamp)r time_unitr^s rrf!SeriesDateTimeNamespace.timestamposj0 . .AAJ QP S/ !$$44  ! ! 3 3 6 6 @ @ K  rrN)rr returnNone)rir )rUstrrir )rYz str | Nonerir )rYrkrir )rgr rir )__name__ __module__ __qualname____firstlineno__rrr r#r&r)r,r0r3r6r:r=r@rCrGrJrNrQrTrXr]rf__static_attributes__rrr r sv' 4 0 0 6 6 . . 4 6 4 6 8 > >  D  D >@ D  D! F  rr N) __future__rtypingrrrrnarwhals.seriesrnarwhals.typingr r r rqrrrvs<" &( )= 1@  gg.@  r