Wh ZXddlmZddlmZmZddlmZerddlmZGddeeZy)) annotations) TYPE_CHECKINGGeneric)SeriesT)TimeUnitceZdZddZddZddZddZddZddZddZ ddZ dd Z dd Z dd Z dd Zdd ZddZddZddZddZddZddZddZddZddZd dZd!dZy)"SeriesDateTimeNamespacec||_y)N)_narwhals_series)selfseriess L/var/www/html/jupyter_env/lib/python3.12/site-packages/narwhals/series_dt.py__init__z SeriesDateTimeNamespace.__init__ s &c|jj|jjjj S)aGet the date in a datetime series. 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_seriesdtdater s rrzSeriesDateTimeNamespace.dates;&$$44  ! ! 3 3 6 6 ; ; =  rc|jj|jjjj S)aGet the year in a datetime series. 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 ] )r rrryearrs rrzSeriesDateTimeNamespace.year&s;"$$44  ! ! 3 3 6 6 ; ; =  rc|jj|jjjj S)aGets the month in a datetime series. 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 ] )r rrrmonthrs rrzSeriesDateTimeNamespace.month;s;"$$44  ! ! 3 3 6 6 < < >  rc|jj|jjjj S)aOExtracts the day in a datetime series. 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 ] ] )r rrrdayrs rrzSeriesDateTimeNamespace.dayPs;($$44  ! ! 3 3 6 6 : : <  rc|jj|jjjj S)a^Extracts the hour in a datetime series. 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 ] ] )r rrrhourrs rrzSeriesDateTimeNamespace.hourhs;($$44  ! ! 3 3 6 6 ; ; =  rc|jj|jjjj S)aExtracts the minute in a datetime series. 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 )r rrrminuters rr zSeriesDateTimeNamespace.minute; $$44  ! ! 3 3 6 6 = = ?  rc|jj|jjjj S)aExtracts the seconds in a datetime series. 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 )r rrrsecondrs rr#zSeriesDateTimeNamespace.secondr!rc|jj|jjjj S)asExtracts the milliseconds in a datetime series. 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 )r rrr millisecondrs rr%z#SeriesDateTimeNamespace.millisecond;&$$44  ! ! 3 3 6 6 B B D  rc|jj|jjjj S)ayExtracts the microseconds in a datetime series. 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 )r rrr microsecondrs rr(z#SeriesDateTimeNamespace.microsecondr&rc|jj|jjjj S)axExtract the nanoseconds in a date series. 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 )r rrr nanosecondrs rr*z"SeriesDateTimeNamespace.nanoseconds;&$$44  ! ! 3 3 6 6 A A C  rc|jj|jjjj S)aCGet ordinal day. 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 ] ] )r rrr ordinal_dayrs rr,z#SeriesDateTimeNamespace.ordinal_days;($$44  ! ! 3 3 6 6 B B D  rc|jj|jjjj S)aExtract the week day in a datetime series. Note that 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 ] ] )r rrrweekdayrs rr.zSeriesDateTimeNamespace.weekdays;,$$44  ! ! 3 3 6 6 > > @  rc|jj|jjjj S)a/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. 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 ] )r rrr total_minutesrs rr0z%SeriesDateTimeNamespace.total_minutes;0$$44  ! ! 3 3 6 6 D D F  rc|jj|jjjj S)a2Get 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. 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 ] )r rrr total_secondsrs rr3z%SeriesDateTimeNamespace.total_seconds;r1rc|jj|jjjj S)aGet 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. 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 ] )r rrrtotal_millisecondsrs rr5z*SeriesDateTimeNamespace.total_millisecondsW;6$$44  ! ! 3 3 6 6 I I K  rc|jj|jjjj S)aGet total microseconds. 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 ] )r rrrtotal_microsecondsrs rr8z*SeriesDateTimeNamespace.total_microsecondsvr6rc|jj|jjjj S)ajGet 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. 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 ] )r rrrtotal_nanosecondsrs rr:z)SeriesDateTimeNamespace.total_nanosecondss;0$$44  ! ! 3 3 6 6 H H J  rc|jj|jjjj |S)uConvert a Date/Time/Datetime series into a String series with the given format. Arguments: format: Format string for converting the datetime to string. 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 pandas as pd >>> import narwhals as nw >>> s_native = pd.Series([datetime(2020, 3, 1), datetime(2020, 4, 1)]) >>> s = nw.from_native(s_native, series_only=True) >>> s.dt.to_string("%Y/%m/%d") ┌───────────────┐ |Narwhals Series| |---------------| |0 2020/03/01| |1 2020/04/01| |dtype: object | └───────────────┘ )r rrr to_string)r formats rr<z!SeriesDateTimeNamespace.to_strings>h$$44  ! ! 3 3 6 6 @ @ H  rc|jj|jjjj |S)ujReplace time zone. Arguments: time_zone: Target 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 ] )r rrrreplace_time_zone)r time_zones rr?z)SeriesDateTimeNamespace.replace_time_zones=6$$44  ! ! 3 3 6 6 H H S  rc| d}t||jj|jjjj |S)aRConvert time zone. If converting from a time-zone-naive column, then conversion happens as if converting from UTC. Arguments: time_zone: Target 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.) TypeErrorr rrrconvert_time_zone)r r@msgs rrCz)SeriesDateTimeNamespace.convert_time_zonesU2  ZCC. $$44  ! ! 3 3 6 6 H H S  rc|dvrd|d}t||jj|jjjj |S)aReturn a timestamp in the given time unit. Arguments: time_unit: One of - 'ns': nanosecond. - 'us': microsecond. - 'ms': millisecond. 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 .) ValueErrorr rrr timestamp)r time_unitrDs rrKz!SeriesDateTimeNamespace.timestamp(sj. . .AAJ QP S/ !$$44  ! ! 3 3 6 6 @ @ K  rc|jj|jjjj |S)aDivide the date/datetime range into buckets. Arguments: every: Length of bucket. Must be of form ``, where `multiple` is a positive integer and `unit` is one of - 'ns': nanosecond. - 'us': microsecond. - 'ms': millisecond. - 's': second. - 'm': minute. - 'h': hour. - 'd': day. - 'mo': month. - 'q': quarter. - 'y': year. Examples: >>> from datetime import datetime >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series([datetime(2021, 3, 1, 12, 34)]) >>> s = nw.from_native(s_native, series_only=True) >>> s.dt.truncate("1h").to_native() 0 2021-03-01 12:00:00 dtype: datetime64[ns] )r rrrtruncate)r everys rrNz SeriesDateTimeNamespace.truncateIs=8$$44  ! ! 3 3 6 6 ? ? F  rc|jj|jjjj |S)aOffset this date by a relative time offset. Arguments: by: The offset. Must be of form ``, where `multiple` is a positive integer and `unit` is one of - 'ns': nanosecond. - 'us': microsecond. - 'ms': millisecond. - 's': second. - 'm': minute. - 'h': hour. - 'd': day. - 'mo': month. - 'q': quarter. - 'y': year. Examples: >>> from datetime import datetime >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series([datetime(2021, 3, 1, 12, 34)]) >>> s = nw.from_native(s_native, series_only=True) >>> s.dt.offset_by("1h").to_native() 0 2021-03-01 13:34:00 dtype: datetime64[ns] )r rrr offset_by)r bys rrQz!SeriesDateTimeNamespace.offset_byis=8$$44  ! ! 3 3 6 6 @ @ D  rN)r rreturnNone)rSr)r=strrSr)r@z str | NonerSr)r@rUrSr)rLrrSr)rOrUrSr)rRrUrSr)__name__ __module__ __qualname__rrrrrrr r#r%r(r*r,r.r0r3r5r8r:r<r?rCrKrNrQrrr r s~' . * * 0 0 ( ( . . . 0 4 8 8 > > 86 p > @ B @ rr N) __future__rtypingrrnarwhals.typingrrr rYrrr]s'")#(|  gg.|  r