g#&ddlmZddlmZddlmZddlmZddlmZddlmZddlm Z ddlm Z dd lm Z dd lm Z dd l mZdd lZdd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z!ddl"m#Z#ddl"m$Z$ddl"m%Z%ddl"m&Z&ddl"m'Z'ddl"m(Z(ddl"m)Z)ddl"m*Z+ddl"m,Z,ddl"m-Z-dd l.m/Z0dd!l1m2Z3dd"l4m5Z5dd#l6m7Z7dd$l6m8Z8dd%l6m9Z9dd&l6m:Z:dd'l6m;Z;dd(l6mZ>dd+l6m?Z?dd,l6m@Z@dd-l6mAZAdd.l6mBZBdd/l6mCZCdd0l6mDZDdd1l6mEZEdd2l6mFZFdd3l6mGZGdd4l6mHZHdd5l6mIZIdd6l6mJZJdd7l6mKZKdd8l6mLZLdd9l6mMZMdd:l6mNZNdd;l6mOZOddlQmSZSdd?lQmTZTdd@lUmVZVddAlUmWZWddBlUmXZXddClYmZZZddDlYm[Z[ddElYm\Z\ddFlYm]Z]ddGlYm^Z^ddHlYm_Z_ddIlYm`Z`ddJlYmaZaddKlYmbZbddLlYmcZcer(ddMldmeZedd lfZgddNlhmiZiddOljmkZkddPl"mlZlddQlUmmZmddRlUmnZne dSZoGdTdUeeVZGdVdWeeWZGdXdYe3eZ2GdZd[eZGd\d]e0Z/e dd^Zpe dd_Zpe dd`Zpe ddaZpe ddbZp ddcZpe ddddde ddfZqe dddddg ddhZqe dddddddi ddjZqe dddddddi ddkZqe dddddddl ddmZqe dddddddl ddnZqe dddddddo ddpZqe dddddddq ddrZqe ddddddddds ddtZqe ddddddddds dduZqe dddddddddv ddwZqe dddddddddx ddyZqe dddddddddz dd{Zqe ddddddddd| dd}Zqe ddddddddddd~ ddZqe ddddde ddZqe dddddg ddZqe dddddddi ddZqe dddddddi ddZqe dddddddl ddZqe dddddddl ddZqe dddddddo ddZqe dddddddq ddZqe ddddddddds ddZqe ddddddddds ddZqe ddddddddd ddZqe ddddddddd ddZqe ddddddddd ddZqe ddddddddd ddZqe ddddddddddd ddZqe dd ddZqd d dddd d ddZqe ddd ddZre ddd ddZre dddddZre ddZre ddd ddZre ddd ddZre dddddZre ddZrd d d ddZr dd d ddddd ddZsddZtddZuddZvddZwdddZxddZyddZzddZ{ddZ|ddZ}ddZ~ddZddZddZddZddZe dd ddZe dd ddZdd ddZddd ddZGddeZGddeeZd dÄZ d d dĄZ d dńZ* dd dƜ d dDŽZ d d dȄZ ddɄZ ddʄZ dd˄Z dd̄Zgd͢Zy () annotationswraps) TYPE_CHECKING)Any)Callable)Iterable)Literal)Sequence)TypeVar)overload)warnN) dependencies) exceptions) selectors DataFrame LazyFrame)Expr)Then)When)when)_from_dict_impl)_from_numpy_impl)_new_series_impl)_read_csv_impl)_read_parquet_impl)_scan_csv_impl)_scan_parquet_impl) from_arrow) get_level) show_versions)SchemaSeries)dtypes)Array)Boolean) Categorical)Date)Datetime)Decimal)Duration)Enum)Field)Float32)Float64)Int8)Int16)Int32)Int64)Int128)List)Object)String)Struct)UInt8)UInt16)UInt32)UInt64)UInt128)Unknown)_from_native_impl)get_native_namespace) to_py_scalar)IntoDataFrameT) IntoFrameT) IntoSeriesT)Implementation)Version)generate_temporary_column_name)is_ordered_categorical)maybe_align_index)maybe_convert_dtypes)maybe_get_index)maybe_reset_index)maybe_set_indexvalidate_strict_and_pass_though) ModuleType)Self)DType)ArrowStreamExportable)IntoExpr) IntoSeriesTceZdZdZeddZeddZed dZed!dZed"dZed#dZed$dZed%d Zed&d Zed'd Zed(d Zed)d Zed*dZed+dZed,dZed-dZd.fd Zd/fd Z eddd0dZ ed1dZ ed2dZ dd d2fdZ d3fd Z d3fd Z d4dZ xZS)5raNarwhals DataFrame, backed by a native eager dataframe. !!! warning This class is not meant to be instantiated directly - instead: - If the native object is a eager dataframe from one of the supported backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table), you can use [`narwhals.from_native`][]: ```py narwhals.from_native(native_dataframe) narwhals.from_native(native_dataframe, eager_only=True) ``` - If the object is a dictionary of column names and generic sequences mapping (e.g. `dict[str, list]`), you can create a DataFrame via [`narwhals.from_dict`][]: ```py narwhals.from_dict( data={"a": [1, 2, 3]}, native_namespace=narwhals.get_native_namespace(another_object), ) ``` ctSNr%selfs P/var/www/openai/venv/lib/python3.12/site-packages/narwhals/stable/v1/__init__.py_serieszDataFrame._serieszs ctSr\rr]s r_ _lazyframezDataFrame._lazyframe~racyr\r^items r_ __getitem__zDataFrame.__getitem__FIracyr\rfrgs r_rizDataFrame.__getitem__NQracyr\rfrgs r_rizDataFrame.__getitem__rjracyr\rfrgs r_rizDataFrame.__getitem__rjracyr\rfrgs r_rizDataFrame.__getitem__>Aracyr\rfrgs r_rizDataFrame.__getitem__rlracyr\rfrgs r_rizDataFrame.__getitem__rjracyr\rfrgs r_rizDataFrame.__getitem__rjracyr\rfrgs r_rizDataFrame.__getitem__rpracyr\rfrgs r_rizDataFrame.__getitem__8;racyr\rfrgs r_rizDataFrame.__getitem__03racyr\rfrgs r_rizDataFrame.__getitem__rvracyr\rfrgs r_rizDataFrame.__getitem__rxracyr\rfrgs r_rizDataFrame.__getitem__rprac"t||Sr\)superri)r^rh __class__s r_rizDataFrame.__getitem__sw"4((rac t|S)aLazify the DataFrame (if possible). If a library does not support lazy execution, then this is a no-op. Returns: A new LazyFrame. Examples: Construct pandas, Polars and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_lazy(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.lazy().to_native() Note that then, pandas and pyarrow dataframe stay eager, but Polars DataFrame becomes a Polars LazyFrame: >>> agnostic_lazy(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_lazy(df_pl) >>> agnostic_lazy(df_pa) pyarrow.Table foo: int64 bar: double ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] )r}lazyr^r~s r_rzDataFrame.lazys^w|~ra. as_seriescyr\rfr^rs r_to_dictzDataFrame.to_dictORracyr\rfrs r_rzDataFrame.to_dictsMPracyr\rfrs r_rzDataFrame.to_dictsWZraTc$t||S)aqConvert DataFrame to a dictionary mapping column name to values. Arguments: as_series: If set to true ``True``, then the values are Narwhals Series, otherwise the values are Any. Returns: A mapping from column name to values / Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = { ... "A": [1, 2, 3, 4, 5], ... "fruits": ["banana", "banana", "apple", "apple", "banana"], ... "B": [5, 4, 3, 2, 1], ... "animals": ["beetle", "fly", "beetle", "beetle", "beetle"], ... "optional": [28, 300, None, 2, -30], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_to_dict( ... df_native: IntoDataFrame, ... ) -> dict[str, list[int | str | float | None]]: ... df = nw.from_native(df_native) ... return df.to_dict(as_series=False) We can then pass either pandas, Polars or PyArrow to `agnostic_to_dict`: >>> agnostic_to_dict(df_pd) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28.0, 300.0, nan, 2.0, -30.0]} >>> agnostic_to_dict(df_pl) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} >>> agnostic_to_dict(df_pa) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} r)r}r)r^rr~s r_rzDataFrame.to_dicts\w33rac t|S)aGet a mask of all duplicated rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_is_duplicated(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native, eager_only=True) ... return df.is_duplicated().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_is_duplicated`: >>> agnostic_is_duplicated(df_pd) 0 True 1 False 2 False 3 True dtype: bool >>> agnostic_is_duplicated(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ true false false true ] >>> agnostic_is_duplicated(df_pa) # doctest: +ELLIPSIS [ [ true, false, false, true ] ] )r} is_duplicatedrs r_rzDataFrame.is_duplicatedsrw$&&rac t|S)aGet a mask of all unique rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_is_unique(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native, eager_only=True) ... return df.is_unique().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_is_unique`: >>> agnostic_is_unique(df_pd) 0 False 1 True 2 True 3 False dtype: bool >>> agnostic_is_unique(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ false true true false ] >>> agnostic_is_unique(df_pa) # doctest: +ELLIPSIS [ [ false, true, true, false ] ] )r} is_uniquers r_rzDataFrame.is_uniqueKsrw ""racP|jtjS)zbPrivate, just used to test the stable API. Returns: A new DataFrame. selectall_l1_normr]s r_rzDataFrame._l1_norm {{35>>+,,ra)returnz type[Series])rztype[LazyFrame[Any]])rhztuple[Sequence[int], slice]rrT)rhz#tuple[Sequence[int], Sequence[int]]rrT)rhztuple[slice, Sequence[int]]rrT)rhztuple[Sequence[int], str]rr&)rhztuple[slice, str]rr&)rhz#tuple[Sequence[int], Sequence[str]]rrT)rhztuple[slice, Sequence[str]]rrT)rhztuple[Sequence[int], int]rr&)rhztuple[slice, int]rr&)rhz Sequence[int]rrT)rhstrrr&)rhz Sequence[str]rrT)rhslicerrT)rhztuple[slice, slice]rrT)rhrrr)rLazyFrame[Any])r Literal[True]rzdict[str, Series])rLiteral[False]rzdict[str, list[Any]])rboolrz(dict[str, Series] | dict[str, list[Any]])r^rTrr&r^rTrrT)__name__ __module__ __qualname____doc__propertyr`rcr rirrrrr __classcell__r~s@r_rr^sZ6II QQ II II AA QQ II II AA ;; 33 ;; 33 AA)/f47RR PP ZZ#'.4 .4 1.4`9'v9#v-rarc>eZdZdZeddZdfd ZddZxZS)raNarwhals LazyFrame, backed by a native lazyframe. !!! warning This class is not meant to be instantiated directly - instead use [`narwhals.from_native`][] with a native object that is a lazy dataframe from one of the supported backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame): ```py narwhals.from_native(native_lazyframe) ``` ctSr\rr]s r_ _dataframezLazyFrame._dataframerdrac t|S)u Materialize this LazyFrame into a DataFrame. Returns: DataFrame Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> data = { ... "a": ["a", "b", "a", "b", "b", "c"], ... "b": [1, 2, 3, 4, 5, 6], ... "c": [6, 5, 4, 3, 2, 1], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) >>> lf = nw.from_native(lf_pl) >>> lf # doctest:+ELLIPSIS ┌─────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------| |>> df = lf.group_by("a").agg(nw.all().sum()).collect() >>> df.to_native().sort("a") shape: (3, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 4 ┆ 10 │ │ b ┆ 11 ┆ 10 │ │ c ┆ 6 ┆ 1 │ └─────┴─────┴─────┘ >>> lf = nw.from_native(lf_dask) >>> lf ┌───────────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------------| |Dask DataFrame Structure: | | a b c| |npartitions=2 | |0 string int64 int64| |3 ... ... ...| |5 ... ... ...| |Dask Name: frompandas, 1 expression| |Expr=df | └───────────────────────────────────┘ >>> df = lf.group_by("a").agg(nw.col("b", "c").sum()).collect() >>> df.to_native() a b c 0 a 4 10 1 b 11 10 2 c 6 1 )r}collectrs r_rzLazyFrame.collectsvw  racP|jtjS)zbPrivate, just used to test the stable API. Returns: A new lazyframe. rr]s r_rzLazyFrame._l1_normrrarztype[DataFrame[Any]]rDataFrame[Any]r) rrrrrrrrrrs@r_rrs' ;!z-rarcHeZdZdZeddZdfd Zddddd dfdZdddddd dd  dfd Zddd  dfd Z ddd  dfdZ ddd d dfdZ ddd d dfdZ xZ S)r&aiNarwhals Series, backed by a native series. !!! warning This class is not meant to be instantiated directly - instead: - If the native object is a series from one of the supported backend (e.g. pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use [`narwhals.from_native`][]: ```py narwhals.from_native(native_series, allow_series=True) narwhals.from_native(native_series, series_only=True) ``` - If the object is a generic sequence (e.g. a list or a tuple of values), you can create a series via [`narwhals.new_series`][]: ```py narwhals.new_series( name=name, values=values, native_namespace=narwhals.get_native_namespace(another_object), ) ``` ctSr\rr]s r_rzSeries._dataframerdrac t|S)uConvert to dataframe. Returns: A DataFrame containing this Series as a single column. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = [1, 2] >>> s_pd = pd.Series(data, name="a") >>> s_pl = pl.Series("a", data) >>> s_pa = pa.chunked_array([data]) We define a library agnostic function: >>> def agnostic_to_frame(s_native: IntoSeries) -> IntoDataFrame: ... s = nw.from_native(s_native, series_only=True) ... return s.to_frame().to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `agnostic_to_frame`: >>> agnostic_to_frame(s_pd) a 0 1 1 2 >>> agnostic_to_frame(s_pl) shape: (2, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ └─────┘ >>> agnostic_to_frame(s_pa) pyarrow.Table : int64 ---- : [[1,2]] )r}to_framers r_rzSeries.to_framesdw!!raFNsortparallelname normalizec*t|||||S)uq Count 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 DataFrame with two columns: - The original values as first column - Either count or proportion as second column, depending on normalize parameter. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = [1, 1, 2, 3, 2] >>> s_pd = pd.Series(data, name="s") >>> s_pl = pl.Series(values=data, name="s") >>> s_pa = pa.chunked_array([data]) Let's define a dataframe-agnostic function: >>> def agnostic_value_counts(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 any supported library such as pandas, Polars, or PyArrow to `agnostic_value_counts`: >>> agnostic_value_counts(s_pd) s count 0 1 2 1 2 2 2 3 1 >>> agnostic_value_counts(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 2) ┌─────┬───────┐ │ s ┆ count │ │ --- ┆ --- │ │ i64 ┆ u32 │ ╞═════╪═══════╡ │ 1 ┆ 2 │ │ 2 ┆ 2 │ │ 3 ┆ 1 │ └─────┴───────┘ >>> agnostic_value_counts(s_pa) pyarrow.Table : int64 count: int64 ---- : [[1,2,3]] count: [[2,2,1]] r)r} value_counts)r^rrrrr~s r_rzSeries.value_counts:s&Nw#ty$  raTcomspan half_lifealphaadjust min_periods ignore_nullsc rddlm}ddlm} d} t | || t ||||||||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 agnostic_ewm_mean(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 any supported library such as pandas or Polars to `agnostic_ewm_mean`: >>> agnostic_ewm_mean(s_pd) 0 1.000000 1 1.666667 2 2.428571 Name: a, dtype: float64 >>> agnostic_ewm_mean(s_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: 'a' [f64] [ 1.0 1.666667 2.428571 ] rNarwhalsUnstableWarningfind_stacklevelz^`Series.ewm_mean` is being called from the stable API although considered an unstable feature.messagecategory stacklevelrnarwhals.exceptionsrnarwhals.utilsrrr}ewm_mean r^rrrrrrrrrmsgr~s r_rzSeries.ewm_meansUl @2 #  S#:GXYw#%   rarcentercjddlm}ddlm}d}t |||t ||||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 series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> 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 `agnostic_rolling_sum`: >>> 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 ] ] rrrza`Series.rolling_sum` is being called from the stable API although considered an unstable feature.r window_sizerrrrrrrr} rolling_sumr^rrrrrrr~s r_rzSeries.rolling_sumsI` @2 #  S#:GXYw"###  racjddlm}ddlm}d}t |||t ||||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 series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> 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 `agnostic_rolling_mean`: >>> 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 ] ] rrrzb`Series.rolling_mean` is being called from the stable API although considered an unstable feature.rrrrrrrr} rolling_meanrs r_rzSeries.rolling_meanKsI` @2 #  S#:GXYw###$  rarrddofclddlm}ddlm}d}t |||t |||||S)a/ Apply a rolling variance (moving variance) 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 variance. 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. ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof. Returns: A new series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [1.0, 3.0, 1.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_var(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.rolling_var(window_size=2, min_periods=1).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `agnostic_rolling_var`: >>> agnostic_rolling_var(s_pd) 0 NaN 1 2.0 2 2.0 3 4.5 dtype: float64 >>> agnostic_rolling_var(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [f64] [ null 2.0 2.0 4.5 ] >>> agnostic_rolling_var(s_pa) # doctest:+ELLIPSIS [ [ nan, 2, 2, 4.5 ] ] rrrza`Series.rolling_var` is being called from the stable API although considered an unstable feature.rrrrrrrrrrr} rolling_var r^rrrrrrrr~s r_rzSeries.rolling_varLd @2 #  S#:GXYw"## #  raclddlm}ddlm}d}t |||t |||||S)a Apply a rolling standard deviation (moving standard deviation) 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 standard deviation. 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. ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof. Returns: A new series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoSeriesT >>> data = [1.0, 3.0, 1.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_std(s_native: IntoSeriesT) -> IntoSeriesT: ... s = nw.from_native(s_native, series_only=True) ... return s.rolling_std(window_size=2, min_periods=1).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `agnostic_rolling_std`: >>> agnostic_rolling_std(s_pd) 0 NaN 1 1.414214 2 1.414214 3 2.121320 dtype: float64 >>> agnostic_rolling_std(s_pl) # doctest:+NORMALIZE_WHITESPACE shape: (4,) Series: '' [f64] [ null 1.414214 1.414214 2.12132 ] >>> agnostic_rolling_std(s_pa) # doctest:+ELLIPSIS [ [ nan, 1.4142135623730951, 1.4142135623730951, 2.1213203435596424 ] ] rrrza`Series.rolling_std` is being called from the stable API although considered an unstable feature.rrrrrrrr} rolling_stdrs r_rzSeries.rolling_std rrarr) r^rTrrrrrz str | Nonerrrrr^rTr float | NonerrrrrrrrrintrrrrT r^rTrrr int | NonerrrrT r^rTrrrrrrrrrrT)rrrrrrrrrrrrrrrs@r_r&r&s62"n I I I  I  I  I  I \!!"&""f f f  f  f  f f f f  f X#' \ \ \  \  \  \ D#' \ \ \  \  \  \ D#' _ _ _  _  _  _  _ J#' _ _ _  _  _  _  _ _ rar&ceZdZdfd Zdddddddd dfdZddd dfd Zddd dfd Zdddd  dfd Zdddd  dfd ZxZ S)rc t|Sr\)r} _taxicab_normrs r_rz Expr._l1_normmsw$&&raNTrFrc rddlm}ddlm} d} t | || t ||||||||S)u 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: Expr Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3]} >>> 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.select( ... nw.col("a").ewm_mean(com=1, ignore_nulls=False) ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a 0 1.000000 1 1.666667 2 2.428571 >>> my_library_agnostic_function(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 1) ┌──────────┐ │ a │ │ --- │ │ f64 │ ╞══════════╡ │ 1.0 │ │ 1.666667 │ │ 2.428571 │ └──────────┘ rrrz\`Expr.ewm_mean` is being called from the stable API although considered an unstable feature.rrrrs r_rz Expr.ewm_meanpsUr @2 #  S#:GXYw#%   rarcjddlm}ddlm}d}t |||t ||||S)u7 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 >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> @nw.narwhalify ... def agnostic_rolling_sum(df): ... return df.with_columns( ... b=nw.col("a").rolling_sum(window_size=3, min_periods=1) ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_sum(df_pd) a b 0 1.0 1.0 1 2.0 3.0 2 NaN 3.0 3 4.0 6.0 >>> agnostic_rolling_sum(df_pl) shape: (4, 2) ┌──────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞══════╪═════╡ │ 1.0 ┆ 1.0 │ │ 2.0 ┆ 3.0 │ │ null ┆ 3.0 │ │ 4.0 ┆ 6.0 │ └──────┴─────┘ >>> agnostic_rolling_sum(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[1,3,3,6]] rrrz_`Expr.rolling_sum` is being called from the stable API although considered an unstable feature.rrrrs r_rzExpr.rolling_sumsI^ @2 #  S#:GXYw"###  racjddlm}ddlm}d}t |||t ||||S)uC 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 >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> @nw.narwhalify ... def agnostic_rolling_mean(df): ... return df.with_columns( ... b=nw.col("a").rolling_mean(window_size=3, min_periods=1) ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_mean(df_pd) a b 0 1.0 1.0 1 2.0 1.5 2 NaN 1.5 3 4.0 3.0 >>> agnostic_rolling_mean(df_pl) shape: (4, 2) ┌──────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞══════╪═════╡ │ 1.0 ┆ 1.0 │ │ 2.0 ┆ 1.5 │ │ null ┆ 1.5 │ │ 4.0 ┆ 3.0 │ └──────┴─────┘ >>> agnostic_rolling_mean(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[1,1.5,1.5,3]] rrrz``Expr.rolling_mean` is being called from the stable API although considered an unstable feature.rrrrs r_rzExpr.rolling_mean8sI^ @2 #  S#:GXYw###$  rarclddlm}ddlm}d}t |||t |||||S)uB Apply a rolling variance (moving variance) 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 variance. 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. ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rolling_var(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... b=nw.col("a").rolling_var(window_size=3, min_periods=1) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_var(df_pd) a b 0 1.0 NaN 1 2.0 0.5 2 NaN 0.5 3 4.0 2.0 >>> agnostic_rolling_var(df_pl) # doctest:+SKIP shape: (4, 2) ┌──────┬──────┐ │ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞══════╪══════╡ │ 1.0 ┆ null │ │ 2.0 ┆ 0.5 │ │ null ┆ 0.5 │ │ 4.0 ┆ 2.0 │ └──────┴──────┘ >>> agnostic_rolling_var(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[nan,0.5,0.5,2]] rrrz_`Expr.rolling_var` is being called from the stable API although considered an unstable feature.rrrrs r_rzExpr.rolling_varsJd @2 #  S#:GXYw"#VRV#  raclddlm}ddlm}d}t |||t |||||S)u Apply a rolling standard deviation (moving standard deviation) 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 standard deviation. 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. ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rolling_std(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... b=nw.col("a").rolling_std(window_size=3, min_periods=1) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_std(df_pd) a b 0 1.0 NaN 1 2.0 0.707107 2 NaN 0.707107 3 4.0 1.414214 >>> agnostic_rolling_std(df_pl) # doctest:+SKIP shape: (4, 2) ┌──────┬──────────┐ │ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞══════╪══════════╡ │ 1.0 ┆ null │ │ 2.0 ┆ 0.707107 │ │ null ┆ 0.707107 │ │ 4.0 ┆ 1.414214 │ └──────┴──────────┘ >>> agnostic_rolling_std(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[nan,0.7071067811865476,0.7071067811865476,1.4142135623730951]] rrrz_`Expr.rolling_std` is being called from the stable API although considered an unstable feature.rrrrs r_rzExpr.rolling_stdrra)rrTrrr) rrrrrrrrrrrs@r_rrls' !!"&""i i i  i  i  i i i i  i ^#' [ [ [  [  [  [ B#' [ [ [  [  [  [ B#' \ \ \  \  \  \  \ D#' _ _ _  _  _  _  _ _ rarceZdZdZy)r$aOrdered mapping of column names to their data type. Arguments: schema: Mapping[str, DType] | Iterable[tuple[str, DType]] | None The schema definition given by column names and their associated. *instantiated* Narwhals data type. Accepts a mapping or an iterable of tuples. Examples: Define a schema by passing *instantiated* data types. >>> import narwhals as nw >>> schema = nw.Schema({"foo": nw.Int8(), "bar": nw.String()}) >>> schema Schema({'foo': Int8, 'bar': String}) Access the data type associated with a specific column name. >>> schema["foo"] Int8 Access various schema properties using the `names`, `dtypes`, and `len` methods. >>> schema.names() ['foo', 'bar'] >>> schema.dtypes() [Int8, String] >>> schema.len() 2 N)rrrrrfrar_r$r$Usrar$cyr\rfobjs r_ _stableifyruGJracyr\rfrs r_rrwrracyr\rfrs r_rrys.1racyr\rfrs r_rr{s%(racyr\rfrs r_rr}s!$rac$t|tr>t|jj t j |jSt|tr>t|jj t j |jSt|tr>t|jj t j |jSt|trt|jS|S)N)level) isinstance NwDataFramer_compliant_frame_change_versionrIV1_level NwLazyFramerNwSeriesr&_compliant_seriesNwExprr_to_compliant_exprrs r_rrs#{#  0 0 <**  #{#  0 0 <**  #x   ! ! 1 1'** =**  #vC**++ Jra.) eager_only series_onlycyr\rf native_objectstrictr eager_or_interchange_onlyr  allow_seriess r_ from_nativer*-ra)rr cyr\rfrs r_rrrra)r r rcyr\rfrs r_rr!$racyr\rfrs r_rr ra)rr rcyr\rfrs r_rrrracyr\rfrs r_rrrra)r rr cyr\rfrs r_rr>Ara)r rrcyr\rfrs r_rrra)r rr rcyr\rfrs r_rr58racyr\rfrs r_rrrra)rr r rcyr\rfrs r_rrrra)rrr rcyr\rfrs r_rrrra)rr rr cyr\rfrs r_rr(03ra)rr rrcyr\rfrs r_rr4rra)rr rr rcyr\rfrs r_rr@r!racyr\rfr pass_throughr rr rs r_rrLrracyr\rfr*s r_rrXrracyr\rfr*s r_rrdrracyr\rfr*s r_rrprracyr\rfr*s r_rr|rracyr\rfr*s r_rrrracyr\rfr*s r_rrrracyr\rfr*s r_rrrracyr\rfr*s r_rrr!racyr\rfr*s r_rrrra)r+r r rcyr\rfr*s r_rrrra)r+rr rcyr\rfr*s r_rrrra)r+r rr cyr\rfr*s r_rrr&ra)r+r rrcyr\rfr*s r_rrrrar+r rr rcyr\rfr*s r_rrr!raF)rcyr\rfr*s r_rrs ra)rr+r rr rc t|ttfr|s|St|tr|s|r|St ||dd}t ||||||t j}t|S)a Convert `native_object` to Narwhals Dataframe, Lazyframe, or Series. Arguments: native_object: Raw object from user. Depending on the other arguments, input object can be: - a Dataframe / Lazyframe / Series supported by Narwhals (pandas, Polars, PyArrow, ...) - an object which implements `__narwhals_dataframe__`, `__narwhals_lazyframe__`, or `__narwhals_series__` strict: Determine what happens if the object can't be converted to Narwhals: - `True` or `None` (default): raise an error - `False`: pass object through as-is **Deprecated** (v1.13.0): Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). pass_through: Determine what happens if the object can't be converted to Narwhals: - `False` or `None` (default): raise an error - `True`: pass object through as-is eager_only: Whether to only allow eager objects: - `False` (default): don't require `native_object` to be eager - `True`: only convert to Narwhals if `native_object` is eager eager_or_interchange_only: Whether to only allow eager objects or objects which have interchange-level support in Narwhals: - `False` (default): don't require `native_object` to either be eager or to have interchange-level support in Narwhals - `True`: only convert to Narwhals if `native_object` is eager or has interchange-level support in Narwhals See [interchange-only support](../extending.md/#interchange-only-support) for more details. series_only: Whether to only allow Series: - `False` (default): don't require `native_object` to be a Series - `True`: only convert to Narwhals if `native_object` is a Series allow_series: Whether to allow Series (default is only Dataframe / Lazyframe): - `False` or `None` (default): don't convert to Narwhals if `native_object` is a Series - `True`: allow `native_object` to be a Series Returns: DataFrame, LazyFrame, Series, or original object, depending on which combination of parameters was passed. Fpass_through_defaultemit_deprecation_warning)r+r rr rversion) rrrr&rRrBrIrr)rrr+r rr rresults r_rr svx-)Y!78-(k\2 5SXL!";! F f ra)rcyr\rfnarwhals_objectrs r_ to_nativerE^racyr\rfrCs r_rErEbracyr\rfrCs r_rErEfrracyr\rfrCs r_rErEhs=@rar+cyr\rfrDr+s r_rErEjrFracyr\rfrMs r_rErEnrHracyr\rfrMs r_rErErsVYracyr\rfrMs r_rErEtsCFra)rr+cddlm}ddlm}ddlm}|||dd}t ||r|jjSt ||r|jjS|sdt|d}t||S) a<Convert Narwhals object to native one. Arguments: narwhals_object: Narwhals object. strict: Determine what happens if `narwhals_object` isn't a Narwhals class: - `True` (default): raise an error - `False`: pass object through as-is **Deprecated** (v1.13.0): Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). pass_through: Determine what happens if `narwhals_object` isn't a Narwhals class: - `False` (default): raise an error - `True`: pass object through as-is Returns: Object of class that user started with. r) BaseFramer%rQFr=zExpected Narwhals object, got .) narwhals.dataframerRnarwhals.seriesr&rrRrr _native_framer_native_seriestype TypeError)rDrr+rRr&rRrs r_rErExs6-&>2 5SXL/9-//===/6*00??? .tO/D.EQGn raTcVt|dddfd }||S||S)a Decorate function so it becomes dataframe-agnostic. This will try to convert any dataframe/series-like object into the Narwhals respective DataFrame/Series, while leaving the other parameters as they are. Similarly, if the output of the function is a Narwhals DataFrame or Series, it will be converted back to the original dataframe/series type, while if the output is another type it will be left as is. By setting `pass_through=False`, then every input and every output will be required to be a dataframe/series-like object. Arguments: func: Function to wrap in a `from_native`-`to_native` block. strict: **Deprecated** (v1.13.0): Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). Determine what happens if the object can't be converted to Narwhals: - `True` or `None` (default): raise an error - `False`: pass object through as-is pass_through: Determine what happens if the object can't be converted to Narwhals: - `False` or `None` (default): raise an error - `True`: pass object through as-is eager_only: Whether to only allow eager objects: - `False` (default): don't require `native_object` to be eager - `True`: only convert to Narwhals if `native_object` is eager eager_or_interchange_only: Whether to only allow eager objects or objects which have interchange-level support in Narwhals: - `False` (default): don't require `native_object` to either be eager or to have interchange-level support in Narwhals - `True`: only convert to Narwhals if `native_object` is eager or has interchange-level support in Narwhals See [interchange-only support](../extending.md/#interchange-only-support) for more details. series_only: Whether to only allow Series: - `False` (default): don't require `native_object` to be a Series - `True`: only convert to Narwhals if `native_object` is a Series allow_series: Whether to allow Series (default is only Dataframe / Lazyframe): - `False` or `None`: don't convert to Narwhals if `native_object` is a Series - `True` (default): allow `native_object` to be a Series Returns: Decorated function. Examples: Instead of writing >>> import narwhals as nw >>> def agnostic_group_by_sum(df): ... df = nw.from_native(df, pass_through=True) ... df = df.group_by("a").agg(nw.col("b").sum()) ... return nw.to_native(df) you can just write >>> @nw.narwhalify ... def agnostic_group_by_sum(df): ... return df.group_by("a").agg(nw.col("b").sum()) TFr=c<tdfd }|S)Nc |Dcgc]}t|  }}|jDcic]\}}|t|  }}}g||jDchc]}t|ddx}r|}}|j dkDr d}t | |i|} t | Scc}wcc}}wcc}w)Nr9__native_namespace__rz_Found multiple backends. Make sure that all dataframe/series inputs come from the same backend.rK)ritemsvaluesgetattr__len__ ValueErrorrE)argskwargsargrvaluevbbackendsrrArr rfuncr+r s r_wrapperz.narwhalify..decorator..wrappers%   C!-).G +!-    *$*<<> $2KD%k!-).G +!- $2  342&--/22A $:DAAAA2  !A%w o%4*6*FV,? ?I  sB=C)C)rcrrdrrrr)rjrkrr rr+r s` r_ decoratorznarwhalify..decorators) t% @% @ % @Nra)rjCallable[..., Any]rrmrQ)rjrr+r rr rrls ````` r_ narwhalifyrns>X3 4RWL))V |rac<ttjS)uInstantiate an expression representing all columns. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> 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) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_all(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all() * 2).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_all`: >>> agnostic_all(df_pd) a b 0 2 8 1 4 10 2 6 12 >>> agnostic_all(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 2 ┆ 8 │ │ 4 ┆ 10 │ │ 6 ┆ 12 │ └─────┴─────┘ >>> agnostic_all(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[2,4,6]] b: [[8,10,12]] )rnwrrfrar_rr( sj bffh rac8ttj|S)u!Creates an expression that references one or more columns by their name(s). Arguments: names: Name(s) of the columns to use. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_col(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a") * nw.col("b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_col`: >>> agnostic_col(df_pd) a 0 3 1 8 >>> agnostic_col(df_pl) shape: (2, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 3 │ │ 8 │ └─────┘ >>> agnostic_col(df_pa) pyarrow.Table a: int64 ---- a: [[3,8]] )rrpcol)namess r_rrrr` sh bffen %%rac8ttj|S)uCreates an expression that references one or more columns by their index(es). Notes: `nth` is not supported for Polars version<1.0.0. Please use [`narwhals.col`][] instead. Arguments: indices: One or more indices representing the columns to retrieve. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_nth(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.nth(0) * 2).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_nth`: >>> agnostic_nth(df_pd) a 0 2 1 4 >>> agnostic_nth(df_pl) shape: (2, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 2 │ │ 4 │ └─────┘ >>> agnostic_nth(df_pa) pyarrow.Table a: int64 ---- a: [[2,4]] )rrpnth)indicess r_ruru sn bffg& ''rac<ttjS)uReturn the number of rows. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [5, 10]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_len(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.len()).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_len`: >>> agnostic_len(df_pd) len 0 2 >>> agnostic_len(df_pl) shape: (1, 1) ┌─────┐ │ len │ │ --- │ │ u32 │ ╞═════╡ │ 2 │ └─────┘ >>> agnostic_len(df_pa) pyarrow.Table len: int64 ---- len: [[2]] )rrplenrfrar_rxrx sZ bffh rac@ttj||S)u@Return an expression representing a literal value. Arguments: value: The value to use as literal. dtype: The data type of the literal value. If not provided, the data type will be inferred. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_lit(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(nw.lit(3)).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_lit`: >>> agnostic_lit(df_pd) a literal 0 1 3 1 2 3 >>> agnostic_lit(df_pl) shape: (2, 2) ┌─────┬─────────┐ │ a ┆ literal │ │ --- ┆ --- │ │ i64 ┆ i32 │ ╞═════╪═════════╡ │ 1 ┆ 3 │ │ 2 ┆ 3 │ └─────┴─────────┘ >>> agnostic_lit(df_pa) pyarrow.Table a: int64 literal: int64 ---- a: [[1,2]] literal: [[3,3]] )rrplit)rfdtypes r_rzrz sp bffUE* ++rac8ttj|S)u!Return the minimum value. Note: Syntactic sugar for ``nw.col(columns).min()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [5, 10]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_min(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.min("b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_min`: >>> agnostic_min(df_pd) b 0 5 >>> agnostic_min(df_pl) shape: (1, 1) ┌─────┐ │ b │ │ --- │ │ i64 │ ╞═════╡ │ 5 │ └─────┘ >>> agnostic_min(df_pa) pyarrow.Table b: int64 ---- b: [[5]] )rrpmincolumnss r_r}r}< j bffg& ''rac8ttj|S)u!Return the maximum value. Note: Syntactic sugar for ``nw.col(columns).max()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [5, 10]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_max(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.max("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_max`: >>> agnostic_max(df_pd) a 0 2 >>> agnostic_max(df_pl) shape: (1, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 2 │ └─────┘ >>> agnostic_max(df_pa) pyarrow.Table a: int64 ---- a: [[2]] )rrpmaxr~s r_rrt rrac8ttj|S)uGet the mean value. Note: Syntactic sugar for ``nw.col(columns).mean()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 8, 3]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe agnostic function: >>> def agnostic_mean(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.mean("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_mean`: >>> agnostic_mean(df_pd) a 0 4.0 >>> agnostic_mean(df_pl) shape: (1, 1) ┌─────┐ │ a │ │ --- │ │ f64 │ ╞═════╡ │ 4.0 │ └─────┘ >>> agnostic_mean(df_pa) pyarrow.Table a: double ---- a: [[4]] )rrpmeanr~s r_rr sj bggw' ((rac8ttj|S)uGet the median value. Notes: - Syntactic sugar for ``nw.col(columns).median()`` - Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median. Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [4, 5, 2]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe agnostic function: >>> def agnostic_median(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.median("a")).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `agnostic_median`: >>> agnostic_median(df_pd) a 0 4.0 >>> agnostic_median(df_pl) shape: (1, 1) ┌─────┐ │ a │ │ --- │ │ f64 │ ╞═════╡ │ 4.0 │ └─────┘ >>> agnostic_median(df_pa) pyarrow.Table a: double ---- a: [[4]] )rrpmedianr~s r_rr sn bii) **rac8ttj|S)uSum all values. Note: Syntactic sugar for ``nw.col(columns).sum()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_sum(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.sum("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_sum`: >>> agnostic_sum(df_pd) a 0 3 >>> agnostic_sum(df_pl) shape: (1, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 3 │ └─────┘ >>> agnostic_sum(df_pa) pyarrow.Table a: int64 ---- a: [[3]] )rrpsumr~s r_rr rrac8ttj|S)uSum all values horizontally across columns. Warning: Unlike Polars, we support horizontal sum over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "b": [5, 10, None]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_sum_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.sum_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_sum_horizontal`: >>> agnostic_sum_horizontal(df_pd) a 0 6.0 1 12.0 2 3.0 >>> agnostic_sum_horizontal(df_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 6 │ │ 12 │ │ 3 │ └─────┘ >>> agnostic_sum_horizontal(df_pa) pyarrow.Table a: int64 ---- a: [[6,12,3]] )rrpsum_horizontalexprss r_rrV sr b''/ 00rac8ttj|S)u2 Compute the bitwise AND horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data).convert_dtypes(dtype_backend="pyarrow") >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_all_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("a", "b", all=nw.all_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_all_horizontal`: >>> agnostic_all_horizontal(df_pd) a b all 0 False False False 1 False True False 2 True True True 3 True 4 False False 5 >>> agnostic_all_horizontal(df_pl) shape: (6, 3) ┌───────┬───────┬───────┐ │ a ┆ b ┆ all │ │ --- ┆ --- ┆ --- │ │ bool ┆ bool ┆ bool │ ╞═══════╪═══════╪═══════╡ │ false ┆ false ┆ false │ │ false ┆ true ┆ false │ │ true ┆ true ┆ true │ │ true ┆ null ┆ null │ │ false ┆ null ┆ false │ │ null ┆ null ┆ null │ └───────┴───────┴───────┘ >>> agnostic_all_horizontal(df_pa) pyarrow.Table a: bool b: bool all: bool ---- a: [[false,false,true,true,false,null]] b: [[false,true,true,null,null,null]] all: [[false,false,true,null,false,null]] )rrpall_horizontalrs r_rr H b''/ 00rac8ttj|S)u/ Compute the bitwise OR horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data).convert_dtypes(dtype_backend="pyarrow") >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_any_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("a", "b", any=nw.any_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_any_horizontal`: >>> agnostic_any_horizontal(df_pd) a b any 0 False False False 1 False True True 2 True True True 3 True True 4 False 5 >>> agnostic_any_horizontal(df_pl) shape: (6, 3) ┌───────┬───────┬───────┐ │ a ┆ b ┆ any │ │ --- ┆ --- ┆ --- │ │ bool ┆ bool ┆ bool │ ╞═══════╪═══════╪═══════╡ │ false ┆ false ┆ false │ │ false ┆ true ┆ true │ │ true ┆ true ┆ true │ │ true ┆ null ┆ true │ │ false ┆ null ┆ null │ │ null ┆ null ┆ null │ └───────┴───────┴───────┘ >>> agnostic_any_horizontal(df_pa) pyarrow.Table a: bool b: bool any: bool ---- a: [[false,false,true,true,false,null]] b: [[false,true,true,null,null,null]] any: [[false,true,true,true,null,null]] )rrpany_horizontalrs r_rr rrac8ttj|S)uaCompute the mean of all values horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function that computes the horizontal mean of "a" and "b" columns: >>> def agnostic_mean_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.mean_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_mean_horizontal`: >>> agnostic_mean_horizontal(df_pd) a 0 2.5 1 6.5 2 3.0 >>> agnostic_mean_horizontal(df_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ f64 │ ╞═════╡ │ 2.5 │ │ 6.5 │ │ 3.0 │ └─────┘ >>> agnostic_mean_horizontal(df_pa) pyarrow.Table a: double ---- a: [[2.5,6.5,3]] )rrpmean_horizontalrs r_rr sx b((%0 11rac8ttj|S)uIGet the minimum value horizontally across columns. Notes: We support `min_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } We define a dataframe-agnostic function that computes the horizontal min of "a" and "b" columns: >>> def agnostic_min_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.min_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_min_horizontal`: >>> agnostic_min_horizontal(pd.DataFrame(data)) a 0 1.0 1 5.0 2 3.0 >>> agnostic_min_horizontal(pl.DataFrame(data)) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 5 │ │ 3 │ └─────┘ >>> agnostic_min_horizontal(pa.table(data)) pyarrow.Table a: int64 ---- a: [[1,5,3]] )rrpmin_horizontalrs r_rr_ x b''/ 00rac8ttj|S)uIGet the maximum value horizontally across columns. Notes: We support `max_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } We define a dataframe-agnostic function that computes the horizontal max of "a" and "b" columns: >>> def agnostic_max_horizontal(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.max_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_max_horizontal`: >>> agnostic_max_horizontal(pd.DataFrame(data)) a 0 4.0 1 8.0 2 3.0 >>> agnostic_max_horizontal(pl.DataFrame(data)) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 4 │ │ 8 │ │ 3 │ └─────┘ >>> agnostic_max_horizontal(pa.table(data)) pyarrow.Table a: int64 ---- a: [[4,8,3]] )rrpmax_horizontalrs r_rr rraverticalhowcyr\rfr^rs r_concatr  racyr\rfrs r_rr rracBttj||S)u^Concatenate multiple DataFrames, LazyFrames into a single entity. Arguments: items: DataFrames, LazyFrames to concatenate. how: concatenating strategy: - vertical: Concatenate vertically. Column names must match. - horizontal: Concatenate horizontally. If lengths don't match, then missing rows are filled with null values. - diagonal: Finds a union between the column schemas and fills missing column values with null. Returns: A new DataFrame, Lazyframe resulting from the concatenation. Raises: TypeError: The items to concatenate should either all be eager, or all lazy Examples: Let's take an example of vertical concatenation: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data_1 = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> data_2 = {"a": [5, 2], "b": [1, 4]} >>> df_pd_1 = pd.DataFrame(data_1) >>> df_pd_2 = pd.DataFrame(data_2) >>> df_pl_1 = pl.DataFrame(data_1) >>> df_pl_2 = pl.DataFrame(data_2) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def agnostic_vertical_concat(df1, df2): ... return nw.concat([df1, df2], how="vertical") >>> agnostic_vertical_concat(df_pd_1, df_pd_2) a b 0 1 4 1 2 5 2 3 6 0 5 1 1 2 4 >>> agnostic_vertical_concat(df_pl_1, df_pl_2) shape: (5, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ Let's look at case a for horizontal concatenation: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data_1 = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> data_2 = {"c": [5, 2], "d": [1, 4]} >>> df_pd_1 = pd.DataFrame(data_1) >>> df_pd_2 = pd.DataFrame(data_2) >>> df_pl_1 = pl.DataFrame(data_1) >>> df_pl_2 = pl.DataFrame(data_2) Defining a dataframe-agnostic function: >>> @nw.narwhalify ... def agnostic_horizontal_concat(df1, df2): ... return nw.concat([df1, df2], how="horizontal") >>> agnostic_horizontal_concat(df_pd_1, df_pd_2) a b c d 0 1 4 5.0 1.0 1 2 5 2.0 4.0 2 3 6 NaN NaN >>> agnostic_horizontal_concat(df_pl_1, df_pl_2) shape: (3, 4) ┌─────┬─────┬──────┬──────┐ │ a ┆ b ┆ c ┆ d │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪══════╪══════╡ │ 1 ┆ 4 ┆ 5 ┆ 1 │ │ 2 ┆ 5 ┆ 2 ┆ 4 │ │ 3 ┆ 6 ┆ null ┆ null │ └─────┴─────┴──────┴──────┘ Let's look at case a for diagonal concatenation: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data_1 = {"a": [1, 2], "b": [3.5, 4.5]} >>> data_2 = {"a": [3, 4], "z": ["x", "y"]} >>> df_pd_1 = pd.DataFrame(data_1) >>> df_pd_2 = pd.DataFrame(data_2) >>> df_pl_1 = pl.DataFrame(data_1) >>> df_pl_2 = pl.DataFrame(data_2) Defining a dataframe-agnostic function: >>> @nw.narwhalify ... def agnostic_diagonal_concat(df1, df2): ... return nw.concat([df1, df2], how="diagonal") >>> agnostic_diagonal_concat(df_pd_1, df_pd_2) a b z 0 1 3.5 NaN 1 2 4.5 NaN 0 3 NaN x 1 4 NaN y >>> agnostic_diagonal_concat(df_pl_1, df_pl_2) shape: (4, 3) ┌─────┬──────┬──────┐ │ a ┆ b ┆ z │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞═════╪══════╪══════╡ │ 1 ┆ 3.5 ┆ null │ │ 2 ┆ 4.5 ┆ null │ │ 3 ┆ null ┆ x │ │ 4 ┆ null ┆ y │ └─────┴──────┴──────┘ r)rrprrs r_rr sX bii3/ 00ra separatorrcHttj|g|||dS)uI Horizontally concatenate columns into a single string column. Arguments: exprs: Columns to concatenate into a single string column. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. Non-`String` columns are cast to `String`. *more_exprs: Additional columns to concatenate into a single string column, specified as positional arguments. separator: String that will be used to separate the values of each column. ignore_nulls: Ignore null values (default is `False`). If set to `False`, null values will be propagated and if the row contains any null values, the output is null. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3], ... "b": ["dogs", "cats", None], ... "c": ["play", "swim", "walk"], ... } We define a dataframe-agnostic function that computes the horizontal string concatenation of different columns >>> def agnostic_concat_str(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.concat_str( ... [ ... nw.col("a") * 2, ... nw.col("b"), ... nw.col("c"), ... ], ... separator=" ", ... ).alias("full_sentence") ... ).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_concat_str`: >>> agnostic_concat_str(pd.DataFrame(data)) full_sentence 0 2 dogs play 1 4 cats swim 2 None >>> agnostic_concat_str(pl.DataFrame(data)) shape: (3, 1) ┌───────────────┐ │ full_sentence │ │ --- │ │ str │ ╞═══════════════╡ │ 2 dogs play │ │ 4 cats swim │ │ null │ └───────────────┘ >>> agnostic_concat_str(pa.table(data)) pyarrow.Table full_sentence: string ---- full_sentence: [["2 dogs play","4 cats swim",null]] r)rrp concat_str)rrr more_exprss r_rr| s*\  eYjYILY rac2eZdZeddZdfd ZxZS)rc ||jSr\) _predicates)clsrs r_ from_whenzWhen.from_when sD$$%%racHtjt| |Sr\)r from_thenr}thenr^rfr~s r_rz When.then s~~egl5122ra)rNwWhenrrT)rfrrr)rrr classmethodrrrrs@r_rr s&&33rarc2eZdZeddZdfd ZxZS)rc&||jSr\)r )rrs r_rzThen.from_then s4**++rac4tt| |Sr\)rr} otherwisers r_rzThen.otherwise s%'+E233ra)rNwThenrrT)rfrrr)rrrrrrrrs@r_rr s,,44rarc8tjt|S)u Start a `when-then-otherwise` expression. Expression similar to an `if-else` statement in Python. Always initiated by a `pl.when().then()`, and optionally followed by chaining one or more `.when().then()` statements. Chained when-then operations should be read as Python `if, elif, ... elif` blocks, not as `if, if, ... if`, i.e. the first condition that evaluates to `True` will be picked. If none of the conditions are `True`, an optional `.otherwise()` can be appended at the end. If not appended, and none of the conditions are `True`, `None` will be returned. Arguments: predicates: Condition(s) that must be met in order to apply the subsequent statement. Accepts one or more boolean expressions, which are implicitly combined with `&`. String input is parsed as a column name. Returns: A "when" object, which `.then` can be called on. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "b": [5, 10, 15]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def agnostic_when_then_otherwise(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.when(nw.col("a") < 3).then(5).otherwise(6).alias("a_when") ... ).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_when_then_otherwise`: >>> agnostic_when_then_otherwise(df_pd) a b a_when 0 1 5 5 1 2 10 5 2 3 15 6 >>> agnostic_when_then_otherwise(df_pl) shape: (3, 3) ┌─────┬─────┬────────┐ │ a ┆ b ┆ a_when │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i32 │ ╞═════╪═════╪════════╡ │ 1 ┆ 5 ┆ 5 │ │ 2 ┆ 10 ┆ 5 │ │ 3 ┆ 15 ┆ 6 │ └─────┴─────┴────────┘ >>> agnostic_when_then_otherwise(df_pa) pyarrow.Table a: int64 b: int64 a_when: int64 ---- a: [[1,2,3]] b: [[5,10,15]] a_when: [[5,5,6]] )rrnw_when) predicatess r_rr sP >>':. //rac Ptt||||tjS)aInstantiate Narwhals Series from iterable (e.g. list or array). Arguments: name: Name of resulting Series. values: Values of make Series from. dtype: (Narwhals) dtype. If not provided, the native library may auto-infer it from `values`. native_namespace: The native library to use for DataFrame creation. Returns: A new Series Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT, IntoSeriesT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function: >>> def agnostic_new_series(df_native: IntoFrameT) -> IntoSeriesT: ... values = [4, 1, 2, 3] ... native_namespace = nw.get_native_namespace(df_native) ... return nw.new_series( ... name="a", ... values=values, ... dtype=nw.Int32, ... native_namespace=native_namespace, ... ).to_native() We can then pass any supported eager library, such as pandas / Polars / PyArrow: >>> agnostic_new_series(pd.DataFrame(data)) 0 4 1 1 2 2 3 3 Name: a, dtype: int32 >>> agnostic_new_series(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: 'a' [i32] [ 4 1 2 3 ] >>> agnostic_new_series(pa.table(data)) [ [ 4, 1, 2, 3 ] ] native_namespacer@)rrrIr)rr_r{rs r_ new_seriesr,s-F    -JJ   rac.tt||S)aConstruct a DataFrame from an object which supports the PyCapsule Interface. Arguments: native_frame: Object which implements `__arrow_c_stream__`. native_namespace: The native library to use for DataFrame creation. Returns: A new DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function which creates a PyArrow Table. >>> def agnostic_to_arrow(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return nw.from_arrow(df, native_namespace=pa).to_native() Let's see what happens when passing pandas / Polars input: >>> agnostic_to_arrow(pd.DataFrame(data)) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] >>> agnostic_to_arrow(pl.DataFrame(data)) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] r)r nw_from_arrow) native_framers r_r!r!zsX l5EF rarcNtt|||tjS)uInstantiate DataFrame from dictionary. Indexes (if present, for pandas-like backends) are aligned following the [left-hand-rule](../pandas_like_concepts/pandas_index.md/). Notes: For pandas-like dataframes, conversion to schema is applied after dataframe creation. Arguments: data: Dictionary to create DataFrame from. schema: The DataFrame schema as Schema or dict of {name: type}. native_namespace: The native library to use for DataFrame creation. Only necessary if inputs are not Narwhals Series. Returns: A new DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's create a new dataframe of the same class as the dataframe we started with, from a dict of new data: >>> def agnostic_from_dict(df_native: IntoFrameT) -> IntoFrameT: ... new_data = {"c": [5, 2], "d": [1, 4]} ... native_namespace = nw.get_native_namespace(df_native) ... return nw.from_dict(new_data, native_namespace=native_namespace).to_native() Let's see what happens when passing pandas, Polars or PyArrow input: >>> agnostic_from_dict(pd.DataFrame(data)) c d 0 5 1 1 2 4 >>> agnostic_from_dict(pl.DataFrame(data)) shape: (2, 2) ┌─────┬─────┐ │ c ┆ d │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ >>> agnostic_from_dict(pa.table(data)) pyarrow.Table c: int64 d: int64 ---- c: [[5,2]] d: [[1,4]] r)rrrIrdataschemars r_ from_dictrs*~   -JJ   racNtt|||tjS)uuConstruct a DataFrame from a NumPy ndarray. Notes: Only row orientation is currently supported. For pandas-like dataframes, conversion to schema is applied after dataframe creation. Arguments: data: Two-dimensional data represented as a NumPy ndarray. schema: The DataFrame schema as Schema, dict of {name: type}, or a list of str. native_namespace: The native library to use for DataFrame creation. Returns: A new DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> import numpy as np >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2], "b": [3, 4]} Let's create a new dataframe of the same class as the dataframe we started with, from a NumPy ndarray of new data: >>> def agnostic_from_numpy(df_native: IntoFrameT) -> IntoFrameT: ... new_data = np.array([[5, 2, 1], [1, 4, 3]]) ... df = nw.from_native(df_native) ... native_namespace = nw.get_native_namespace(df) ... return nw.from_numpy(new_data, native_namespace=native_namespace).to_native() Let's see what happens when passing pandas, Polars or PyArrow input: >>> agnostic_from_numpy(pd.DataFrame(data)) column_0 column_1 column_2 0 5 2 1 1 1 4 3 >>> agnostic_from_numpy(pl.DataFrame(data)) shape: (2, 3) ┌──────────┬──────────┬──────────┐ │ column_0 ┆ column_1 ┆ column_2 │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞══════════╪══════════╪══════════╡ │ 5 ┆ 2 ┆ 1 │ │ 1 ┆ 4 ┆ 3 │ └──────────┴──────────┴──────────┘ >>> agnostic_from_numpy(pa.table(data)) pyarrow.Table column_0: int64 column_1: int64 column_2: int64 ---- column_0: [[5,1]] column_1: [[2,4]] column_2: [[1,3]] Let's specify the column names: >>> def agnostic_from_numpy(df_native: IntoFrameT) -> IntoFrameT: ... new_data = np.array([[5, 2, 1], [1, 4, 3]]) ... schema = ["c", "d", "e"] ... df = nw.from_native(df_native) ... native_namespace = nw.get_native_namespace(df) ... return nw.from_numpy( ... new_data, native_namespace=native_namespace, schema=schema ... ).to_native() Let's see the modified outputs: >>> agnostic_from_numpy(pd.DataFrame(data)) c d e 0 5 2 1 1 1 4 3 >>> agnostic_from_numpy(pl.DataFrame(data)) shape: (2, 3) ┌─────┬─────┬─────┐ │ c ┆ d ┆ e │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ 5 ┆ 2 ┆ 1 │ │ 1 ┆ 4 ┆ 3 │ └─────┴─────┴─────┘ >>> agnostic_from_numpy(pa.table(data)) pyarrow.Table c: int64 d: int64 e: int64 ---- c: [[5,1]] d: [[2,4]] e: [[1,3]] Let's modify the function so that it specifies the schema: >>> def agnostic_from_numpy(df_native: IntoFrameT) -> IntoFrameT: ... new_data = np.array([[5, 2, 1], [1, 4, 3]]) ... schema = {"c": nw.Int16(), "d": nw.Float32(), "e": nw.Int8()} ... df = nw.from_native(df_native) ... native_namespace = nw.get_native_namespace(df) ... return nw.from_numpy( ... new_data, native_namespace=native_namespace, schema=schema ... ).to_native() Let's see the outputs: >>> agnostic_from_numpy(pd.DataFrame(data)) c d e 0 5 2.0 1 1 1 4.0 3 >>> agnostic_from_numpy(pl.DataFrame(data)) shape: (2, 3) ┌─────┬─────┬─────┐ │ c ┆ d ┆ e │ │ --- ┆ --- ┆ --- │ │ i16 ┆ f32 ┆ i8 │ ╞═════╪═════╪═════╡ │ 5 ┆ 2.0 ┆ 1 │ │ 1 ┆ 4.0 ┆ 3 │ └─────┴─────┴─────┘ >>> agnostic_from_numpy(pa.table(data)) pyarrow.Table c: int16 d: float e: int8 ---- c: [[5,1]] d: [[2,4]] e: [[1,3]] r)rrrIrrs r_ from_numpyrs*V   -JJ   rac 0tt|fd|i|S)uRead a CSV file into a DataFrame. Arguments: source: Path to a file. native_namespace: The native library to use for DataFrame creation. kwargs: Extra keyword arguments which are passed to the native CSV reader. For example, you could use `nw.read_csv('file.csv', native_namespace=pd, engine='pyarrow')`. Returns: DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from types import ModuleType Let's create an agnostic function that reads a csv file with a specified native namespace: >>> def agnostic_read_csv(native_namespace: ModuleType) -> IntoDataFrame: ... return nw.read_csv("file.csv", native_namespace=native_namespace).to_native() Then we can read the file by passing pandas, Polars or PyArrow namespaces: >>> agnostic_read_csv(native_namespace=pd) # doctest:+SKIP a b 0 1 4 1 2 5 2 3 6 >>> agnostic_read_csv(native_namespace=pl) # doctest:+SKIP shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ └─────┴─────┘ >>> agnostic_read_csv(native_namespace=pa) # doctest:+SKIP pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] r)rrsourcerrds r_read_csvrs%l vK0@KFK rac 0tt|fd|i|S)uLazily read from a CSV file. For the libraries that do not support lazy dataframes, the function reads a csv file eagerly and then converts the resulting dataframe to a lazyframe. Arguments: source: Path to a file. native_namespace: The native library to use for DataFrame creation. kwargs: Extra keyword arguments which are passed to the native CSV reader. For example, you could use `nw.scan_csv('file.csv', native_namespace=pd, engine='pyarrow')`. Returns: LazyFrame. Examples: >>> import dask.dataframe as dd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> from types import ModuleType Let's create an agnostic function that lazily reads a csv file with a specified native namespace: >>> def agnostic_scan_csv(native_namespace: ModuleType) -> IntoFrame: ... return nw.scan_csv("file.csv", native_namespace=native_namespace).to_native() Then we can read the file by passing, for example, Polars or Dask namespaces: >>> agnostic_scan_csv(native_namespace=pl).collect() # doctest:+SKIP shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ └─────┴─────┘ >>> agnostic_scan_csv(native_namespace=dd).compute() # doctest:+SKIP a b 0 1 4 1 2 5 2 3 6 r)rrrs r_scan_csvrs%d vK0@KFK rac 0tt|fd|i|S)uRead into a DataFrame from a parquet file. Arguments: source: Path to a file. native_namespace: The native library to use for DataFrame creation. kwargs: Extra keyword arguments which are passed to the native parquet reader. For example, you could use `nw.read_parquet('file.parquet', native_namespace=pd, engine='pyarrow')`. Returns: DataFrame. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from types import ModuleType Let's create an agnostic function that reads a parquet file with a specified native namespace: >>> def agnostic_read_parquet(native_namespace: ModuleType) -> IntoDataFrame: ... return nw.read_parquet( ... "file.parquet", native_namespace=native_namespace ... ).to_native() Then we can read the file by passing pandas, Polars or PyArrow namespaces: >>> agnostic_read_parquet(native_namespace=pd) # doctest:+SKIP a b 0 1 4 1 2 5 2 3 6 >>> agnostic_read_parquet(native_namespace=pl) # doctest:+SKIP shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ └─────┴─────┘ >>> agnostic_read_parquet(native_namespace=pa) # doctest:+SKIP pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] r)rrrs r_ read_parquetrs%p 6O4DOO rac 0tt|fd|i|S)uLazily read from a parquet file. For the libraries that do not support lazy dataframes, the function reads a parquet file eagerly and then converts the resulting dataframe to a lazyframe. Arguments: source: Path to a file. native_namespace: The native library to use for DataFrame creation. kwargs: Extra keyword arguments which are passed to the native parquet reader. For example, you could use `nw.scan_parquet('file.parquet', native_namespace=pd, engine='pyarrow')`. Returns: LazyFrame. Examples: >>> import dask.dataframe as dd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> from types import ModuleType Let's create an agnostic function that lazily reads a parquet file with a specified native namespace: >>> def agnostic_scan_parquet(native_namespace: ModuleType) -> IntoFrame: ... return nw.scan_parquet( ... "file.parquet", native_namespace=native_namespace ... ).to_native() Then we can read the file by passing, for example, Polars or Dask namespaces: >>> agnostic_scan_parquet(native_namespace=pl).collect() # doctest:+SKIP shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ └─────┴─────┘ >>> agnostic_scan_parquet(native_namespace=dd).compute() # doctest:+SKIP a b 0 1 4 1 2 5 2 3 6 r)rr rs r_ scan_parquetr8s%h 6O4DOO ra)Mr(r)r*rr+r,r-r.r/rr0r1r2rHr3r4r5r6r7rr8r9r$r&r:r;r<r=r>r?r@rArrrrrrrrr'rr!rrrrJr"rCrKrxrzrrrLrMrNrOrPrrrr}rrnrrurrrrrr#rrrErDr)rzNwDataFrame[IntoFrameT]rzDataFrame[IntoFrameT])rzNwLazyFrame[IntoFrameT]rLazyFrame[IntoFrameT])rz NwSeries[Any]rr&)rr rr)rrrr)rzPNwDataFrame[IntoFrameT] | NwLazyFrame[IntoFrameT] | NwSeries[Any] | NwExpr | AnyrzCDataFrame[IntoFrameT] | LazyFrame[IntoFrameT] | Series | Expr | Any)rIntoDataFrameT | IntoSeriesTrrr rrrr rrrr"DataFrame[IntoDataFrameT] | Series)rrrrr rrrr rrrrr)rrErrr rrrr rrNonerDataFrame[IntoDataFrameT])rrYrrr rrrr rrrrrY)rrErrr rrrr rrrrr)rrYrrr rrrr rrrrrY)rIntoFrameT | IntoSeriesTrrr rrrr rrrr6DataFrame[IntoFrameT] | LazyFrame[IntoFrameT] | Series)rrGrrr rrrr rrrrr&)rrFrrr rrrr rrrr-DataFrame[IntoFrameT] | LazyFrame[IntoFrameT])rrYrrr rrrr rrrrrY)rrErrr rrrr rrrrr)rrErrr rrrr rrrrr)rrrrr rrrr rrrr(DataFrame[Any] | LazyFrame[Any] | Series)rzIntoSeriesT | Anyrrr rrrr rrrrr&)rrFrrr rrrr rrrrr)rrr+rr rrrr rrrrr)rrr+rr rrrr rrrrr)rrEr+rr rrrr rrrrr)rrYr+rr rrrr rrrrrY)rrEr+rr rrrr rrrrr)rrYr+rr rrrr rrrrrY)rrr+rr rrrr rrrrr)rrGr+rr rrrr rrrrr&)rrFr+rr rrrr rrrrr)rrYr+rr rrrr rrrrrY)rrEr+rr rrrr rrrrr)rrEr+rr rrrr rrrrr)rrr+rr rrrr rrrrr)rrGr+rr rrrr rrrrr&)rrFr+rr rrrr rrrrr)rrr+rr rrrr rr bool | Nonerr)rzIntoFrameT | IntoSeries | Trrr+rr rrrr rrrrz:LazyFrame[IntoFrameT] | DataFrame[IntoFrameT] | Series | T)rDrrrrrE)rDrrrrrF)rDr&rrrr)rDrrrrr)rDrr+rrrE)rDrr+rrrF)rDr&r+rrr)rDrr+rrr)rDrrrr+rrzIntoFrameT | Anyr\)rjzCallable[..., Any] | Nonerrr+rr rrrr rrrrrm)rr)rszstr | Iterable[str]rr)rvzint | Sequence[int]rr)rfrr{DType | type[DType] | Nonerr)rrrr)rIntoExpr | Iterable[IntoExpr]rr)r^zIterable[DataFrame[Any]]r-Literal['horizontal', 'vertical', 'diagonal']rr)r^zIterable[LazyFrame[Any]]rrrr)r^z)Iterable[DataFrame[Any] | LazyFrame[Any]]rrrzDataFrame[Any] | LazyFrame[Any]) rrrrWrrrrrr)rrrr) rrr_rr{rrrSrr&)rrVrrSrr)rzdict[str, Any]rz dict[str, DType] | Schema | NonerzModuleType | Nonerr)rz np.ndarrayrz,dict[str, DType] | Schema | list[str] | NonerrSrr)rrrrSrdrrr)rrrrSrdrrr) __future__r functoolsrtypingrrrr r r r r warningsrnarwhalsrprrrrTrrrr narwhals.exprrr rrrrrrnarwhals.functionsrrrrrrr r!rr"r#narwhals.schemar$NwSchemarUr&rnarwhals.stable.v1r'narwhals.stable.v1.dtypesr(r)r*r+r,r-r.r/r0r1r2r3r4r5r6r7r8r9r:r;r<r=r>r?r@rAnarwhals.translaterBrCrDnarwhals.typingrErFrGrrHrIrJrKrLrMrNrOrPrRtypesrSnumpynptyping_extensionsrTnarwhals.dtypesrUrVrWrXrYrrrErnrrrrurxrzr}rrrrrrrrrrrrrrrrrrr__all__rfrar_rs" !77((().//-1-1:(,..%+-1*.-.*+--*+++,*,,,+,,,--03+*&')"91,/*,*: &%8(* CLn- N+n-b T- J'T-nC  Xc]C  Lf 6f RX@ J J J J 1 1 ( ( $ $ YH. "%"% -/- - - - -  - -(- - 14"% -/- - - . -  - -(- - "%"%$!$ $ $ - $  $$$ $ "%"%      -         14"%$!$ $ $ . $  $$$ $ 14"%      .         "%03"% A+A A A . A  A A<A A "%03   .      "%03"%88 8 8 . 8  8838 8 "%03"%      .          !$"%$!$ $ $ - $  $$$ $  03"%$!$ $ $ . $  $$$ $  !$03"% 3+3 3 3 . 3  3 3.3 3  !$03$   .       !$03"%88 8 8 . 8  8838 8 "%"% $/$ $ $ - $  $ $$ $ 14"% -/- - - . -  - -(- - "%"%$!$ $ $ - $  $$$ $ "%"%      -         14"%$!$ $ $ . $  $$$ $ 14"%      .         "%03"% A+A A A . A  A A<A A "%03   .      "%03"%88 8 8 . 8  8838 8 "%03"%      .         $'!$"%$!$!$ $ - $  $$$ $ $'03"%$!$!$ $ . $  $$$ $ $'!$03"% 3+3!3 3 . 3  3 3.3 3 $'!$03!  .      $'!$03"%88!8 8 . 8  8838 8 ',   $      $&+ $N.N N N  N $ NNN@Nb KN.;H  GJ*7D  BER R @ @ RU.AO  NQ*=K  ILY Y F F  $ +K+ + +  +^'+ $&+ $ #     $ D5 p4&n7(t- `8,v5(p5(p5)p7+t5(p91xD1ND1N<2~<1~<1~ :D # 7   :D # 7  :DL1 4L1 7L1% L1d P (PPP P  Pf3634644H0\)-K K K &K ! K  K\.'.>H..f04F+/ F F ,F( F  FV<@R R 8R! R  Rj8 8&08