T.hδddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z dd lm Z dd lm Z dd l mZdd lmZddlmZddlmZddlmZer*ddlmZddlZddlZddlZddlmZddl m!Z!ddlm"Z"ddlm#Z#GddeeZ$e de$eZ%Gddee%Z&Gddee%Z'Gdd ee%Z(Gd!d"ee%Z)y)#) annotations) TYPE_CHECKING)Any)Callable)Generic)Iterator)Literal)Mapping)Sequence)TypeVar)overload)is_numpy_scalar)_validate_dtype) IntoSeriesT)_validate_rolling_arguments) parse_version) ModuleTypeN)Self DataFrame)DType)Implementationc~eZdZdZeddZ ddZeddZdddZe ddZ e ddZ dd Z dd Z ddd Z dd Z dd ZeddZddZddZddZddZddZddZeddZeddZdddddddd ddZddZddZddZddZdd Zdd!Zdd"Zdd#Z dd$Z!dd%Z"dd&Z#dd'Z$dd(Z%dd)Z&dd*dd+Z' d dd,Z(dd-Z)dd.Z*dd/Z+dd0Z,dd1dd2Z-dd3dd4Z.dd5Z/dd6Z0 ddddd7 dd8Z1dd9Z2dd:Z3 ddd; dd<Z4ddd=dd>Z5dd?Z6 d dd@Z7 d ddAZ8ddBZ9ddCZ:ddDZ;ddEZddHZ?ddIZ@ddJZAddKZBddLZCddMZDddNZEddOZFddPZGddQZHddRZIddSZJddTZKddUZLddVZMddWZNddXZOddYZPddZZQdd[ZRdd\ZSdd]ZTdd^ZUdd_ZVdd`ZWddaZXddbZYddcZZdddZ[ddeddfZ\dddddg ddhZ] ddiZ^ddjZ_dddkZ`dddlZadddmZbdddnZcdoddp ddqZddddrZeddsZfddtZgdduZhdd1ddvZidd1ddwZjdd1ddxZkdd1ddyZldddz dd{Zmdddz dd|Zndd}Zodd~ZpeddZqeddZreddZseddZty)SeriesaNarwhals Series, backed by a native series. The native series might be pandas.Series, polars.Series, ... This class is not meant to be instantiated directly - instead, use `narwhals.from_native`, making sure to pass `allow_series=True` or `series_only=True`. cddlm}|S)Nrr)narwhals.dataframer)selfrs c/var/www/html/School_Mangement_New/src/backend/venv/lib/python3.12/site-packages/narwhals/series.py _dataframezSeries._dataframe+s 0c||_t|dr|j|_ydt |d}t |)N__narwhals_series__zQExpected Polars Series or an object which implements `__narwhals_series__`, got: .)_levelhasattrr"_compliant_seriestypeAssertionError)rserieslevelmsgs r__init__zSeries.__init__1sI  60 1%+%?%?%AD "efjkqfresstuC % %r c.|jjS)aReturn implementation of native Series. This can be useful when you need to some special-casing for some libraries for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import pandas as pd >>> s_native = pd.Series([1, 2, 3]) >>> s = nw.from_native(s_native, series_only=True) >>> s.implementation >>> s.implementation.is_pandas() True >>> s.implementation.is_pandas_like() True >>> s.implementation.is_polars() False )r&_implementationrs rimplementationzSeries.implementation>s2%%555r Nc<|jj||S)N)dtypecopy)r& __array__)rr2r3s rr4zSeries.__array__Ys%%//e$/GGr cyNridxs r __getitem__zSeries.__getitem__\s25r cyr6r7r8s rr:zSeries.__getitem___sEHr ct|ts#t|r'|jjdvr|j |S|j |j |S)a)Retrieve elements from the object using integer indexing or slicing. Arguments: idx: The index, slice, or sequence of indices to retrieve. - If `idx` is an integer, a single element is returned. - If `idx` is a slice or a sequence of integers, a subset of the Series is returned. Returns: A single element if `idx` is an integer, else a subset of the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> from typing import Any >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) >>> s_pa = pa.chunked_array([s]) We define a library agnostic function: >>> def agnostic_get_first_item(s_native: IntoSeriesT) -> Any: ... s = nw.from_native(s_native, series_only=True) ... return s[0] We can then pass either pandas, Polars, or any supported library: >>> agnostic_get_first_item(s_pd) np.int64(1) >>> agnostic_get_first_item(s_pl) 1 >>> agnostic_get_first_item(s_pa) 1 We can also make a function to slice the Series: >>> def agnostic_slice(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s[:2].to_native() >>> agnostic_slice(s_pd) 0 1 1 2 dtype: int64 >>> agnostic_slice(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 1 2 ] >>> agnostic_slice(s_pa) [ [ 1, 2 ] ] )iu) isinstanceintrr2kindr&_from_compliant_seriesr8s rr:zSeries.__getitem__bsSD c3  C SYY^^z%A))#. .**4+A+A#+FGGr c6|jjSr6)r&__native_namespace__r/s rrDzSeries.__native_namespace__s%%::<=16.0.0 is required for `Series.__arrow_c_stream__` for object of type )r) r&_native_seriesr%rFpyarrowModuleNotFoundErrorr'r __version__ chunked_arrayto_arrow)rrG native_seriespaexcr+cas rrFzSeries.__arrow_c_stream__s..== ="6 7 33EU3V V 4   (7 2cdhivdwcxyC%c* * R  t}}/ 0$$6F$GG# 4cdhivdwcxyC%c* 3 4sB C'CCc.|jjS)a3Convert Narwhals series to native series. Returns: Series of class that user started with. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 2 2 3 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 1 2 3 ] )r&rIr/s r to_nativezSeries.to_nativesJ%%444r cv|j|jj||j|S)uSet value(s) at given position(s). Arguments: indices: Position(s) to set items at. values: Values to set. Note: This method always returns a new Series, without modifying the original one. Using this function in a for-loop is an anti-pattern, we recommend building up your positions and values beforehand and doing an update in one go. For example, instead of ```python for i in [1, 3, 2]: value = some_function(i) s = s.scatter(i, value) ``` prefer ```python positions = [1, 3, 2] values = [some_function(x) for x in positions] s = s.scatter(positions, values) ``` Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(df["a"].scatter([0, 1], [999, 888])).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a b 0 999 4 1 888 5 2 3 6 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 999 ┆ 4 │ │ 888 ┆ 5 │ │ 3 ┆ 6 │ └─────┴─────┘ )rBr&scatter_extract_native)rindicesvaluess rrVzSeries.scatters9|**  " " * *7D4H4H4P Q  r c.|jjS)aGet the shape of the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> tuple[int]: ... s = nw.from_native(s_native, series_only=True) ... return s.shape We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) (3,) >>> my_library_agnostic_function(s_pl) (3,) )r&shaper/s rr[z Series.shape/4%%+++r cBddlm}t||r |jS|S)Nr)r)narwhals.seriesrr?r&)rargrs rrWzSeries._extract_nativeKs * c6 "(( ( r c<|j||jS)Nr*) __class__r$rr)s rrBzSeries._from_compliant_seriesRs"~~ ++  r c||g|i|S)aPipe function call. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s_pd = pd.Series([1, 2, 3, 4]) >>> s_pl = pl.Series([1, 2, 3, 4]) Lets define a function to pipe into >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.pipe(lambda x: x + 2).to_native() Now apply it to the series >>> my_library_agnostic_function(s_pd) 0 3 1 4 2 5 3 6 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ 3 4 5 6 ] r7)rfunctionargskwargss rpipez Series.pipeXsH.t.v..r c^d}t|}dd|zzdzd|dzdzdzd|zzd zS) Nz) Narwhals Series u┌u─u┐ |z| z,| Use `.to_native()` to see native output | u└u┘)len)rheaderlengths r__repr__zSeries.__repr__~sj<V fn  &o >  >    fn    r c,t|jSr6rkr&r/s r__len__zSeries.__len__s4))**r c,t|jS)adReturn the number of elements in the Series. Null values count towards the total. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl >>> data = [1, 2, None] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) Let's define a dataframe-agnostic function that computes the len of the series: >>> def my_library_agnostic_function(s_native: IntoSeries) -> int: ... s = nw.from_native(s_native, series_only=True) ... return s.len() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 3 >>> my_library_agnostic_function(s_pl) 3 rpr/s rrkz Series.lens64))**r c.|jjS)a Get the data type of the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> nw.dtypes.DType: ... s = nw.from_native(s_native, series_only=True) ... return s.dtype We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) Int64 >>> my_library_agnostic_function(s_pl) Int64 )r&r2r/s rr2z Series.dtyper\r c.|jjS)a Get the name of the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="foo") >>> s_pl = pl.Series("foo", s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> str: ... s = nw.from_native(s_native, series_only=True) ... return s.name We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 'foo' >>> my_library_agnostic_function(s_pl) 'foo' )r&namer/s rruz Series.names4%%***r TFcomspan half_lifealphaadjust min_periods ignore_nullsc d|j|jj|||||||S)a Compute exponentially-weighted moving average. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. Arguments: com: Specify decay in terms of center of mass, $\gamma$, with
$\alpha = \frac{1}{1+\gamma}\forall\gamma\geq0$ span: Specify decay in terms of span, $\theta$, with
$\alpha = \frac{2}{\theta + 1} \forall \theta \geq 1$ half_life: Specify decay in terms of half-life, $\tau$, with
$\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \forall \tau > 0$ alpha: Specify smoothing factor alpha directly, $0 < \alpha \leq 1$. adjust: Divide by decaying adjustment factor in beginning periods to account for imbalance in relative weightings - When `adjust=True` (the default) the EW function is calculated using weights $w_i = (1 - \alpha)^i$ - When `adjust=False` the EW function is calculated recursively by $$ y_0=x_0 $$ $$ y_t = (1 - \alpha)y_{t - 1} + \alpha x_t $$ min_periods: Minimum number of observations in window required to have a value (otherwise result is null). ignore_nulls: Ignore missing values when calculating weights. - When `ignore_nulls=False` (default), weights are based on absolute positions. For example, the weights of $x_0$ and $x_2$ used in calculating the final weighted average of $[x_0, None, x_2]$ are $(1-\alpha)^2$ and $1$ if `adjust=True`, and $(1-\alpha)^2$ and $\alpha$ if `adjust=False`. - When `ignore_nulls=True`, weights are based on relative positions. For example, the weights of $x_0$ and $x_2$ used in calculating the final weighted average of $[x_0, None, x_2]$ are $1-\alpha$ and $1$ if `adjust=True`, and $1-\alpha$ and $\alpha$ if `adjust=False`. Returns: Series Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [1, 2, 3] >>> s_pd = pd.Series(name="a", data=data) >>> s_pl = pl.Series(name="a", values=data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.ewm_mean(com=1, ignore_nulls=False).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1.000000 1 1.666667 2 2.428571 Name: a, dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: 'a' [f64] [ 1.0 1.666667 2.428571 ] rw)rBr&ewm_mean)rrxryrzr{r|r}r~s rrzSeries.ewm_meansFh**  " " + +#') ,   r clt||j|jj|S)aHCast between data types. Arguments: dtype: Data type that the object will be cast into. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [True, False, True] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cast(nw.Int64).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 0 2 1 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 1 0 1 ] )rrBr&cast)rr2s rrz Series.castDs/J **4+A+A+F+Fu+MNNr cl|j|jj|jS)uConvert to dataframe. Returns: A new DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries, IntoDataFrame >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="a") >>> s_pl = pl.Series("a", s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> IntoDataFrame: ... s = nw.from_native(s_native, series_only=True) ... return s.to_frame().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) a 0 1 1 2 2 3 >>> my_library_agnostic_function(s_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ ra)rr&to_framer$r/s rrzSeries.to_framels4P  " " + + -++  r c6|jjS)aCConvert to list. Notes: This function converts to Python scalars. It's typically more efficient to keep your data in the format native to your original dataframe, so we recommend only calling this when you absolutely need to. Returns: A list of Python objects. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="a") >>> s_pl = pl.Series("a", s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.to_list() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) [1, 2, 3] >>> my_library_agnostic_function(s_pl) [1, 2, 3] )r&to_listr/s rrzSeries.to_listsD%%--//r c6|jjS)aReduce this Series to the mean value. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.mean() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.float64(2.0) >>> my_library_agnostic_function(s_pl) 2.0 )r&meanr/s rrz Series.means2%%**,,r c6|jjS)aWReduce this Series to the median value. Notes: Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [5, 3, 8] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) >>> s_pa = pa.chunked_array([s]) Let's define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.median() We can then pass any supported library such as pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(s_pd) np.float64(5.0) >>> my_library_agnostic_function(s_pl) 5.0 >>> my_library_agnostic_function(s_pa) 5.0 )r&medianr/s rrz Series.medians@%%,,..r c6|jjS)aCalculate the sample skewness of the Series. Returns: The sample skewness of the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> s = [1, 1, 2, 10, 100] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) >>> s_pa = pa.array(s) We define a library agnostic function: >>> @nw.narwhalify ... def func(s): ... return s.skew() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(s_pd) np.float64(1.4724267269058975) >>> func(s_pl) 1.4724267269058975 Notes: The skewness is a measure of the asymmetry of the probability distribution. A perfectly symmetric distribution has a skewness of 0. )r&skewr/s rrz Series.skewsB%%**,,r c6|jjS)aReturns the number of non-null elements in the Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.count() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.int64(3) >>> my_library_agnostic_function(s_pl) 3 )r&countr/s rrz Series.counts4%%++--r c6|jjS)a`Return whether any of the values in the Series are True. Notes: Only works on Series of data type Boolean. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [False, True, False] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.any() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.True_ >>> my_library_agnostic_function(s_pl) True )r&anyr/s rrz Series.any9s8%%))++r c6|jjS)aReturn whether all values in the Series are True. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [True, False, True] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.all() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.False_ >>> my_library_agnostic_function(s_pl) False )r&allr/s rrz Series.allWs4%%))++r c6|jjS)aGet the minimal value in this Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.min() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.int64(1) >>> my_library_agnostic_function(s_pl) 1 )r&minr/s rrz Series.mins2%%))++r c6|jjS)aGet the maximum value in this Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.max() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.int64(3) >>> my_library_agnostic_function(s_pl) 3 )r&maxr/s rrz Series.maxrr c6|jjS)aReturns the index of the minimum value. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) >>> s_pa = pa.chunked_array([s]) We define a library agnostic function: >>> def agnostic_arg_min(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.arg_min() We can then pass either any supported library such as pandas, Polars, or PyArrow: >>> agnostic_arg_min(s_pd) np.int64(0) >>> agnostic_arg_min(s_pl) 0 >>> agnostic_arg_min(s_pa) 0 )r&arg_minr/s rrzSeries.arg_min<%%--//r c6|jjS)aReturns the index of the maximum value. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) >>> s_pa = pa.chunked_array([s]) We define a library agnostic function: >>> def agnostic_arg_max(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.arg_max() We can then pass either any supported library such as pandas, Polars, or PyArrow: >>> agnostic_arg_max(s_pd) np.int64(2) >>> agnostic_arg_max(s_pl) 2 >>> agnostic_arg_max(s_pa) 2 )r&arg_maxr/s rrzSeries.arg_maxrr c6|jjS)aReduce this Series to the sum value. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.sum() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.int64(6) >>> my_library_agnostic_function(s_pl) 6 )r&sumr/s rrz Series.sumrr ddofc:|jj|S)uGet the standard deviation of this Series. Arguments: ddof: “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.std() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.float64(1.0) >>> my_library_agnostic_function(s_pl) 1.0 r)r&std)rrs rrz Series.stds:%%))t)44r cZ|j|jj||S)af Clip values in the Series. Arguments: lower_bound: Lower bound value. upper_bound: Upper bound value. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> >>> s = [1, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def clip_lower(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.clip(2).to_native() We can then pass either pandas or Polars to `clip_lower`: >>> clip_lower(s_pd) 0 2 1 2 2 3 dtype: int64 >>> clip_lower(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 2 2 3 ] We define another library agnostic function: >>> def clip_upper(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.clip(upper_bound=2).to_native() We can then pass either pandas or Polars to `clip_upper`: >>> clip_upper(s_pd) 0 1 1 2 2 2 dtype: int64 >>> clip_upper(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 1 2 2 ] We can have both at the same time >>> s = [-1, 1, -3, 3, -5, 5] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.clip(-1, 3).to_native() We can pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 -1 1 1 2 -1 3 3 4 -1 5 3 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (6,) Series: '' [i64] [ -1 1 -1 3 -1 3 ] ) lower_bound upper_bound)rBr&clip)rrrs rrz Series.clip#s1B**  " " ' 'K[ ' Y  r ct|j|jj|j|S)a\Check if the elements of this Series are in the other sequence. Arguments: other: Sequence of primitive type. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s_pd = pd.Series([1, 2, 3]) >>> s_pl = pl.Series([1, 2, 3]) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_in([3, 2, 8]).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 False 1 True 2 True dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [bool] [ false true true ] )rBr&is_inrWrothers rrz Series.is_ins7H**  " " ( ()=)=e)D E  r cT|j|jjS)aFind elements where boolean Series is True. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [1, None, None, 2] >>> s_pd = pd.Series(data, name="a") >>> s_pl = pl.Series("a", data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_null().arg_true().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 1 1 2 2 Name: a, dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [u32] [ 1 2 ] )rBr&arg_truer/s rrzSeries.arg_trues%@**4+A+A+J+J+LMMr cT|j|jjS)aDrop all null values. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import pandas as pd >>> import polars as pl >>> import numpy as np >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s_pd = pd.Series([2, 4, None, 3, 5]) >>> s_pl = pl.Series("a", [2, 4, None, 3, 5]) Now define a dataframe-agnostic function with a `column` argument for the column to evaluate : >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.drop_nulls().to_native() Then we can pass either Series (polars or pandas) to `func`: >>> my_library_agnostic_function(s_pd) 0 2.0 1 4.0 3 3.0 4 5.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: 'a' [i64] [ 2 4 3 5 ] )rBr& drop_nullsr/s rrzSeries.drop_nullss%P**4+A+A+L+L+NOOr cT|j|jjS)aCalculate the absolute value of each element. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [2, -4, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.abs().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2 1 4 2 3 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 2 4 3 ] )rBr&absr/s rrz Series.abss%D**4+A+A+E+E+GHHr reversecX|j|jj|S)a)Calculate the cumulative sum. Arguments: reverse: reverse the operation Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [2, 4, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cum_sum().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2 1 6 2 9 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 2 6 9 ] r)rBr&cum_sumrrs rrzSeries.cum_sum s/J**  " " * *7 * ;  r maintain_ordercX|j|jj|S)aReturns unique values of the series. Arguments: maintain_order: Keep the same order as the original series. This may be more expensive to compute. Settings this to `True` blocks the possibility to run on the streaming engine for Polars. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [2, 4, 4, 6] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.unique(maintain_order=True).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2 1 4 2 6 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 2 4 6 ] r)rBr&unique)rrs rrz Series.uniqueIs/N**  " " ) ) ) H  r cT|j|jjS)aCalculate the difference with the previous element, for each element. Notes: pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use `fill_null` and `cast`. For example, to calculate the diff and fill missing values with `0` in a Int64 column, you could do: s.diff().fill_null(0).cast(nw.Int64) Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [2, 4, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.diff().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 NaN 1 2.0 2 -1.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ null 2 -1 ] )rBr&diffr/s rrz Series.diffts%V**4+A+A+F+F+HIIr cV|j|jj|S)a7Shift values by `n` positions. Arguments: n: Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead. Notes: pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use `fill_null` and `cast`. For example, to shift and fill missing values with `0` in a Int64 column, you could do: s.shift(1).fill_null(0).cast(nw.Int64) Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [2, 4, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.shift(1).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 NaN 1 2.0 2 4.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ null 2 4 ] )rBr&shiftrns rrz Series.shifts'^**4+A+A+G+G+JKKr )fractionwith_replacementseedc^|j|jj||||S)azSample randomly from this Series. Arguments: n: Number of items to return. Cannot be used with fraction. fraction: Fraction of items to return. Cannot be used with n. with_replacement: Allow values to be sampled more than once. seed: Seed for the random number generator. If set to None (default), a random seed is generated for each sample operation. Notes: The `sample` method returns a Series with a specified number of randomly selected items chosen from this Series. The results are not consistent across libraries. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 2, 3, 4]) >>> s_pl = pl.Series([1, 2, 3, 4]) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.sample(fraction=1.0, with_replacement=True).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +SKIP a 2 3 1 2 3 4 3 4 >>> my_library_agnostic_function(s_pl) # doctest: +SKIP shape: (4,) Series: '' [i64] [ 1 4 3 4 ] )rrrr)rBr&sample)rrrrrs rrz Series.samples<n**  " " ) )h9IPT *   r cX|j|jj|S)aTRename the Series. Notes: This method is very cheap, but does not guarantee that data will be copied. For example: ```python s1: nw.Series s2 = s1.alias("foo") arr = s2.to_numpy() arr[0] = 999 ``` may (depending on the backend, and on the version) result in `s1`'s data being modified. We recommend: - if you need to alias an object and don't need the original one around any more, just use `alias` without worrying about it. - if you were expecting `alias` to copy data, then explicily call `.clone` before calling `alias`. Arguments: name: The new name. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="foo") >>> s_pl = pl.Series("foo", s) >>> s_pa = pa.chunked_array([s]) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.alias("bar").to_native() We can then pass any supported library such as pandas, Polars, or PyArrow: >>> my_library_agnostic_function(s_pd) 0 1 1 2 2 3 Name: bar, dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: 'bar' [i64] [ 1 2 3 ] >>> my_library_agnostic_function(s_pa) # doctest: +ELLIPSIS [ [ 1, 2, 3 ] ] ru)rBr&aliasrrus rrz Series.aliass*F**4+A+A+G+GT+G+RSSr c&|j|S)aRename the Series. Alias for `Series.alias()`. Notes: This method is very cheap, but does not guarantee that data will be copied. For example: ```python s1: nw.Series s2 = s1.rename("foo") arr = s2.to_numpy() arr[0] = 999 ``` may (depending on the backend, and on the version) result in `s1`'s data being modified. We recommend: - if you need to rename an object and don't need the original one around any more, just use `rename` without worrying about it. - if you were expecting `rename` to copy data, then explicily call `.clone` before calling `rename`. Arguments: name: The new name. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="foo") >>> s_pl = pl.Series("foo", s) >>> s_pa = pa.chunked_array([s]) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.rename("bar").to_native() We can then pass any supported library such as pandas, Polars, or PyArrow: >>> my_library_agnostic_function(s_pd) 0 1 1 2 2 3 Name: bar, dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: 'bar' [i64] [ 1 2 3 ] >>> my_library_agnostic_function(s_pa) # doctest: +ELLIPSIS [ [ 1, 2, 3 ] ] r)rrs rrenamez Series.renameTsJzztz$$r  return_dtypec|Ot|ts d}t|t|j }t|j }|j |jj|||S)aReplace all values by different values. This function must replace all non-null input values (else it raises an error). Arguments: old: Sequence of values to replace. It also accepts a mapping of values to their replacement as syntactic sugar for `replace_all(old=list(mapping.keys()), new=list(mapping.values()))`. new: Sequence of values to replace by. Length must match the length of `old`. return_dtype: The data type of the resulting expression. If set to `None` (default), the data type is determined automatically based on the other inputs. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> df_pd = pd.DataFrame({"a": [3, 0, 1, 2]}) >>> df_pl = pl.DataFrame({"a": [3, 0, 1, 2]}) >>> df_pa = pa.table({"a": [3, 0, 1, 2]}) Let's define dataframe-agnostic functions: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.replace_strict( ... [0, 1, 2, 3], ["zero", "one", "two", "three"], return_dtype=nw.String ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd["a"]) 0 three 1 zero 2 one 3 two Name: a, dtype: object >>> my_library_agnostic_function(df_pl["a"]) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: 'a' [str] [ "three" "zero" "one" "two" ] >>> my_library_agnostic_function(df_pa["a"]) [ [ "three", "zero", "one", "two" ] ] zB`new` argument is required if `old` argument is not a Mapping typer) r?r TypeErrorlistrYkeysrBr&replace_strict)roldnewrr+s rrzSeries.replace_strictsqD ;c7+Zn$szz|$Csxxz"C**  " " 1 1#s 1 V  r  descending nulls_lastcZ|j|jj||S)aSort this Series. Place null values first. Arguments: descending: Sort in descending order. nulls_last: Place null values last instead of first. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [5, None, 1, 2] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define library agnostic functions: >>> def agnostic_sort(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.sort().to_native() >>> def agnostic_sort_descending(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.sort(descending=True).to_native() We can then pass either pandas or Polars to `agnostic_sort`: >>> agnostic_sort(s_pd) 1 NaN 2 1.0 3 2.0 0 5.0 dtype: float64 >>> agnostic_sort(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ null 1 2 5 ] >>> agnostic_sort_descending(s_pd) 1 NaN 0 5.0 3 2.0 2 1.0 dtype: float64 >>> agnostic_sort_descending(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ null 5 2 1 ] r)rBr&sort)rrrs rrz Series.sorts1v**  " " ' ':* ' U  r cT|j|jjS)aReturns a boolean Series indicating which values are null. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, None] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_null().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 False 1 False 2 True dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [bool] [ false false true ] )rBr&is_nullr/s rrzSeries.is_null(s%L**4+A+A+I+I+KLLr c|| d}t||| d}t|||dvrd|}t||j|jj|||S)aFill null values using the specified value. Arguments: value: Value used to fill null values. strategy: Strategy used to fill null values. limit: Number of consecutive null values to fill when using the 'forward' or 'backward' strategy. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [1, 2, None] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.fill_null(5).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1.0 1 2.0 2 5.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 1 2 5 ] Using a strategy: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.fill_null(strategy="forward", limit=1).to_native() >>> my_library_agnostic_function(s_pd) 0 1.0 1 2.0 2 2.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 1 2 2 ] z*cannot specify both `value` and `strategy`z0must specify either a fill `value` or `strategy`>forwardbackwardzstrategy not supported: )valuestrategylimit) ValueErrorrBr& fill_null)rrrrr+s rrzSeries.fill_nullPsN  !5>CS/ ! =X-DCS/ !  H4K$K,XJ7CS/ !**  " " , ,58SX , Y  r c\|j|jj|||S)aGet a boolean mask of the values that are between the given lower/upper bounds. Arguments: lower_bound: Lower bound value. upper_bound: Upper bound value. closed: Define which sides of the interval are closed (inclusive). Notes: If the value of the `lower_bound` is greater than that of the `upper_bound`, then the values will be False, as no value can satisfy the condition. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s_pd = pd.Series([1, 2, 3, 4, 5]) >>> s_pl = pl.Series([1, 2, 3, 4, 5]) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_between(2, 4, "right").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 False 1 False 2 True 3 True 4 False dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [bool] [ false false true true false ] )closed)rBr& is_between)rrrrs rrzSeries.is_betweens3d**  " " - -k;v - V  r c6|jjS)aCount the number of unique values. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 2, 3] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.n_unique() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 3 >>> my_library_agnostic_function(s_pl) 3 )r&n_uniquer/s rrzSeries.n_uniques2%%..00r c6|jjS)aHConvert to numpy. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> import numpy as np >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="a") >>> s_pl = pl.Series("a", s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> np.ndarray: ... s = nw.from_native(s_native, series_only=True) ... return s.to_numpy() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) array([1, 2, 3]...) >>> my_library_agnostic_function(s_pl) array([1, 2, 3]...) )r&to_numpyr/s rrzSeries.to_numpys4%%..00r c6|jjS)aConvert to pandas. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> s = [1, 2, 3] >>> s_pd = pd.Series(s, name="a") >>> s_pl = pl.Series("a", s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> pd.Series: ... s = nw.from_native(s_native, series_only=True) ... return s.to_pandas() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 2 2 3 Name: a, dtype: int64 >>> my_library_agnostic_function(s_pl) 0 1 1 2 2 3 Name: a, dtype: int64 )r& to_pandasr/s rrzSeries.to_pandass>%%//11r ct|j|jj|j|Sr6)rBr&__add__rWrs rrzSeries.__add__24**  " " * *4+?+?+F G  r ct|j|jj|j|Sr6)rBr&__radd__rWrs rrzSeries.__radd__74**  " " + +D,@,@,G H  r ct|j|jj|j|Sr6)rBr&__sub__rWrs rrzSeries.__sub__<rr ct|j|jj|j|Sr6)rBr&__rsub__rWrs rrzSeries.__rsub__Arr ct|j|jj|j|Sr6)rBr&__mul__rWrs rrzSeries.__mul__Frr ct|j|jj|j|Sr6)rBr&__rmul__rWrs rrzSeries.__rmul__Krr ct|j|jj|j|Sr6)rBr& __truediv__rWrs rrzSeries.__truediv__Ps4**  " " . .t/C/CE/J K  r ct|j|jj|j|Sr6)rBr& __rtruediv__rWrs rrzSeries.__rtruediv__U4**  " " / /0D0DU0K L  r ct|j|jj|j|Sr6)rBr& __floordiv__rWrs rrzSeries.__floordiv__Zrr ct|j|jj|j|Sr6)rBr& __rfloordiv__rWrs rrzSeries.__rfloordiv___s4**  " " 0 01E1Ee1L M  r ct|j|jj|j|Sr6)rBr&__pow__rWrs rrzSeries.__pow__drr ct|j|jj|j|Sr6)rBr&__rpow__rWrs rrzSeries.__rpow__irr ct|j|jj|j|Sr6)rBr&__mod__rWrs rrzSeries.__mod__nrr ct|j|jj|j|Sr6)rBr&__rmod__rWrs rr zSeries.__rmod__srr ct|j|jj|j|Sr6)rBr&__eq__rWrs rr z Series.__eq__x4**  " " ) )$*>*>u*E F  r ct|j|jj|j|Sr6)rBr&__ne__rWrs rrz Series.__ne__}r r ct|j|jj|j|Sr6)rBr&__gt__rWrs rrz Series.__gt__r r ct|j|jj|j|Sr6)rBr&__ge__rWrs rrz Series.__ge__r r ct|j|jj|j|Sr6)rBr&__lt__rWrs rrz Series.__lt__r r ct|j|jj|j|Sr6)rBr&__le__rWrs rrz Series.__le__r r ct|j|jj|j|Sr6)rBr&__and__rWrs rrzSeries.__and__rr ct|j|jj|j|Sr6)rBr&__rand__rWrs rrzSeries.__rand__rr ct|j|jj|j|Sr6)rBr&__or__rWrs rrz Series.__or__r r ct|j|jj|j|Sr6)rBr&__ror__rWrs rrzSeries.__ror__rr cT|j|jjSr6)rBr& __invert__r/s rr!zSeries.__invert__s"**4+A+A+L+L+NOOr ct|j|jj|j|S)aFilter elements in the Series based on a condition. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> s = [4, 10, 15, 34, 50] >>> s_pd = pd.Series(s) >>> s_pl = pl.Series(s) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.filter(s > 10).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 2 15 3 34 4 50 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 15 34 50 ] )rBr&filterrWrs rr#z Series.filters7D**  " " ) )$*>*>u*E F  r cT|j|jjS)aGet a mask of all duplicated rows in the Series. Returns: A new Series. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 2, 3, 1]) >>> s_pl = pl.Series([1, 2, 3, 1]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_duplicated().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 True 1 False 2 False 3 True dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ true false false true ] )rBr& is_duplicatedr/s rr%zSeries.is_duplicateds%L**4+A+A+O+O+QRRr c6|jjS)a*Check if the series is empty. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl Let's define a dataframe-agnostic function that filters rows in which "foo" values are greater than 10, and then checks if the result is empty or not: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.filter(s > 10).is_empty() We can then pass either pandas or Polars to `func`: >>> s_pd = pd.Series([1, 2, 3]) >>> s_pl = pl.Series([1, 2, 3]) >>> my_library_agnostic_function(s_pd), my_library_agnostic_function(s_pl) (True, True) >>> s_pd = pd.Series([100, 2, 3]) >>> s_pl = pl.Series([100, 2, 3]) >>> my_library_agnostic_function(s_pd), my_library_agnostic_function(s_pl) (False, False) )r&is_emptyr/s rr'zSeries.is_emptys8%%..00r cT|j|jjS)aaGet a mask of all unique rows in the Series. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 2, 3, 1]) >>> s_pl = pl.Series([1, 2, 3, 1]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_unique().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 False 1 True 2 True 3 False dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ false true true false ] )rBr& is_uniquer/s rr)zSeries.is_unique s%H**4+A+A+K+K+MNNr c6|jjS)aCreate a new Series that shows the null counts per column. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, None, 3]) >>> s_pl = pl.Series([1, None, None]) Let's define a dataframe-agnostic function that returns the null count of the series: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return s.null_count() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) np.int64(1) >>> my_library_agnostic_function(s_pl) 2 )r& null_countr/s rr+zSeries.null_countA s8%%0022r cT|j|jjS)aReturn a boolean mask indicating the first occurrence of each distinct value. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 1, 2, 3, 2]) >>> s_pl = pl.Series([1, 1, 2, 3, 2]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_first_distinct().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 True 1 False 2 True 3 True 4 False dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [bool] [ true false true true false ] )rBr&is_first_distinctr/s rr-zSeries.is_first_distinct_ s%L**4+A+A+S+S+UVVr cT|j|jjS)aReturn a boolean mask indicating the last occurrence of each distinct value. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 1, 2, 3, 2]) >>> s_pl = pl.Series([1, 1, 2, 3, 2]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_last_distinct().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 False 1 True 2 False 3 True 4 True dtype: bool >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [bool] [ false true false true true ] )rBr&is_last_distinctr/s rr/zSeries.is_last_distinct s%L**4+A+A+R+R+TUUr rc:|jj|S)aCheck if the Series is sorted. Arguments: descending: Check if the Series is sorted in descending order. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl >>> unsorted_data = [1, 3, 2] >>> sorted_data = [3, 2, 1] Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function( ... s_native: IntoSeries, descending: bool = False ... ): ... s = nw.from_native(s_native, series_only=True) ... return s.is_sorted(descending=descending) We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(pl.Series(unsorted_data)) False >>> my_library_agnostic_function(pl.Series(sorted_data), descending=True) True >>> my_library_agnostic_function(pd.Series(unsorted_data)) False >>> my_library_agnostic_function(pd.Series(sorted_data), descending=True) True r0)r& is_sorted)rrs rr2zSeries.is_sorted sB%%//:/FFr rparallelru normalizecv|j|jj|||||jS)uCount the occurrences of unique values. Arguments: sort: Sort the output by count in descending order. If set to False (default), the order of the output is random. parallel: Execute the computation in parallel. Used for Polars only. name: Give the resulting count column a specific name; if `normalize` is True defaults to "proportion", otherwise defaults to "count". normalize: If true gives relative frequencies of the unique values Returns: A new DataFrame. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries, IntoDataFrame >>> import pandas as pd >>> import polars as pl >>> s_pd = pd.Series([1, 1, 2, 3, 2], name="s") >>> s_pl = pl.Series(values=[1, 1, 2, 3, 2], name="s") Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries) -> IntoDataFrame: ... s = nw.from_native(s_native, series_only=True) ... return s.value_counts(sort=True).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE s count 0 1 2 1 2 2 2 3 1 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 2) ┌─────┬───────┐ │ s ┆ count │ │ --- ┆ --- │ │ i64 ┆ u32 │ ╞═════╪═══════╡ │ 1 ┆ 2 │ │ 2 ┆ 2 │ │ 3 ┆ 1 │ └─────┴───────┘ r3ra)rr& value_countsr$)rrr4rur5s rr7zSeries.value_counts sFn  " " / /H49 0 ++   r c<|jj||S)aGet quantile value of the series. Note: pandas and Polars may have implementation differences for a given interpolation method. Arguments: quantile: Quantile between 0.0 and 1.0. interpolation: Interpolation method. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl >>> data = list(range(50)) >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeries): ... s = nw.from_native(s_native, series_only=True) ... return [ ... s.quantile(quantile=q, interpolation="nearest") ... for q in (0.1, 0.25, 0.5, 0.75, 0.9) ... ] We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) [np.int64(5), np.int64(12), np.int64(24), np.int64(37), np.int64(44)] >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE [5.0, 12.0, 25.0, 37.0, 44.0] )quantile interpolation)r&r9)rr9r:s rr9zSeries.quantile s(P%%..]/  r c|j|jj|j||j|S)aPTake values from self or other based on the given mask. Where mask evaluates true, take values from self. Where mask evaluates false, take values from other. Arguments: mask: Boolean Series other: Series of same type. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> s1_pl = pl.Series([1, 2, 3, 4, 5]) >>> s2_pl = pl.Series([5, 4, 3, 2, 1]) >>> mask_pl = pl.Series([True, False, True, False, True]) >>> s1_pd = pd.Series([1, 2, 3, 4, 5]) >>> s2_pd = pd.Series([5, 4, 3, 2, 1]) >>> mask_pd = pd.Series([True, False, True, False, True]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function( ... s1_native: IntoSeriesT, mask_native: IntoSeriesT, s2_native: IntoSeriesT ... ) -> IntoSeriesT: ... s1 = nw.from_native(s1_native, series_only=True) ... mask = nw.from_native(mask_native, series_only=True) ... s2 = nw.from_native(s2_native, series_only=True) ... return s1.zip_with(mask, s2).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function( ... s1_pl, mask_pl, s2_pl ... ) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [i64] [ 1 4 3 2 5 ] >>> my_library_agnostic_function(s1_pd, mask_pd, s2_pd) 0 1 1 4 2 3 3 2 4 5 dtype: int64 )rBr&zip_withrW)rmaskrs rr<zSeries.zip_with< sGl**  " " + +$$T*D,@,@,G   r c:|jj|S)aReturn the Series as a scalar, or return the element at the given index. If no index is provided, this is equivalent to `s[0]`, with a check that the shape is (1,). With an index, this is equivalent to `s[index]`. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pandas as pd >>> import polars as pl Let's define a dataframe-agnostic function that returns item at given index >>> def my_library_agnostic_function(s_native: IntoSeries, index=None): ... s = nw.from_native(s_native, series_only=True) ... return s.item(index) We can then pass either pandas or Polars to `func`: >>> ( ... my_library_agnostic_function(pl.Series("a", [1]), None), ... my_library_agnostic_function(pd.Series([1]), None), ... ) (1, np.int64(1)) >>> ( ... my_library_agnostic_function(pl.Series("a", [9, 8, 7]), -1), ... my_library_agnostic_function(pl.Series([9, 8, 7]), -2), ... ) (7, 8) )index)r&item)rr?s rr@z Series.itemx s@%%***77r cV|j|jj|S)arGet the first `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> data = list(range(10)) >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) Let's define a dataframe-agnostic function that returns the first 3 rows: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.head(3).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 0 1 1 2 2 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 0 1 2 ] )rBr&headrs rrBz Series.head s'L**4+A+A+F+Fq+IJJr cV|j|jj|S)aoGet the last `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> data = list(range(10)) >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) Let's define a dataframe-agnostic function that returns the last 3 rows: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.tail(3).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 7 7 8 8 9 9 dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 7 8 9 ] )rBr&tailrs rrDz Series.tail s'J**4+A+A+F+Fq+IJJr cV|j|jj|S)aQRound underlying floating point data by `decimals` digits. Arguments: decimals: Number of decimals to round by. Notes: For values exactly halfway between rounded decimal values pandas behaves differently than Polars and Arrow. pandas rounds to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5 round to 2.0, 3.5 and 4.5 to 4.0, etc..). Polars and Arrow round away from 0 (e.g. -0.5 to -1.0, 0.5 to 1.0, 1.5 to 2.0, 2.5 to 3.0, etc..). Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> data = [1.12345, 2.56789, 3.901234] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) Let's define a dataframe-agnostic function that rounds to the first decimal: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.round(1).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 1.1 1 2.6 2 3.9 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [f64] [ 1.1 2.6 3.9 ] )rBr&round)rdecimalss rrFz Series.round s'\**4+A+A+G+G+QRRr _ separator drop_firstcr|j|jj|||jS)u Get dummy/indicator variables. Arguments: separator: Separator/delimiter used when generating column names. drop_first: Remove the first category from the variable being encoded. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries, IntoDataFrame >>> import pandas as pd >>> import polars as pl >>> data = [1, 2, 3] >>> s_pd = pd.Series(data, name="a") >>> s_pl = pl.Series("a", data) Let's define a dataframe-agnostic function that rounds to the first decimal: >>> def my_library_agnostic_function( ... s_native: IntoSeries, drop_first: bool = False ... ) -> IntoDataFrame: ... s = nw.from_native(s_native, series_only=True) ... return s.to_dummies(drop_first=drop_first).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) a_1 a_2 a_3 0 1 0 0 1 0 1 0 2 0 0 1 >>> my_library_agnostic_function(s_pd, drop_first=True) a_2 a_3 0 0 0 1 1 0 2 0 1 >>> my_library_agnostic_function(s_pl) shape: (3, 3) ┌─────┬─────┬─────┐ │ a_1 ┆ a_2 ┆ a_3 │ │ --- ┆ --- ┆ --- │ │ i8 ┆ i8 ┆ i8 │ ╞═════╪═════╪═════╡ │ 1 ┆ 0 ┆ 0 │ │ 0 ┆ 1 ┆ 0 │ │ 0 ┆ 0 ┆ 1 │ └─────┴─────┴─────┘ >>> my_library_agnostic_function(s_pl, drop_first=True) shape: (3, 2) ┌─────┬─────┐ │ a_2 ┆ a_3 │ │ --- ┆ --- │ │ i8 ┆ i8 │ ╞═════╪═════╡ │ 0 ┆ 0 │ │ 1 ┆ 0 │ │ 0 ┆ 1 │ └─────┴─────┘ rIra)rr& to_dummiesr$)rrJrKs rrMzSeries.to_dummies s;F  " " - - j - Y++  r cZ|j|jj||S)aTake every nth value in the Series and return as new Series. Arguments: n: Gather every *n*-th row. offset: Starting index. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> data = [1, 2, 3, 4] >>> s_pd = pd.Series(name="a", data=data) >>> s_pl = pl.Series(name="a", values=data) Let's define a dataframe-agnostic function in which gather every 2 rows, starting from a offset of 1: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.gather_every(n=2, offset=1).to_native() >>> my_library_agnostic_function(s_pd) 1 2 3 4 Name: a, dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 2 4 ] )roffset)rBr& gather_every)rrrOs rrPzSeries.gather_everya s1H**  " " / /!F / C  r c6|jjS)awConvert to arrow. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeries >>> import pyarrow as pa >>> import pandas as pd >>> import polars as pl >>> data = [1, 2, 3, 4] >>> s_pd = pd.Series(name="a", data=data) >>> s_pl = pl.Series(name="a", values=data) Let's define a dataframe-agnostic function that converts to arrow: >>> def my_library_agnostic_function(s_native: IntoSeries) -> pa.Array: ... s = nw.from_native(s_native, series_only=True) ... return s.to_arrow() >>> my_library_agnostic_function(s_pd) # doctest:+NORMALIZE_WHITESPACE [ 1, 2, 3, 4 ] >>> my_library_agnostic_function(s_pl) # doctest:+NORMALIZE_WHITESPACE [ 1, 2, 3, 4 ] )r&rNr/s rrNzSeries.to_arrow sJ%%..00r cT|j|jjS)a.Compute the most occurring value(s). Can return multiple values. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [1, 1, 2, 2, 3] >>> s_pd = pd.Series(name="a", data=data) >>> s_pl = pl.Series(name="a", values=data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.mode().sort().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 2 Name: a, dtype: int64 >>> my_library_agnostic_function(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 1 2 ] )rBr&moder/s rrSz Series.mode s%H**4+A+A+F+F+HIIr cT|j|jjS)a+Returns a boolean Series indicating which values are finite. Warning: Different backend handle null values differently. `is_finite` will return False for NaN and Null's in the Dask and pandas non-nullable backend, while for Polars, PyArrow and pandas nullable backends null values are kept as such. Returns: Expression of `Boolean` data type. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [float("nan"), float("inf"), 2.0, None] We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.is_finite().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.Series(data)) 0 False 1 False 2 True 3 False dtype: bool >>> my_library_agnostic_function( ... pl.Series(data) ... ) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ false false true null ] >>> my_library_agnostic_function(pa.chunked_array([data])) # doctest: +ELLIPSIS [ [ false, false, true, null ] ] )rBr& is_finiter/s rrUzSeries.is_finite s%r**4+A+A+K+K+MNNr cX|j|jj|S)aReturn the cumulative count of the non-null values in the series. Arguments: reverse: reverse the operation Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = ["x", "k", None, "d"] We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cum_count(reverse=True).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.Series(data)) 0 3 1 2 2 1 3 1 dtype: int64 >>> my_library_agnostic_function(pl.Series(data)) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [u32] [ 3 2 1 1 ] >>> my_library_agnostic_function(pa.chunked_array([data])) # doctest:+ELLIPSIS [ [ 3, 2, 1, 1 ] ] r)rBr& cum_countrs rrWzSeries.cum_count s/b**  " " , ,W , =  r cX|j|jj|S)aReturn the cumulative min of the non-null values in the series. Arguments: reverse: reverse the operation Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [3, 1, None, 2] We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cum_min().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.Series(data)) 0 3.0 1 1.0 2 NaN 3 1.0 dtype: float64 >>> my_library_agnostic_function(pl.Series(data)) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ 3 1 null 1 ] >>> my_library_agnostic_function(pa.chunked_array([data])) # doctest:+ELLIPSIS [ [ 3, 1, null, 1 ] ] r)rBr&cum_minrs rrYzSeries.cum_minF /b**  " " * *7 * ;  r cX|j|jj|S)aReturn the cumulative max of the non-null values in the series. Arguments: reverse: reverse the operation Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [1, 3, None, 2] We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cum_max().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.Series(data)) 0 1.0 1 3.0 2 NaN 3 3.0 dtype: float64 >>> my_library_agnostic_function(pl.Series(data)) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ 1 3 null 3 ] >>> my_library_agnostic_function(pa.chunked_array([data])) # doctest:+ELLIPSIS [ [ 1, 3, null, 3 ] ] r)rBr&cum_maxrs rr\zSeries.cum_max{ rZr cX|j|jj|S)aReturn the cumulative product of the non-null values in the series. Arguments: reverse: reverse the operation Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [1, 3, None, 2] We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cum_prod().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.Series(data)) 0 1.0 1 3.0 2 NaN 3 6.0 dtype: float64 >>> my_library_agnostic_function(pl.Series(data)) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [i64] [ 1 3 null 6 ] >>> my_library_agnostic_function(pa.chunked_array([data])) # doctest:+ELLIPSIS [ [ 1, 3, null, 6 ] ] r)rBr&cum_prodrs rr^zSeries.cum_prod s/b**  " " + +G + <  r )r}centerct||\}}t|dk(r|S|j|jj |||S)a Apply a rolling sum (moving sum) over the values. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. A window of length `window_size` will traverse the values. The resulting values will be aggregated to their sum. The window at a given row will include the row itself and the `window_size - 1` elements before it. Arguments: window_size: The length of the window in number of elements. It must be a strictly positive integer. min_periods: The number of values in the window that should be non-null before computing a result. If set to `None` (default), it will be set equal to `window_size`. If provided, it must be a strictly positive integer, and less than or equal to `window_size` center: Set the labels at the center of the window. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [1.0, 2.0, 3.0, 4.0] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) We define a library agnostic function: >>> def agnostic_rolling_sum(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.rolling_sum(window_size=2).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_sum(s_pd) 0 NaN 1 3.0 2 5.0 3 7.0 dtype: float64 >>> agnostic_rolling_sum(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [f64] [ null 3.0 5.0 7.0 ] >>> agnostic_rolling_sum(s_pa) # doctest:+ELLIPSIS [ [ null, 3, 5, 7 ] ]  window_sizer}rrbr}r_)rrkrBr& rolling_sumrrbr}r_s rrdzSeries.rolling_sum s`\$?#$  [ t9>K**  " " . .'' /   r ct||\}}t|dk(r|S|j|jj |||S)a Apply a rolling mean (moving mean) over the values. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. A window of length `window_size` will traverse the values. The resulting values will be aggregated to their mean. The window at a given row will include the row itself and the `window_size - 1` elements before it. Arguments: window_size: The length of the window in number of elements. It must be a strictly positive integer. min_periods: The number of values in the window that should be non-null before computing a result. If set to `None` (default), it will be set equal to `window_size`. If provided, it must be a strictly positive integer, and less than or equal to `window_size` center: Set the labels at the center of the window. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [1.0, 2.0, 3.0, 4.0] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) We define a library agnostic function: >>> def agnostic_rolling_mean(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.rolling_mean(window_size=2).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_mean(s_pd) 0 NaN 1 1.5 2 2.5 3 3.5 dtype: float64 >>> agnostic_rolling_mean(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [f64] [ null 1.5 2.5 3.5 ] >>> agnostic_rolling_mean(s_pa) # doctest:+ELLIPSIS [ [ null, 1.5, 2.5, 3.5 ] ] rarrc)rrkrBr& rolling_meanres rrgzSeries.rolling_meanB s`\$?#$  [ t9>K**  " " / /'' 0   r c#TK|jjEd{y7wr6)r&__iter__r/s rrizSeries.__iter__ s))22444s (&(c8|jj|Sr6)r& __contains__rs rrkzSeries.__contains__ s%%22599r ct|Sr6)SeriesStringNamespacer/s rstrz Series.str s $T**r ct|Sr6)SeriesDateTimeNamespacer/s rdtz Series.dt s &t,,r ct|Sr6)SeriesCatNamespacer/s rcatz Series.cat s !$''r ct|Sr6)SeriesListNamespacer/s rrz Series.list s "4((r )returnztype[DataFrame[Any]])rrr)rr*z&Literal['full', 'lazy', 'interchange']rwNone)rwr)NN)rrr2rr3z bool | Nonerw np.ndarray)rrr9r@rwr)rrr9zslice | Sequence[int]rwr)rrr9zint | slice | Sequence[int]rwz Any | Self)rrrwrr6)rGz object | Nonerwobject)rwr)rXzint | Sequence[int]rYrrwr)rwz tuple[int])r_rrwr)r)rrwr)rezCallable[[Any], Self]rfrrgrrwr)rwrn)rwr@)rrrwr)rrrx float | Noneryr{rzr{r{r{r|boolr}r@r~r|rwr)rrr2zDType | type[DType]rwr)rwDataFrame[Any])rwz list[Any])rwr)rrrwr)rr@rwr)r Any | Nonerr~rwr)rrrwr)rwr)rrrr|rwr)rr|rwr)rr@rwr) rrr int | Nonerr{rr|rrrwr)rurnrwr) rrrz!Sequence[Any] | Mapping[Any, Any]rzSequence[Any] | NonerzDType | type[DType] | Nonerwr)rr|rr|rwr)NNN)rr~rz%Literal['forward', 'backward'] | Nonerrrwr)both)rrrrrrnrwr)rwry)rwz pd.Series)rrzrwr)rrrwr)rrrwr|)rrrwr@)rrrr|rwr|) rrrr|r4r|ru str | Noner5r|rwr})r9floatr:z;Literal['nearest', 'higher', 'lower', 'midpoint', 'linear']rwr)rrr=rrrrwr)rrr?rrwr) )rrrr@rwr)r)rrrGr@rwr)rrrJrnrKr|rwr})rrrr@rOr@rwr)rrrwzpa.Array) rrrbr@r}rr_r|rwr)rrrwz Iterator[Any])rrrrrwr|)rrrwzSeriesStringNamespace[Self])rrrwzSeriesDateTimeNamespace[Self])rrrwzSeriesCatNamespace[Self])rrrwzSeriesListNamespace[Self])u__name__ __module__ __qualname____doc__propertyrr,r0r4r r:rDrFrTrVr[rWrBrhrnrqrkr2rurrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr r rrrrrrrrrr!r#r%r'r)r+r-r/r2r7r9r<r@rBrDrFrMrPrNrSrUrWrYr\r^rdrgrirkrnrqrtrr7r rrr!s & & &6 &  &664H55 HHFHP=H2%5N@ D,,6 $/L  ++:,,6++<!!"&""^ ^ ^  ^  ^  ^ ^ ^ ^  ^ @&OP+ Z"0H-6 /D!-F.8,<,8,6,60@0@,6"#5@IMc %c ;Ec c J& P ND(PT"IH05' R05) V+JZ/Lf; "&!& ; ; ;  ;  ;  ;  ; zCTJE%T%)L 48 L L .L "L 1 L  L \*/5= ~&MT!:> R R 8R  R  R jAG4 4 -04 :=4 4 l16182B                        P$ N&SP1<$OL3<&WP&VP5:!GL < < <  <  <  <  < |* * S*  * X: x 8D&KP%KN.Sb),F F "%F 9=F F P& P%1N$JL9Ov273 j053 j053 j163 r#' [ [ [  [  [  [ B#' [ [ [  [  [  [ z5:++--(())r rSeriesT)boundceZdZddZddZy)rsc||_yr6_narwhals_seriesrcs rr,zSeriesCatNamespace.__init__ &r c|jj|jjjj S)aGet unique categories from column. Examples: Let's create some series: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["apple", "mango", "mango"] >>> s_pd = pd.Series(data, dtype="category") >>> s_pl = pl.Series(data, dtype=pl.Categorical) We define a dataframe-agnostic function to get unique categories from column 'fruits': >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.cat.get_categories().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 apple 1 mango dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [str] [ "apple" "mango" ] )rrBr&rtget_categoriesr/s rrz!SeriesCatNamespace.get_categories s<F$$;;  ! ! 3 3 7 7 F F H  r Nrrr)rrwrxrrrwr)rrrr,rr7r rrsrs s '% r rsceZdZddZddZddd ddZdd ddZddd Zdd Zdd Z dddd Z dddZ dddZ dddZ d dZd dZdd!dZy )"rmc||_yr6rrcs rr,zSeriesStringNamespace.__init__ rr c|jj|jjjj S)uReturn the length of each string as the number of characters. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["foo", "Café", "345", "東京", None] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.len_chars().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 3.0 1 4.0 2 3.0 3 2.0 4 NaN dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [u32] [ 3 4 3 2 null ] )rrBr&rn len_charsr/s rrzSeriesStringNamespace.len_chars s<N$$;;  ! ! 3 3 7 7 A A C  r Frvliteralrc|jj|jjjj ||||S)aAReplace first matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. n: Number of matches to replace. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["123abc", "abc abc123"] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... s = s.str.replace("abc", "") ... return s.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 123 1 abc123 dtype: object >>> my_library_agnostic_function(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: '' [str] [ "123" " abc123" ] r)rrBr&rnreplace)rpatternrrrs rrzSeriesStringNamespace.replacesMT$$;;  ! ! 3 3 7 7 ? ?1 @   r rc|jj|jjjj |||S)a Replace all matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["123abc", "abc abc123"] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... s = s.str.replace_all("abc", "") ... return s.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 123 1 123 dtype: object >>> my_library_agnostic_function(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: '' [str] [ "123" " 123" ] r)rrBr&rn replace_all)rrrrs rrz!SeriesStringNamespace.replace_allDsKR$$;;  ! ! 3 3 7 7 C C D   r Nc|jj|jjjj |S)a#Remove leading and trailing characters. Arguments: characters: The set of characters to be removed. All combinations of this set of characters will be stripped from the start and end of the string. If set to None (default), all leading and trailing whitespace is removed instead. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["apple", "\nmango"] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... s = s.str.strip_chars() ... return s.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 apple 1 mango dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [str] [ "apple" "mango" ] )rrBr&rn strip_chars)r characterss rrz!SeriesStringNamespace.strip_charsss>J$$;;  ! ! 3 3 7 7 C CJ O  r c|jj|jjjj |S)arCheck if string values start with a substring. Arguments: prefix: prefix substring Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["apple", "mango", None] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.starts_with("app").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 True 1 False 2 None dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [bool] [ true false null ] )rrBr&rn starts_with)rprefixs rrz!SeriesStringNamespace.starts_withs>L$$;;  ! ! 3 3 7 7 C CF K  r c|jj|jjjj |S)anCheck if string values end with a substring. Arguments: suffix: suffix substring Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["apple", "mango", None] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.ends_with("ngo").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 False 1 True 2 None dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [bool] [ false true null ] )rrBr&rn ends_with)rsuffixs rrzSeriesStringNamespace.ends_withs>L$$;;  ! ! 3 3 7 7 A A& I  r c|jj|jjjj ||S)aCheck if string contains a substring that matches a pattern. Arguments: pattern: A Character sequence or valid regular expression pattern. literal: If True, treats the pattern as a literal string. If False, assumes the pattern is a regular expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> pets = ["cat", "dog", "rabbit and parrot", "dove", None] >>> s_pd = pd.Series(pets) >>> s_pl = pl.Series(pets) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.contains("parrot|dove").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 False 1 False 2 True 3 True 4 None dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: '' [bool] [ false false true true null ] r)rrBr&rncontains)rrrs rrzSeriesStringNamespace.containssDX$$;;  ! ! 3 3 7 7 @ @RY @ Z  r c|jj|jjjj ||S)aCreate subslices of the string values of a Series. Arguments: offset: Start index. Negative indexing is supported. length: Length of the slice. If set to `None` (default), the slice is taken to the end of the string. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["pear", None, "papaya", "dragonfruit"] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.slice(4, length=3).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 1 None 2 ya 3 onf dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [str] [ "" null "ya" "onf" ] Using negative indexes: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.slice(-3).to_native() >>> my_library_agnostic_function(s_pd) # doctest: +NORMALIZE_WHITESPACE 0 ear 1 None 2 aya 3 uit dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [str] [ "ear" null "aya" "uit" ] rOrmrrBr&rnslice)rrOrms rrzSeriesStringNamespace.slice sHB$$;;  ! ! 3 3 7 7 = =f >   r c|jj|jjjj d|S)a1Take the first n elements of each string. Arguments: n: Number of elements to take. Negative indexing is supported (see note (1.)) Notes: 1. When the `n` input is negative, `head` returns characters up to the n-th from the end of the string. For example, if `n = -3`, then all characters except the last three are returned. 2. If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> lyrics = ["Atatata", "taata", "taatatata", "zukkyun"] >>> s_pd = pd.Series(lyrics) >>> s_pl = pl.Series(lyrics) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.head().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 Atata 1 taata 2 taata 3 zukky dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [str] [ "Atata" "taata" "taata" "zukky" ] rrrrs rrBzSeriesStringNamespace.headgsCX$$;;  ! ! 3 3 7 7 = =Qq = Q  r c|jj|jjjj | dS)a?Take the last n elements of each string. Arguments: n: Number of elements to take. Negative indexing is supported (see note (1.)) Notes: 1. When the `n` input is negative, `tail` returns characters starting from the n-th from the beginning of the string. For example, if `n = -3`, then all characters except the first three are returned. 2. If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> lyrics = ["Atatata", "taata", "taatatata", "zukkyun"] >>> s_pd = pd.Series(lyrics) >>> s_pl = pl.Series(lyrics) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.tail().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 atata 1 taata 2 atata 3 kkyun dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [str] [ "atata" "taata" "atata" "kkyun" ] Nrrrs rrDzSeriesStringNamespace.tailsFX$$;;  ! ! 3 3 7 7 = =aRPT = U  r c|jj|jjjj S)u>Transform string to uppercase variant. Notes: The PyArrow backend will convert 'ß' to 'ẞ' instead of 'SS'. For more info see: https://github.com/apache/arrow/issues/34599 There may be other unicode-edge-case-related variations across implementations. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... upper_col=nw.col("fruits").str.to_uppercase() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) # doctest: +NORMALIZE_WHITESPACE fruits upper_col 0 apple APPLE 1 mango MANGO 2 None None >>> my_library_agnostic_function(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 2) ┌────────┬───────────┐ │ fruits ┆ upper_col │ │ --- ┆ --- │ │ str ┆ str │ ╞════════╪═══════════╡ │ apple ┆ APPLE │ │ mango ┆ MANGO │ │ null ┆ null │ └────────┴───────────┘ )rrBr&rn to_uppercaser/s rrz"SeriesStringNamespace.to_uppercases<\$$;;  ! ! 3 3 7 7 D D F  r c|jj|jjjj S)uDTransform string to lowercase variant. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT, IntoFrameT >>> data = {"fruits": ["APPLE", "MANGO", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... lower_col=nw.col("fruits").str.to_lowercase() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) # doctest: +NORMALIZE_WHITESPACE fruits lower_col 0 APPLE apple 1 MANGO mango 2 None None >>> my_library_agnostic_function(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 2) ┌────────┬───────────┐ │ fruits ┆ lower_col │ │ --- ┆ --- │ │ str ┆ str │ ╞════════╪═══════════╡ │ APPLE ┆ apple │ │ MANGO ┆ mango │ │ null ┆ null │ └────────┴───────────┘ )rrBr&rn to_lowercaser/s rrz"SeriesStringNamespace.to_lowercases<R$$;;  ! ! 3 3 7 7 D D F  r c|jj|jjjj |S)ueParse Series with strings to a Series with Datetime dtype. Notes: pandas defaults to nanosecond time unit, Polars to microsecond. Prior to pandas 2.0, nanoseconds were the only time unit supported in pandas, with no ability to set any other one. The ability to set the time unit in pandas, if the version permits, will arrive. Warning: As different backends auto-infer format in different ways, if `format=None` there is no guarantee that the result will be equal. Arguments: format: Format to use for conversion. If set to None (default), the format is inferred from the data. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["2020-01-01", "2020-01-02"] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.str.to_datetime(format="%Y-%m-%d").to_native() We can then pass any supported library such as pandas, Polars, or PyArrow:: >>> my_library_agnostic_function(s_pd) 0 2020-01-01 1 2020-01-02 dtype: datetime64[ns] >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [datetime[μs]] [ 2020-01-01 00:00:00 2020-01-02 00:00:00 ] >>> my_library_agnostic_function(s_pa) # doctest: +ELLIPSIS [ [ 2020-01-01 00:00:00.000000, 2020-01-02 00:00:00.000000 ] ] )format)rrBr&rn to_datetimerrs rrz!SeriesStringNamespace.to_datetime&sAp$$;;  ! ! 3 3 7 7 C C6 C R  r rr) rrrrnrrnrr|rr@rwr) rrrrnrrnrr|rwrr6)rrrrrwr)rrrrnrwr)rrrrnrwr)rrrrnrr|rwr)rrrOr@rmrrwr))rrrr@rwr)rwr)rrrrrwr)rrrr,rrrrrrrrrBrDrrrr7r rrmrm s') XBGQR. .  . ),. :>. KN. . bBG- -  - ),- :>- - ^' R( T( T?D. `E N. `. `0 d+ Z: r rmceZdZddZddZddZddZddZddZddZ ddZ dd Z dd Z dd Z dd Zdd ZddZddZddZddZddZddZddZdddZy)rpc||_yr6rrcs rr,z SeriesDateTimeNamespace.__init__drr c|jj|jjjj S)aGet the date in a datetime series. Raises: NotImplementedError: If pandas default backend is being used. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2012, 1, 7, 10, 20), datetime(2023, 3, 10, 11, 32)] >>> s_pd = pd.Series(dates).convert_dtypes(dtype_backend="pyarrow") >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.date().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2012-01-07 1 2023-03-10 dtype: date32[day][pyarrow] >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [date] [ 2012-01-07 2023-03-10 ] )rrBr&rqdater/s rrzSeriesDateTimeNamespace.dategs<J$$;;  ! ! 3 3 6 6 ; ; =  r c|jj|jjjj S)a4Get the year in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2012, 1, 7), datetime(2023, 3, 10)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.year().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2012 1 2023 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i32] [ 2012 2023 ] )rrBr&rqyearr/s rrzSeriesDateTimeNamespace.year<B$$;;  ! ! 3 3 6 6 ; ; =  r c|jj|jjjj S)a)Gets the month in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2023, 2, 1), datetime(2023, 8, 3)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.month().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2 1 8 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 2 8 ] )rrBr&rqmonthr/s rrzSeriesDateTimeNamespace.months<B$$;;  ! ! 3 3 6 6 < < >  r c|jj|jjjj S)a)Extracts the day in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2022, 1, 1), datetime(2022, 1, 5)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.day().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 5 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 1 5 ] )rrBr&rqdayr/s rrzSeriesDateTimeNamespace.days<B$$;;  ! ! 3 3 6 6 : : <  r c|jj|jjjj S)a8Extracts the hour in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.hour().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 5 1 9 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 5 9 ] )rrBr&rqhourr/s rrzSeriesDateTimeNamespace.hourrr c|jj|jjjj S)a?Extracts the minute in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.minute().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 3 1 12 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 3 12 ] )rrBr&rqminuter/s rrzSeriesDateTimeNamespace.minute$<B$$;;  ! ! 3 3 6 6 = = ?  r c|jj|jjjj S)aHExtracts the seconds in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [datetime(2022, 1, 1, 5, 3, 10), datetime(2022, 1, 5, 9, 12, 4)] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.second().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 10 1 4 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i8] [ 10 4 ] )rrBr&rqsecondr/s rrzSeriesDateTimeNamespace.secondIrr c|jj|jjjj S)aExtracts the milliseconds in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [ ... datetime(2023, 5, 21, 12, 55, 10, 400000), ... datetime(2023, 5, 21, 12, 55, 10, 600000), ... datetime(2023, 5, 21, 12, 55, 10, 800000), ... datetime(2023, 5, 21, 12, 55, 11, 0), ... datetime(2023, 5, 21, 12, 55, 11, 200000), ... ] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.millisecond().alias("datetime").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 400 1 600 2 800 3 0 4 200 Name: datetime, dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: 'datetime' [i32] [ 400 600 800 0 200 ] )rrBr&rq millisecondr/s rrz#SeriesDateTimeNamespace.millisecondn<\$$;;  ! ! 3 3 6 6 B B D  r c|jj|jjjj S)aExtracts the microseconds in a datetime series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [ ... datetime(2023, 5, 21, 12, 55, 10, 400000), ... datetime(2023, 5, 21, 12, 55, 10, 600000), ... datetime(2023, 5, 21, 12, 55, 10, 800000), ... datetime(2023, 5, 21, 12, 55, 11, 0), ... datetime(2023, 5, 21, 12, 55, 11, 200000), ... ] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.microsecond().alias("datetime").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 400000 1 600000 2 800000 3 0 4 200000 Name: datetime, dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (5,) Series: 'datetime' [i32] [ 400000 600000 800000 0 200000 ] )rrBr&rq microsecondr/s rrz#SeriesDateTimeNamespace.microsecondrr c|jj|jjjj S)aExtract the nanoseconds in a date series. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> dates = [ ... datetime(2022, 1, 1, 5, 3, 10, 500000), ... datetime(2022, 1, 5, 9, 12, 4, 60000), ... ] >>> s_pd = pd.Series(dates) >>> s_pl = pl.Series(dates) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.nanosecond().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 500000000 1 60000000 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i32] [ 500000000 60000000 ] )rrBr&rq nanosecondr/s rrz"SeriesDateTimeNamespace.nanoseconds<H$$;;  ! ! 3 3 6 6 A A C  r c|jj|jjjj S)aGet ordinal day. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [datetime(2020, 1, 1), datetime(2020, 8, 3)] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.ordinal_day().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 1 1 216 dtype: int32 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i16] [ 1 216 ] )rrBr&rq ordinal_dayr/s rrz#SeriesDateTimeNamespace.ordinal_days<B$$;;  ! ! 3 3 6 6 B B D  r c|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: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [timedelta(minutes=10), timedelta(minutes=20, seconds=40)] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.total_minutes().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 10 1 20 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 20 ] )rrBr&rq total_minutesr/s rrz%SeriesDateTimeNamespace.total_minutes<L$$;;  ! ! 3 3 6 6 D D F  r c|jj|jjjj S)a/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. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [timedelta(seconds=10), timedelta(seconds=20, milliseconds=40)] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.total_seconds().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 10 1 20 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 20 ] )rrBr&rq total_secondsr/s rrz%SeriesDateTimeNamespace.total_secondsIrr c|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: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [ ... timedelta(milliseconds=10), ... timedelta(milliseconds=20, microseconds=40), ... ] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.total_milliseconds().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 10 1 20 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 20 ] )rrBr&rqtotal_millisecondsr/s rrz*SeriesDateTimeNamespace.total_millisecondss<R$$;;  ! ! 3 3 6 6 I I K  r c|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: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [ ... timedelta(microseconds=10), ... timedelta(milliseconds=1, microseconds=200), ... ] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.total_microseconds().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 10 1 1200 dtype: int... >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ 10 1200 ] )rrBr&rqtotal_microsecondsr/s rrz*SeriesDateTimeNamespace.total_microsecondsrr c|jj|jjjj S)ayGet 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: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = ["2024-01-01 00:00:00.000000001", "2024-01-01 00:00:00.000000002"] >>> s_pd = pd.to_datetime(pd.Series(data)) >>> s_pl = pl.Series(data).str.to_datetime(time_unit="ns") We define a library agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.diff().dt.total_nanoseconds().to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 NaN 1 1.0 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [i64] [ null 1 ] )rrBr&rqtotal_nanosecondsr/s rrz)SeriesDateTimeNamespace.total_nanosecondss<L$$;;  ! ! 3 3 6 6 H H J  r c|jj|jjjj |S)a Convert a Date/Time/Datetime series into a String series with the given 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 pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [ ... datetime(2020, 3, 1), ... datetime(2020, 4, 1), ... datetime(2020, 5, 1), ... ] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.to_string("%Y/%m/%d").to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(s_pd) 0 2020/03/01 1 2020/04/01 2 2020/05/01 dtype: object >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [str] [ "2020/03/01" "2020/04/01" "2020/05/01" ] )rrBr&rq to_stringrs rrz!SeriesDateTimeNamespace.to_strings>N$$;;  ! ! 3 3 6 6 @ @ H  r c|jj|jjjj |S)uReplace time zone. Arguments: time_zone: Target time zone. Examples: >>> from datetime import datetime, timezone >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [ ... datetime(2024, 1, 1, tzinfo=timezone.utc), ... datetime(2024, 1, 2, tzinfo=timezone.utc), ... ] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.replace_time_zone("Asia/Kathmandu").to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(s_pd) 0 2024-01-01 00:00:00+05:45 1 2024-01-02 00:00:00+05:45 dtype: datetime64[ns, Asia/Kathmandu] >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [datetime[μs, Asia/Kathmandu]] [ 2024-01-01 00:00:00 +0545 2024-01-02 00:00:00 +0545 ] >>> my_library_agnostic_function(s_pa) [ [ 2023-12-31 18:15:00.000000Z, 2024-01-01 18:15:00.000000Z ] ] )rrBr&rqreplace_time_zone)r time_zones rrz)SeriesDateTimeNamespace.replace_time_zoneBs>b$$;;  ! ! 3 3 6 6 H H S  r c| d}t||jj|jjjj |S)uMConvert 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 narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [ ... datetime(2024, 1, 1, tzinfo=timezone.utc), ... datetime(2024, 1, 2, tzinfo=timezone.utc), ... ] >>> s_pd = pd.Series(data) >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.convert_time_zone("Asia/Kathmandu").to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(s_pd) 0 2024-01-01 05:45:00+05:45 1 2024-01-02 05:45:00+05:45 dtype: datetime64[ns, Asia/Kathmandu] >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [datetime[μs, Asia/Kathmandu]] [ 2024-01-01 05:45:00 +0545 2024-01-02 05:45:00 +0545 ] >>> my_library_agnostic_function(s_pa) [ [ 2024-01-01 00:00:00.000000Z, 2024-01-02 00:00:00.000000Z ] ] zTarget `time_zone` cannot be `None` in `convert_time_zone`. Please use `replace_time_zone(None)` if you want to remove the time zone.)rrrBr&rqconvert_time_zone)rrr+s rrz)SeriesDateTimeNamespace.convert_time_zonewsVh  ZCC. $$;;  ! ! 3 3 6 6 H H S  r c|dvrd|d}t||jj|jjjj |S)asReturn a timestamp in the given time unit. Arguments: time_unit: {'ns', 'us', 'ms'} Time unit. Examples: >>> from datetime import date >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [date(2001, 1, 1), None, date(2001, 1, 3)] >>> s_pd = pd.Series(data, dtype="datetime64[ns]") >>> s_pl = pl.Series(data) >>> s_pa = pa.chunked_array([data]) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.dt.timestamp("ms").to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(s_pd) 0 9.783072e+11 1 NaN 2 9.784800e+11 dtype: float64 >>> my_library_agnostic_function(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [i64] [ 978307200000 null 978480000000 ] >>> my_library_agnostic_function(s_pa) [ [ 978307200000, null, 978480000000 ] ] >msnsusz=invalid `time_unit` Expected one of {'ns', 'us', 'ms'}, got r#)rrrBr&rq timestamp)r time_unitr+s rrz!SeriesDateTimeNamespace.timestampskd . .AAJ QP S/ !$$;;  ! ! 3 3 6 6 @ @ K  r Nrr)rrrrnrwr)rrrrrwr)rrrrnrwr)r)rrrzLiteral['ns', 'us', 'ms']rwr)rrrr,rrrrrrrrrrrrrrrrrrrrr7r rrprpcs'' R# J# J# J# J# J# J0 d0 d& P# J( T( T+ Z+ Z( TI V3 j9 v: r rpceZdZddZddZy)rvc||_yr6rrcs rr,zSeriesListNamespace.__init__rr c|jj|jjjj S)a Return the number of elements in each list. Null values count towards the total. Returns: A new series. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = [[1, 2], [3, 4, None], None, []] Let's define a dataframe-agnostic function: >>> def agnostic_list_len(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.list.len().to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> agnostic_list_len( ... pd.Series(data, dtype=pd.ArrowDtype(pa.list_(pa.int64()))) ... ) # doctest: +SKIP 0 2 1 3 2 3 0 dtype: int32[pyarrow] >>> agnostic_list_len(pl.Series(data)) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [u32] [ 2 3 null 0 ] >>> agnostic_list_len(pa.chunked_array([data])) # doctest: +ELLIPSIS [ [ 2, 3, null, 0 ] ] )rrBr&rrkr/s rrkzSeriesListNamespace.lens<l$$;;  ! ! 3 3 8 8 < < >  r Nrr)rrrr,rkr7r rrvrvs '8 r rv)* __future__rtypingrrrrrr r r r r narwhals.dependenciesrnarwhals.dtypesrnarwhals.typingrnarwhals.utilsrrtypesrnumpynppandaspdrJrPtyping_extensionsrrrrrrrrsrmrprvr7r rrs" 1+'6( &,%-R6)W[ !R6)jl )6#; /) )) X{  GG,{  |I gg.I X< ''*< r