hh"%SSKJr SSKJr SSKJr SSKJr SSKJr SSKJ r SSKJ r SSKJ r SS KJ r SS KJ r SS KJr SS KJr SS KJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJ r SSKJ!r! SSK"J#r# SSK$J%r% SSK&J'r' SSK&J(r( SSK&J)r) SS K&J*r* SS!K&J+r+ SS"K&J,r, SS#K&J-r- SS$K&J.r. SS%K&J/r/ SS&K&J0r0 SS'K&J1r1 SS(K&J2r2 SS)K&J3r3 \(aSS*K4J5r5 SS+K6J7r7 SS,K8J9r9 SS-K:r;SS-Kr?SS.K@JArA SS/K@JBrB SS0K@JCrC SS1K@JDrD SS2KEJFrF SS3KEJGrG SS4KEJHrH SS5KIJJrJ SS6KKJLrL SS7KKJMrM SS8KNJOrO SS9KPJQrQ SS:KPJRrR SS;KPJSrS SSKPJVrV SS?KPJWrX SS@KPJYrZ SSAKPJ[r[ SSBKPJ\r\ SSCKPJ]r] SSDKPJ^r^ SSEKPJ_r_ SSFKPJ`r` \B"SG5ra\"SHSISJ9rb\"SKSISJ9rc\"SLSMSJ9rd\"SN5reSOrWSP\fSQ'SRrYSP\fSS'"STSU\ \b5rg"SVSW\g\d5rh"SXSY\g\c5rig-)Z) annotations)abstractmethod)chain) TYPE_CHECKING)Any)Callable)Generic)Iterable)Iterator)Literal)NoReturn)Sequence)TypeVar)overload)warn)ExprKind)all_exprs_are_scalar_like)!check_expressions_preserve_length) infer_kind)is_scalar_like) get_polars)is_numpy_array)ColumnNotFoundError)InvalidIntoExprError)LengthChangingExprError)OrderDependentExprError)Schema to_native)Implementation)find_stacklevel)flatten) generate_repr)is_compliant_dataframe)is_compliant_lazyframe)is_index_selector) is_list_of)is_sequence_like) is_slice_none)issue_deprecation_warning) parse_version)supports_arrow_c_stream)BytesIO)Path) ModuleTypeN) Concatenate) ParamSpec)Self) TypeAlias)CompliantDataFrame)CompliantLazyFrame)IntoCompliantExpr)EagerNamespaceAnyGroupBy LazyGroupBySeries)AsofJoinStrategy) IntoDataFrame)IntoExpr) IntoFrame) JoinStrategy)LazyUniqueKeepStrategy)MultiColSelector)MultiIndexSelector)PivotAgg)SingleColSelector)SingleIndexSelector)SizeUnit)UniqueKeepStrategy)_2DArrayPS_FrameTrA)boundFrameT DataFrameTr?Rz_MultiColSelector[Series[Any]]r3rDz _MultiIndexSelector[Series[Any]]rEc .\rSrSr%S\S'S\S'S(SjrS)SjrS*SjrS+S jr\ S,S j5r \ S-S j5r S-S jr S.S jrS/S0SjjrS1Sjr\ S2Sj5rS3SjrS3SjrS4SjrS5SjrS5SjrS6SjrS7SjrSSS.S8SjjrS9SSSS.S:SjjjrS;SS#jrS?S$jrS?S%jrS@S&jr S'r!g)A BaseFrame[r_compliant_frame&Literal['full', 'lazy', 'interchange']_levelc6URR5$N)rU__native_namespace__selfs D/var/www/html/env/lib/python3.13/site-packages/narwhals/dataframe.pyrZBaseFrame.__native_namespace___s$$99;;c6URR5$rY)rU__narwhals_namespace__r[s r]ra BaseFrame.__narwhals_namespace__bs$$;;==r_c4URXRS9$)Nlevel) __class__rW)r\dfs r]_with_compliantBaseFrame._with_compliantes~~b ~44r_cp/n/n[U5H>nURU5nURU5 UR[USS95 M@ UR 5HOupuURU5R U5nURU5 UR[USS95 MQ X44$)zjProcess `args` and `kwargs`, extracting underlying objects as we go, interpreting strings as column names.F) str_as_lit)r"_extract_compliantappendritemsalias)r\exprs named_exprs out_exprs out_kindsexprcompliant_exprros r]_flatten_and_extractBaseFrame._flatten_and_extractis  END!44T:N   ^ ,   Z? @#',,.KE!44T:@@GN   ^ ,   Z? @/##r_c[erYNotImplementedError)r\args r]rlBaseFrame._extract_compliantys!!r_c\[URRR55$rY)rrUschemarnr[s r]r~BaseFrame.schema}s"d++2288:;;r_c^[URR55n[U5$rY)dictrUcollect_schemar)r\ native_schemas r]rBaseFrame.collect_schemas&T22AACD m$$r_cU"U/UQ70UD6$rY)r\functionargskwargss r]pipeBaseFrame.pipes .t.v..r_cVURURRU55$rY)rhrUwith_row_indexr\names r]rBaseFrame.with_row_indexs$##D$9$9$H$H$NOOr_c[U[5(aU/OUnURURR US95$)Nsubset) isinstancestrrhrU drop_nulls)r\rs r]rBaseFrame.drop_nullss<'44&&##D$9$9$D$DF$D$STTr_c.URR$rY)rUcolumnsr[s r]rBaseFrame.columnss$$,,,r_cUR"U0UD6up4[X45VVs/sH(upV[U5(aURU5OUPM* nnnUR UR R "U65$s snnfrY)rvzipr broadcastrhrU with_columns)r\rprqcompliant_exprskindsrukinds r]rBaseFrame.with_columnss"&!:!:E!Q[!Q),O(C (C$/=T.B.BN $ $T * V(C  ##D$9$9$F$F$XYY  s/A=c[[U55nU(aG[SU55(a0U(d)URURR "U65$UR"U0UD6upU(a8[U0UD6(a(URURR"U65$[X5V V s/sH(up[U 5(aU RU 5OU PM* nn n URURR "U65$![ aGnURnUVs/sH ofU;dM UPM Os snfnn[R"Xu5UeSnAff=fs sn n f)Nc3B# UHn[U[5v M g7frY)rr).0xs r] #BaseFrame.select..sE*QjC00*s)tupler"allrhrU simple_select Exceptionrr'from_missing_and_available_column_namesrvr aggregaterrrselect) r\rprq flat_exprseavailable_columnsrmissing_columnsrrrurs r]rBaseFrame.selects] 75>* #E*EEEk ++))77D"&!:!:J!V+!V 8*T T''(=(=(G(G(YZ Z),O(C (C$/=T.B.BN $ $T * V(C  ##D$9$9$@$@/$RSS $(LL!.8"WjEV$>q$ABBr_cVURURRU55$rY)rhrUtailrs r]rBaseFrame.tailrr_cRURURRX!S95$)Nstrict)rhrUdrop)r\rrs r]rBaseFrame.drops'##D$9$9$>$>w$>$VWWr_c^^ [U5S:Xa[US[5(aUSnOpSSKJm [ U5n[ USS06 UR5m UR"U6upVUU 4SjUR55nT R"[XW56nURURRU55$)Nr)col function_namefilterc3\># UH!upT"U5U:HRT5v M# g7frY)_to_compliant_expr)rrvrplxs r]r#BaseFrame.filter..s0%2GDTa33C882s),)lenr'boolnarwhals.functionsrr"rrarvrnall_horizontalrrhrUr) r\ predicates constraints predicateflat_predicatescompliant_predicates_kindscompliant_constraintsrrs @@r]rBaseFrame.filters z?a Jz!}d$C$C"1 I .%j1O - Wh W--/C+/+D+Do+V ( %*002% !**+CI##D$9$9$@$@$KLLr_F descending nulls_lastc[/[U/5QUQ5nURURR"XUS.65$)Nr)r"rhrUsort)r\byrrmore_bys r]rBaseFrame.sortsH/wt}/w/ 0##  ! ! & &j Y  r_N_rightleft_onright_onsuffixc [U[5(aU/OUn[U[5(aU/OUn[U[5(aU/OUnUS=n;aSUSUS3n[U5eUS:XaUcUcUb Sn[U5eUS:waUcUbUcSUS3n[U5eUS:waUbUcUbS US3n[U5eUbU=pEUR UR R URU5UUUUS 95$) N)innerleftfullcrossantisemiz2Only the following join strategies are supported: ; found ''.rz>Can not pass `left_on`, `right_on` or `on` keys for cross joinzGEither (`left_on` and `right_on`) or `on` keys should be specified for .zBIf `on` is specified, `left_on` and `right_on` should be None for )howrrr)rrrz ValueErrorrhrUjoinrl) r\otheronrrrr_supported_joinsmsgs r]rBaseFrame.joinsT C((bTb)'3777)W!+Hc!:!:H:  R R  GGWFXXabeaffhiC%c* * '>  8#72>RCS/ ! '>rzw(BR[\_[``abCS/ ! '> N 3x7KVWZV[[\]CS/ ! >!# #G##  ! ! & &''.! '   r_cRURURRXS95$)Nroffset)rhrU gather_every)r\rrs r]rBaseFrame.gather_everys,##  ! ! . . . B  r_backwardrrrby_leftby_rightrstrategyrc Sn X;aSU SUS3n [U 5eUcUbUc Sn [U 5eUbUcUb Sn [U 5eUcUcUcUbUc Sn [U 5eUbUcUb Sn [U 5eUbU=p#UbU=pV[U[5(aU/n[U[5(aU/nUR UR R URU5UUUUUU S 95$) N)rforwardnearestz-Only the following strategies are supported: rrzCEither (`left_on` and `right_on`) or `on` keys should be specified.z>If `on` is specified, `left_on` and `right_on` should be None.zGCan not specify only `by_left` or `by_right`, you need to specify both.z>If `by` is specified, `by_left` and `by_right` should be None.)rrrrrr)rzrrrrhrU join_asofrl) r\rrrrrrrrr_supported_strategiesrs r]r BaseFrame.join_asof$sN!C  0ABWAXXabjakkmnC%c* * JW_0@WCS/ ! N!48LRCS/ ! J _!5#(8Z S/ ! N!48LRCS/ ! >!# #G >!# #G gs # #iG h $ $ zH##  ! ! + +''.!!! ,   r_c [U[5(aU/OUn[U[5(aU/OUnURURR XX4S95$)Nrindex variable_name value_name)rrrhrUunpivot)r\rrrrs r]rBaseFrame.unpivot\s_ C((bTb%eS11u##  ! ! ) )- *   r_cSn[U5e)NzDataFrame.__neq__ and LazyFrame.__neq__ are not implemented, please use expressions instead. Hint: instead of df != 0 you may want to use df.select(nw.all() != 0)ryr\rrs r]__neq__BaseFrame.__neq__m + "#&&r_cSn[U5e)NzDataFrame.__eq__ and LazyFrame.__eq__ are not implemented, please use expressions instead. Hint: instead of df == 0 you may want to use df.select(nw.all() == 0)ryrs r]__eq__BaseFrame.__eq__xrr_c[U[5(aU/UQO/UQUQnURURR US95$)Nr)rrrhrUexplode)r\r more_columns to_explodes r]rBaseFrame.explodesW'3'' $| $*7*\*  ##D$9$9$A$A*$A$UVVr_r)returnr/)r!r)rgrr!r2)rpIntoExpr | Iterable[IntoExpr]rqr@r!z8tuple[list[IntoCompliantExpr[Any, Any]], list[ExprKind]]r{rr!rr!rrz"Callable[Concatenate[Self, PS], R]rzPS.argsrz PS.kwargsr!rQrrrr!r2rstr | list[str] | Noner!r2r!z list[str]rpr"rqr@r!r2rzdict[str, str]r!r2rintr!r2)rz Iterable[str]rrr!r2rz*IntoExpr | Iterable[IntoExpr] | list[bool]rrr!r2 rstr | Iterable[str]rrrzbool | Sequence[bool]rrr!r2Nrrr2rr)rrBrr)rr)rrr!r2rrr.rr.r!r2rr2r str | Nonerr7rr7rr)rr)rr)rr>rrr!r2 rr)rr)rrrrr!r2)robjectr!r rzstr | Sequence[str]rrr!r2)"__name__ __module__ __qualname____firstlineno____annotations__rZrarhrvrrlpropertyr~rrrrrrrrrrrrrrrr rrrr__static_attributes__rr_r]rSrS[s 22<>5$3$DL$ A$ ""<<% /4// / /PU--Z3ZDLZ ZT-T T  T8KCCXM?MM  M6-2      *      &*# / +/+// /  #/  / ( / )/ /  / b ##*.+/%)%/6 6  6  6  6 (6 )6  #6 #6 6  6 p " &        " ' 'Wr_rSc N^\rSrSrSrSbSjr\ScSj5r\SdSj5rSeSjr \SfSj5r SgSjr ShSiS jjr SjS jr SkSlS jjrSkSmS jjrSnSjrSoSjrSpSjr\SkSqSjj5r\SrSj5rSkSsSjjrSrSjrStSjr\SuSj5rSvSjrSwSxSjjr\SySj5r\SzSj5r\S{Sj5rS|SjrS}Sjr\SS.S~S jj5r\SS!j5r\SS"j5rS#S.SS$jjrSS%jrSU4S&jjrSkSU4S'jjjrSSU4S(jjjr \SU4S)jj5r!SU4S*jjr"\SU4S+jj5r#\S,S-.SS.jj5r$\SS/j5r$\SS0j5r$S,S-.SS1jjr$SS2jr%\SS3.SS4jj5r&\SS3.SS5jj5r&\SS3.SS6jj5r&S,S7S8.SS9jjr&SU4S:jjr'SU4S;jjr(SU4S<jjr)SSU4S=jjjr*SSU4S>jjjr+S#S?.SU4S@jjjr,SkSAS,SB.SSCjjjr-SU4SDjjr.S,SE.SSFjjr/S,S,SG.SU4SHjjjr0SS S SISJ.SU4SKjjjjr1S S S S S S SLSISM.SU4SNjjjr2SSOjr3SSPjr4SSQjr5SSRjr6ShSSSjjr7SSTjr8SSU4SUjjjr9S S S S S,SVSW.SSXjjr:SSYjr;SkS S,S SZ.SS[jjjr<SkS S\S]S^.SU4S_jjjjr=SU4S`jjr>Sar?U=r@$) DataFrameia2Narwhals 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]}, backend=narwhals.get_native_namespace(another_object), ) ``` cSSKJn SSKJn UR 5n[ U[ 5(a UR$[ X5(aURR5$[ X5(aURUR 55$[ U[5(aURU5$[5b2S[[U55;aS[U5S3n[U5e[!U5(a'UR"R%XS9R5$[&R("[U55e)NrExprr<polarsExpected Narwhals object, got: [. Perhaps you: - Forgot a `nw.from_native` somewhere? - Used `pl.col` instead of `nw.col`?)context) narwhals.exprrFnarwhals.seriesr=rarrSrU_compliant_series_to_exprrrrrtype TypeErrorr_series from_numpyrfrom_invalid_type)r\r{rFr=rrs r]rlDataFrame._extract_compliants &*!%! c9 % %'' ' c " "((113 3 c ))$*E*E*GH H c3  773<  < #CS N(B1$s)=77  C. #  ;;))#);DDF F"44T#Y??r_cSSKJn U$)Nrr<)rLr=)r\r=s r]rQDataFrame._seriess * r_c[$rY) LazyFramer[s r] _lazyframeDataFrame._lazyframer_cX lU [U5(aUR5UlgS[ U53n[ U5e)NzCExpected an object which implements `__narwhals_dataframe__`, got: )rWr$__narwhals_dataframe__rUrOAssertionErrorr\rgrers r]__init__DataFrame.__init__sE>C  !" % %$&$=$=$?D !WX\]_X`WabC % %r_c.URR$)aGReturn implementation of native frame. This can be useful when you need to use special-casing 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 >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation >>> df.implementation.is_pandas() True >>> df.implementation.is_pandas_like() True >>> df.implementation.is_polars() False rU_implementationr[s r]implementationDataFrame.implementations0$$444r_c6URR5$rY)rU__len__r[s r]rhDataFrame.__len__s$$,,..r_Nc4URRXS9$)Ncopy)rU __array__)r\dtyperls r]rmDataFrame.__array__s$$..u.@@r_cR[SUR5R55$)NzNarwhals DataFramer#r__repr__r[s r]rrDataFrame.__repr__ 14>>3C3L3L3NOOr_c^URRn[U5(aURUS9$SSKn[U5S:aS[ U53n[ U5SeUR5nURUS9$![ anS[ U53n[ U5UeSnAff=f)a@Export a DataFrame via the Arrow PyCapsule Interface. - if the underlying dataframe implements the interface, it'll return that - else, it'll call `to_arrow` and then defer to PyArrow's implementation See [PyCapsule Interface](https://arrow.apache.org/docs/dev/format/CDataInterface/PyCapsuleInterface.html) for more. )requested_schemarNzRPyArrow>=14.0.0 is required for `DataFrame.__arrow_c_stream__` for object of type )r) rU _native_framer,__arrow_c_stream__pyarrowModuleNotFoundErrorrOr+to_arrow)r\rv native_framepaexcrpa_tables r]ryDataFrame.__arrow_c_stream__s,,:: "< 0 022DT2U U 4   w &fgklxgyfz{C%c* 4==?**` with `BACKEND` being `DASK`, `DUCKDB` or `POLARS`. - As a string: `"dask"`, `"duckdb"` or `"polars"` - Directly as a module `dask.dataframe`, `duckdb` or `polars`. Returns: A new LazyFrame. Examples: >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2], "b": [4, 6]}) >>> df = nw.from_native(df_native) If we call `df.lazy`, we get a `narwhals.LazyFrame` backed by a Polars LazyFrame. >>> df.lazy() # doctest: +SKIP ┌─────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------| || └─────────────────────────────┘ We can also pass DuckDB as the backend, and then we'll get a `narwhals.LazyFrame` backed by a `duckdb.DuckDBPyRelation`. >>> df.lazy(backend=nw.Implementation.DUCKDB) ┌──────────────────┐ |Narwhals LazyFrame| |------------------| |┌───────┬───────┐ | |│ a │ b │ | |│ int64 │ int64 │ | |├───────┼───────┤ | |│ 1 │ 4 │ | |│ 2 │ 6 │ | |└───────┴───────┘ | └──────────────────┘ Nz(Not-supported backend. Expected one of z or `None`, got )backendlazyrd) r from_backendDASKDUCKDBPOLARSrrYrUr)r\r lazy_backendsupported_lazy_backendsrs r]rDataFrame.lazy s~ 'tN4O4OPW4X     ! !  ! !#   # (S''>&??OP\~_ S/ !  ! ! & &| & >> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} ... ) Calling `to_native` on a Narwhals DataFrame returns the native object: >>> nw.from_native(df_native).to_native() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c )rUrxr[s r]rDataFrame.to_native\s*$$222r_c6URR5$)aConvert this DataFrame to a pandas DataFrame. Returns: A pandas DataFrame. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame( ... {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} ... ) >>> df = nw.from_native(df_native) >>> df.to_pandas() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c )rU to_pandasr[s r]rDataFrame.to_pandasss&$$..00r_c6URR5$)u#Convert this DataFrame to a polars DataFrame. Returns: A polars DataFrame. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> df = nw.from_native(df_native) >>> df.to_polars() shape: (2, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ f64 │ ╞═════╪═════╡ │ 1 ┆ 6.0 │ │ 2 ┆ 7.0 │ └─────┴─────┘ )rU to_polarsr[s r]rDataFrame.to_polarss,$$..00r_cgrYrr\files r] write_csvDataFrame.write_csvs36r_cgrYrrs r]rrs=@r_c8URRU5$)aWrite dataframe to comma-separated values (CSV) file. Arguments: file: String, path object or file-like object to which the dataframe will be written. If None, the resulting csv format is returned as a string. Returns: String or None. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} ... ) >>> df = nw.from_native(df_native) >>> df.write_csv() 'foo,bar,ham\n1,6.0,a\n2,7.0,b\n3,8.0,c\n' If we had passed a file name to `write_csv`, it would have been written to that file. )rUrrs r]rrs.$$..t44r_c:URRU5 g)aWrite dataframe to parquet file. Arguments: file: String, path object or file-like object to which the dataframe will be written. Returns: None. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> df = nw.from_native(df_native) >>> df.write_parquet("out.parquet") # doctest:+SKIP N)rU write_parquetrs r]rDataFrame.write_parquets" ++D1r_c6URRSSS9$)aFConvert this DataFrame to a NumPy ndarray. Returns: A NumPy ndarray array. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [1, 2], "bar": [6.5, 7.0]}) >>> df = nw.from_native(df_native) >>> df.to_numpy() array([[1. , 6.5], [2. , 7. ]]) Nrk)rUto_numpyr[s r]rDataFrame.to_numpys $$--d->>r_c.URR$)aGet the shape of the DataFrame. Returns: The shape of the dataframe as a tuple. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [1, 2]}) >>> df = nw.from_native(df_native) >>> df.shape (2, 1) )rUshaper[s r]rDataFrame.shapes$$***r_chURURRU5URS9$)aGet a single column by name. Arguments: name: The column name as a string. Returns: A Narwhals Series, backed by a native series. Notes: Although `name` is typed as `str`, pandas does allow non-string column names, and they will work when passed to this function if the `narwhals.DataFrame` is backed by a pandas dataframe with non-string columns. This function can only be used to extract a column by name, so there is no risk of ambiguity. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2]}) >>> df = nw.from_native(df_native) >>> df.get_column("a").to_native() 0 1 1 2 Name: a, dtype: int64 rd)rQrU get_columnrWrs r]rDataFrame.get_columns,4||D11<>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> df = nw.from_native(df_native) >>> df.estimated_size() 32 )unit)rUestimated_size)r\rs r]rDataFrame.estimated_sizes($$333>>r_cgrYrr\items r] __getitem__DataFrame.__getitem__(sWZr_cgrYrrs r]rr+sr_cgrYrrs r]rr0sr_c2SSKJn S[U5S3n[U[5(ao[ U5S:a Sn[ U5eU(a[US5(aSOUSn[ U5S:d[US5(aSOUSnUcUcU$OP[U5(aUnSnO;[U5(d[U[[45(aSnUnO [ U5e[U[5(a [ U5eURn[U[[45(af[U[5(aURXV5$[U[5(aUOURUnUR!U5n UbX$U $[XR5(a UR"n[Xb5(a UR"nUcUR%USS2U45$UcUR%XuSS245$UR%XuU45$) a|Extract column or slice of DataFrame. Arguments: item: How to slice dataframe. What happens depends on what is passed. It's easiest to explain by example. Suppose we have a Dataframe `df`: - `df['a']` extracts column `'a'` and returns a `Series`. - `df[0:2]` extracts the first two rows and returns a `DataFrame`. - `df[0:2, 'a']` extracts the first two rows from column `'a'` and returns a `Series`. - `df[0:2, 0]` extracts the first two rows from the first column and returns a `Series`. - `df[[0, 1], [0, 1, 2]]` extracts the first two rows and the first three columns and returns a `DataFrame` - `df[:, [0, 1, 2]]` extracts all rows from the first three columns and returns a `DataFrame`. - `df[:, ['a', 'c']]` extracts all rows and columns `'a'` and `'c'` and returns a `DataFrame`. - `df[['a', 'c']]` extracts all rows and columns `'a'` and `'c'` and returns a `DataFrame`. - `df[0: 2, ['a', 'c']]` extracts the first two rows and columns `'a'` and `'c'` and returns a `DataFrame` - `df[:, 0: 2]` extracts all rows from the first two columns and returns a `DataFrame` - `df[:, 'a': 'c']` extracts all rows and all columns positioned between `'a'` and `'c'` _inclusive_ and returns a `DataFrame`. For example, if the columns are `'a', 'd', 'c', 'b'`, then that would extract columns `'a'`, `'d'`, and `'c'`. Returns: A Narwhals Series, backed by a native series. Notes: - Integers are always interpreted as positions - Strings are always interpreted as column names. In contrast with Polars, pandas allows non-string column names. If you don't know whether the column name you're trying to extract is definitely a string (e.g. `df[df.columns[0]]`) then you should use `DataFrame.get_column` instead. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2]}) >>> df = nw.from_native(df_native) >>> df["a"].to_native() 0 1 1 2 Name: a, dtype: int64 rr<z2Unexpected type for `DataFrame.__getitem__`, got: z. Hints: - use `df.item` to select a single item. - Use `df[indices, :]` to select rows positionally. - Use `df.filter(mask)` to filter rows based on a boolean mask.zzTuples cannot be passed to DataFrame.__getitem__ directly. Hint: instead of `df[indices]`, did you mean `df[indices, :]`?Nr)rLr=rOrrrrPr)r&r(slicerrUr.rrrrMrh) r\rr=r tuple_msgrowsr compliantcol_nameseriess r]rr;s| +Ad MN N  dE " "4y1}U **#}T!W'='=447D!$i!m}T!W/E/Ed4PQ7G| t $ $DG d # #z$ 'E'EDGC. dC C. )) gSz * *$$$yy//",Wc":":w W@UH__X.F#'#36< ? ? d # #))D g & &//G <'' !W*(=> > ?'' '(:; ;##IGm$<==r_cXR;$rYr)r\keys r] __contains__DataFrame.__contains__sll""r_. as_seriescgrYrr\rs r]to_dictDataFrame.to_dictTWr_cgrYrrs r]rrsMPr_cgrYrrs r]rrs9>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"A": [1, 2], "fruits": ["banana", "apple"]}) >>> df = nw.from_native(df_native) >>> df.to_dict(as_series=False) {'A': [1, 2], 'fruits': ['banana', 'apple']} rrd)rUrrnrQrW)r\rrvalues r]rrs( #'"7"7"?"?'#@#%'##JC\\%{{\;;#  $$,,y,AA s%A4c8URRU5$)a/Get values at given row. !!! warning You should NEVER use this method to iterate over a DataFrame; if you require row-iteration you should strongly prefer use of iter_rows() instead. Arguments: index: Row number. Returns: A tuple of the values in the selected row. Notes: cuDF doesn't support this method. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"a": [1, 2], "b": [4, 5]}) >>> nw.from_native(df_native).row(1) (, ) )rUrow)r\rs r]r DataFrame.rows0$$((//r_c,>[TU]"U/UQ70UD6$)a+Pipe function call. Arguments: function: Function to apply. args: Positional arguments to pass to function. kwargs: Keyword arguments to pass to function. Returns: The original object with the function applied. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2], "ba": [4, 5]}) >>> nw.from_native(df_native).pipe( ... lambda _df: _df.select( ... [x for x in _df.columns if len(x) == 1] ... ).to_native() ... ) a 0 1 1 2 superrr\rrrrfs r]rDataFrame.pipes:w|H6t6v66r_c>[TU]US9$)aDrop rows that contain null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Returns: The original object with the rows removed that contained the null values. Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md) for reference. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"a": [1.0, None], "ba": [1.0, 2.0]}) >>> nw.from_native(df_native).drop_nulls().to_native() pyarrow.Table a: double ba: double ---- a: [[1]] ba: [[1]] rrrr\rrfs r]rDataFrame.drop_nullss6w!!00r_c">[TU]U5$)aInsert column which enumerates rows. Arguments: name: The name of the column as a string. The default is "index". Returns: The original object with the column added. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"a": [1, 2], "b": [4, 5]}) >>> nw.from_native(df_native).with_row_index().to_native() pyarrow.Table index: int64 a: int64 b: int64 ---- index: [[0,1]] a: [[1,2]] b: [[4,5]] rrr\rrfs r]rDataFrame.with_row_index+s.w%d++r_c>[TU]$)ahGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> nw.from_native(df_native).schema Schema({'foo': Int64, 'bar': Float64}) rr~r\rfs r]r~DataFrame.schemaDw~r_c >[TU]5$)arGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> nw.from_native(df_native).collect_schema() Schema({'foo': Int64, 'bar': Float64}) rrrs r]rDataFrame.collect_schemaTw%''r_c>[TU]$)aGet column names. Returns: The column names stored in a list. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> nw.from_native(df_native).columns ['foo', 'bar'] rrrs r]rDataFrame.columnscwr_FnamedcgrYrr\rs r]rDataFrame.rowsssORr_cgrYrrs r]rrvsEHr_cgrYrrs r]rryrr_c4URRUS9$)aReturns all data in the DataFrame as a list of rows of python-native values. Arguments: named: By default, each row is returned as a tuple of values given in the same order as the frame columns. Setting named=True will return rows of dictionaries instead. Returns: The data as a list of rows. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> nw.from_native(df_native).rows() [(1, 6.0), (2, 7.0)] r)rUrrs r]rr|s($$)))66r_c## URR5HnURXRS9v M g7f)uReturns an iterator over the columns of this DataFrame. Yields: A Narwhals Series, backed by a native series. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> iter_columns = nw.from_native(df_native).iter_columns() >>> next(iter_columns) ┌───────────────────────┐ | Narwhals Series | |-----------------------| |0 1 | |1 2 | |Name: foo, dtype: int64| └───────────────────────┘ >>> next(iter_columns) ┌─────────────────────────┐ | Narwhals Series | |-------------------------| |0 6.0 | |1 7.0 | |Name: bar, dtype: float64| └─────────────────────────┘ rdN)rU iter_columnsrQrW)r\rs r]rDataFrame.iter_columnss58++88:F,,v[[,9 9;s>A) buffer_sizecgrYrr\rrs r] iter_rowsDataFrame.iter_rowss%(r_cgrYrrs r]rrs$'r_cgrYrrs r]rrs @Cr_irrc4URRXS9$)a]Returns an iterator over the DataFrame of rows of python-native values. Arguments: named: By default, each row is returned as a tuple of values given in the same order as the frame columns. Setting named=True will return rows of dictionaries instead. buffer_size: Determines the number of rows that are buffered internally while iterating over the data. See https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.iter_rows.html Returns: An iterator over the DataFrame of rows. Notes: cuDF doesn't support this method. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]}) >>> iter_rows = nw.from_native(df_native).iter_rows() >>> next(iter_rows) (1, 6.0) >>> next(iter_rows) (2, 7.0) r)rUrrs r]rrs:$$..U.TTr_c$>[TU]"U0UD6$)aAdd columns to this DataFrame. Added columns will replace existing columns with the same name. Arguments: *exprs: Column(s) to add, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to add, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: DataFrame: A new DataFrame with the columns added. Note: Creating a new DataFrame using this method does not create a new copy of existing data. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2], "b": [0.5, 4.0]}) >>> ( ... nw.from_native(df_native) ... .with_columns((nw.col("a") * 2).alias("a*2")) ... .to_native() ... ) a b a*2 0 1 0.5 2 1 2 4.0 4 )rrr\rprqrfs r]rDataFrame.with_columnssFw#U:k::r_c$>[TU]"U0UD6$)uSelect columns from this DataFrame. Arguments: *exprs: Column(s) to select, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to select, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: The dataframe containing only the selected columns. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"a": [1, 2], "b": [3, 4]}) >>> nw.from_native(df_native).select("a", a_plus_1=nw.col("a") + 1) ┌──────────────────┐ |Narwhals DataFrame| |------------------| |pyarrow.Table | |a: int64 | |a_plus_1: int64 | |---- | |a: [[1,2]] | |a_plus_1: [[2,3]] | └──────────────────┘ )rrrs r]rDataFrame.selectsDw~u4 44r_c">[TU]U5$)aRename column names. Arguments: mapping: Key value pairs that map from old name to new name. Returns: The dataframe with the specified columns renamed. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, 2], "bar": [6, 7]}) >>> nw.from_native(df_native).rename({"foo": "apple"}).to_native() pyarrow.Table apple: int64 bar: int64 ---- apple: [[1,2]] bar: [[6,7]] rrr\rrfs r]rDataFrame.rename(s*w~g&&r_c">[TU]U5$)aGet the first `n` rows. Arguments: n: Number of rows to return. If a negative value is passed, return all rows except the last `abs(n)`. Returns: A subset of the dataframe of shape (n, n_columns). Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2], "b": [0.5, 4.0]}) >>> nw.from_native(df_native).head(1).to_native() a b 0 1 0.5 rrr\rrfs r]rDataFrame.head?s$w|Ar_c">[TU]U5$)umGet the last `n` rows. Arguments: n: Number of rows to return. If a negative value is passed, return all rows except the first `abs(n)`. Returns: A subset of the dataframe of shape (n, n_columns). Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2], "b": [0.5, 4.0]}) >>> nw.from_native(df_native).tail(1) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 1 2 4.0 | └──────────────────┘ rrrs r]rDataFrame.tailS,w|Ar_rc6>[TU]"[U5SU06$)agRemove columns from the dataframe. Returns: The dataframe with the specified columns removed. Arguments: *columns: Names of the columns that should be removed from the dataframe. strict: Validate that all column names exist in the schema and throw an exception if a column name does not exist in the schema. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [1, 2], "bar": [6.0, 7.0], "ham": ["a", "b"]} ... ) >>> nw.from_native(df_native).drop("ham").to_native() foo bar 0 1 6.0 1 2 7.0 rrrr"r\rrrfs r]rDataFrame.dropks,w|WW-=f==r_anykeepmaintain_ordercUS;aSSSU3n[U5e[U[5(aU/nURURR XUS95$)aDrop duplicate rows from this dataframe. Arguments: subset: Column name(s) to consider when identifying duplicate rows. keep: {'first', 'last', 'any', 'none'} Which of the duplicate rows to keep. * 'any': Does not give any guarantee of which row is kept. This allows more optimizations. * 'none': Don't keep duplicate rows. * 'first': Keep first unique row. * 'last': Keep last unique row. maintain_order: Keep the same order as the original DataFrame. This may be more expensive to compute. Returns: The dataframe with the duplicate rows removed. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [1, 2], "bar": ["a", "a"], "ham": ["b", "b"]} ... ) >>> nw.from_native(df_native).unique(["bar", "ham"]).to_native() foo bar ham 0 1 a b >rlastnonefirstz Expected )rrrrz, got: rrrrrhrUunique)r\rrrrs r]rDataFrame.uniqueslF 7 7<=WTFKCS/ ! fc " "XF##  ! ! ( (> ( Z  r_c$>[TU]"U0UD6$)aFilter the rows in the DataFrame based on one or more predicate expressions. The original order of the remaining rows is preserved. Arguments: *predicates: Expression(s) that evaluates to a boolean Series. Can also be a (single!) boolean list. **constraints: Column filters; use `name = value` to filter columns by the supplied value. Each constraint will behave the same as `nw.col(name).eq(value)`, and will be implicitly joined with the other filter conditions using &. Returns: The filtered dataframe. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]} ... ) Filter on one condition >>> nw.from_native(df_native).filter(nw.col("foo") > 1).to_native() foo bar ham 1 2 7 b 2 3 8 c Filter on multiple conditions with implicit `&` >>> nw.from_native(df_native).filter( ... nw.col("foo") < 3, nw.col("ham") == "a" ... ).to_native() foo bar ham 0 1 6 a Filter on multiple conditions with `|` >>> nw.from_native(df_native).filter( ... (nw.col("foo") == 1) | (nw.col("ham") == "c") ... ).to_native() foo bar ham 0 1 6 a 2 3 8 c Filter using `**kwargs` syntax >>> nw.from_native(df_native).filter(foo=2, ham="b").to_native() foo bar ham 1 2 7 b )rr)r\rrrfs r]rDataFrame.filterspw~z9[99r_drop_null_keysc^^SSKJm SSKJn SSKJm [ U5n[UU4SjU55(a Sn[U5eU"U/UQ7SU06$)asStart a group by operation. Arguments: *keys: Column(s) to group by. Accepts multiple columns names as a list. drop_null_keys: if True, then groups where any key is null won't be included in the result. Returns: GroupBy: Object which can be used to perform aggregations. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... { ... "a": ["a", "b", "a", "b", "c"], ... "b": [1, 2, 1, 3, 3], ... "c": [5, 4, 3, 2, 1], ... } ... ) Group by one column and compute the sum of another column >>> nw.from_native(df_native, eager_only=True).group_by("a").agg( ... nw.col("b").sum() ... ).sort("a").to_native() a b 0 a 2 1 b 5 2 c 3 Group by multiple columns and compute the max of another column >>> ( ... nw.from_native(df_native, eager_only=True) ... .group_by(["a", "b"]) ... .agg(nw.max("c")) ... .sort("a", "b") ... .to_native() ... ) a b c 0 a 1 5 1 b 2 4 2 b 3 2 3 c 3 1 rrEr8r<c3@># UHn[UTT45v M g7frYrrrrFr=s r]r%DataFrame.group_by..@iz!dF^,,i`group_by` with expression or Series keys is not (yet?) supported. Hint: instead of `df.group_by(nw.col('a'))`, use `df.group_by('a')`.r) rKrFnarwhals.group_byr9rLr=r"rrz)r\rkeysr9 flat_keysrrFr=s @@r]group_byDataFrame.group_bysVb '-*DM @i@ @ @W &c* *tGiGGGr_rc,>[TU]"U/UQ7X#S.6$)u4Sort the dataframe by the given columns. Arguments: by: Column(s) names to sort by. *more_by: Additional columns to sort by, specified as positional arguments. descending: Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans. nulls_last: Place null values last. Returns: The sorted dataframe. Note: Unlike Polars, it is not possible to specify a sequence of booleans for `nulls_last` in order to control per-column behaviour. Instead a single boolean is applied for all `by` columns. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame( ... {"foo": [2, 1], "bar": [6.0, 7.0], "ham": ["a", "b"]} ... ) >>> nw.from_native(df_native).sort("foo") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | foo bar ham | | 1 1 7.0 b | | 0 2 6.0 a | └──────────────────┘ rrrr\rrrrrfs r]rDataFrame.sort'sNw|BWWZWWr_rrc ">[TU]XXEX&S9$)uJoin in SQL-like fashion. Arguments: other: DataFrame to join with. on: Name(s) of the join columns in both DataFrames. If set, `left_on` and `right_on` should be None. how: Join strategy. * *inner*: Returns rows that have matching values in both tables. * *left*: Returns all rows from the left table, and the matched rows from the right table. * *full*: Returns all rows in both dataframes, with the suffix appended to the right join keys. * *cross*: Returns the Cartesian product of rows from both tables. * *semi*: Filter rows that have a match in the right table. * *anti*: Filter rows that do not have a match in the right table. left_on: Join column of the left DataFrame. right_on: Join column of the right DataFrame. suffix: Suffix to append to columns with a duplicate name. Returns: A new joined DataFrame Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_1_native = pd.DataFrame({"id": ["a", "b"], "price": [6.0, 7.0]}) >>> df_2_native = pd.DataFrame({"id": ["a", "b", "c"], "qty": [1, 2, 3]}) >>> nw.from_native(df_1_native).join(nw.from_native(df_2_native), on="id") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | id price qty | | 0 a 6.0 1 | | 1 b 7.0 2 | └──────────────────┘ rrrrrrrr\rrrrrrrfs r]rDataFrame.joinPs#Zw| G2  r_rrc .>[T U]UUUUUUUUU S9 $)u Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. Both DataFrames must be sorted by the asof_join key. Arguments: other: DataFrame to join with. left_on: Name(s) of the left join column(s). right_on: Name(s) of the right join column(s). on: Join column of both DataFrames. If set, left_on and right_on should be None. by_left: join on these columns before doing asof join. by_right: join on these columns before doing asof join. by: join on these columns before doing asof join. strategy: Join strategy. The default is "backward". suffix: Suffix to append to columns with a duplicate name. * *backward*: selects the last row in the right DataFrame whose "on" key is less than or equal to the left's key. * *forward*: selects the first row in the right DataFrame whose "on" key is greater than or equal to the left's key. * *nearest*: search selects the last row in the right DataFrame whose value is nearest to the left's key. Returns: A new joined DataFrame Examples: >>> from datetime import datetime >>> import pandas as pd >>> import narwhals as nw >>> data_gdp = { ... "datetime": [ ... datetime(2016, 1, 1), ... datetime(2017, 1, 1), ... datetime(2018, 1, 1), ... datetime(2019, 1, 1), ... datetime(2020, 1, 1), ... ], ... "gdp": [4164, 4411, 4566, 4696, 4827], ... } >>> data_population = { ... "datetime": [ ... datetime(2016, 3, 1), ... datetime(2018, 8, 1), ... datetime(2019, 1, 1), ... ], ... "population": [82.19, 82.66, 83.12], ... } >>> gdp_native = pd.DataFrame(data_gdp) >>> population_native = pd.DataFrame(data_population) >>> gdp = nw.from_native(gdp_native) >>> population = nw.from_native(population_native) >>> population.join_asof(gdp, on="datetime", strategy="backward") ┌──────────────────────────────┐ | Narwhals DataFrame | |------------------------------| | datetime population gdp| |0 2016-03-01 82.19 4164| |1 2018-08-01 82.66 4566| |2 2019-01-01 83.12 4696| └──────────────────────────────┘ rrr  r\rrrrrrrrrrfs r]r DataFrame.join_asofs8Rw !  r_c$UR5)$)u Get a mask of all duplicated rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [2, 2, 2], "bar": [6.0, 6.0, 7.0]}) >>> nw.from_native(df_native).is_duplicated() ┌───────────────┐ |Narwhals Series| |---------------| | 0 True | | 1 True | | 2 False | | dtype: bool | └───────────────┘ ) is_uniquer[s r] is_duplicatedDataFrame.is_duplicateds(   r_c[U5S:H$)aCCheck if the dataframe is empty. Returns: A boolean indicating whether the dataframe is empty (True) or not (False). Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [2, 2, 2], "bar": [6.0, 6.0, 7.0]}) >>> nw.from_native(df_native).is_empty() False r)rr[s r]is_emptyDataFrame.is_emptys4yA~r_cfURURR5URS9$)uGet a mask of all unique rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [2, 2, 2], "bar": [6.0, 6.0, 7.0]}) >>> nw.from_native(df_native).is_unique() ┌───────────────┐ |Narwhals Series| |---------------| | 0 False | | 1 False | | 2 True | | dtype: bool | └───────────────┘ rd)rQrUr9rWr[s r]r9DataFrame.is_uniques*(||D11;;=T[[|QQr_cURR5nURRUR5R 55nUR U5$)uCreate a new DataFrame that shows the null counts per column. Returns: A dataframe of shape (1, n_columns). Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md/) for reference. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, None], "bar": [2, 3]}) >>> nw.from_native(df_native).null_count() ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | foo: int64 | | bar: int64 | | ---- | | foo: [[1]] | | bar: [[0]] | └──────────────────┘ )rUrarr null_countrh)r\rresults r]rBDataFrame.null_countsN6##::<&&--cggi.B.B.DE##F++r_c4URRXS9$)aZReturn the DataFrame as a scalar, or return the element at the given row/column. Arguments: row: The *n*-th row. column: The column selected via an integer or a string (column name). Returns: A scalar or the specified element in the dataframe. Notes: If row/col not provided, this is equivalent to df[0,0], with a check that the shape is (1,1). With row/col, this is equivalent to df[row,col]. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, None], "bar": [2, 3]}) >>> nw.from_native(df_native).item(0, 1) 2 )rcolumn)rUr)r\rrFs r]rDataFrame.item1s*$$))c)AAr_cTURURR55$)z\Create a copy of this DataFrame. Returns: An identical copy of the original dataframe. )rhrUcloner[s r]rIDataFrame.cloneHs$ ##D$9$9$?$?$ABBr_c>[TU]XS9$)uTake every nth row in the DataFrame and return as a new DataFrame. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: The dataframe containing only the selected rows. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"foo": [1, None, 2, 3]}) >>> nw.from_native(df_native).gather_every(2) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | foo: int64 | | ---- | | foo: [[1,2]] | └──────────────────┘ r)rr)r\rrrfs r]rDataFrame.gather_everyPs0w#a#77r__)rvaluesaggregate_functionr sort_columns separatorc VUcUc Sn[U5eUbSn[U[[5S9 [ U[ 5(aU/OUn[ U[ 5(aU/OUn[ U[ 5(aU/OUnUR URRUUUUUUS95$)uCreate a spreadsheet-style pivot table as a DataFrame. Arguments: on: Name of the column(s) whose values will be used as the header of the output DataFrame. index: One or multiple keys to group by. If None, all remaining columns not specified on `on` and `values` will be used. At least one of `index` and `values` must be specified. values: One or multiple keys to group by. If None, all remaining columns not specified on `on` and `index` will be used. At least one of `index` and `values` must be specified. aggregate_function: Choose from: - None: no aggregation takes place, will raise error if multiple values are in group. - A predefined aggregate function string, one of {'min', 'max', 'first', 'last', 'sum', 'mean', 'median', 'len'} maintain_order: Has no effect and is kept around only for backwards-compatibility. sort_columns: Sort the transposed columns by name. Default is by order of discovery. separator: Used as separator/delimiter in generated column names in case of multiple `values` columns. Returns: A new dataframe. Examples: >>> import pandas as pd >>> import narwhals as nw >>> data = { ... "ix": [1, 1, 2, 2, 1, 2], ... "col": ["a", "a", "a", "a", "b", "b"], ... "foo": [0, 1, 2, 2, 7, 1], ... "bar": [0, 2, 0, 0, 9, 4], ... } >>> df_native = pd.DataFrame(data) >>> nw.from_native(df_native).pivot( ... "col", index="ix", aggregate_function="sum" ... ) ┌─────────────────────────────────┐ | Narwhals DataFrame | |---------------------------------| | ix foo_a foo_b bar_a bar_b| |0 1 1 7 2 9| |1 2 4 1 0 4| └─────────────────────────────────┘ z3At least one of `values` and `index` must be passedzx`maintain_order` has no effect and is only kept around for backwards-compatibility. You can safely remove this argument.)messagecategory stacklevel)rrrNrOrPrQ) rr UserWarningr!rrrhrUpivot) r\rrrNrOrrPrQrs r]rWDataFrame.pivotjst >emGCS/ !  %7  {?P QC((bTb'44&&%eS11u##  ! ! ' '#5)# (   r_c6URR5$)aPConvert to arrow table. Returns: A new PyArrow table. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [1, None], "bar": [2, 3]}) >>> nw.from_native(df_native).to_arrow() pyarrow.Table foo: double bar: int64 ---- foo: [[1,null]] bar: [[2,3]] )rUr|r[s r]r|DataFrame.to_arrows$$$--//r_)fractionwith_replacementseedc TURURRXX4S95$)uSample from this DataFrame. 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. Returns: A new dataframe. Notes: The results may not be consistent across libraries. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": [1, 2, 3], "bar": [19, 32, 4]}) >>> nw.from_native(df_native).sample(n=2) # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| | foo bar | | 2 3 4 | | 1 2 32 | └──────────────────┘ )rr[r\r])rhrUsample)r\rr[r\r]s r]r_DataFrame.samples7H##  ! ! ( (9I )   r_variablerrrrc >[TU]XX4S9$)urUnpivot a DataFrame from wide to long format. Optionally leaves identifiers set. This function is useful to massage a DataFrame into a format where one or more columns are identifier variables (index) while all other columns, considered measured variables (on), are "unpivoted" to the row axis leaving just two non-identifier columns, 'variable' and 'value'. Arguments: on: Column(s) to use as values variables; if `on` is empty all columns that are not in `index` will be used. index: Column(s) to use as identifier variables. variable_name: Name to give to the `variable` column. Defaults to "variable". value_name: Name to give to the `value` column. Defaults to "value". Returns: The unpivoted dataframe. Notes: If you're coming from pandas, this is similar to `pandas.DataFrame.melt`, but with `index` replacing `id_vars` and `on` replacing `value_vars`. In other frameworks, you might know this operation as `pivot_longer`. Examples: >>> import pandas as pd >>> import narwhals as nw >>> data = { ... "a": ["x", "y", "z"], ... "b": [1, 3, 5], ... "c": [2, 4, 6], ... } >>> df_native = pd.DataFrame(data) >>> nw.from_native(df_native).unpivot(["b", "c"], index="a") ┌────────────────────┐ | Narwhals DataFrame | |--------------------| | a variable value| |0 x b 1| |1 y b 3| |2 z b 5| |3 x c 2| |4 y c 4| |5 z c 6| └────────────────────┘ r rrr\rrrrrfs r]rDataFrame.unpivots!lwm  r_c&>[TU]"U/UQ76$)uExplode the dataframe to long format by exploding the given columns. Notes: It is possible to explode multiple columns only if these columns must have matching element counts. Arguments: columns: Column names. The underlying columns being exploded must be of the `List` data type. *more_columns: Additional names of columns to explode, specified as positional arguments. Returns: New DataFrame Examples: >>> import polars as pl >>> import narwhals as nw >>> data = {"a": ["x", "y"], "b": [[1, 2], [3]]} >>> df_native = pl.DataFrame(data) >>> nw.from_native(df_native).explode("b").to_native() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ x ┆ 1 │ │ x ┆ 2 │ │ y ┆ 3 │ └─────┴─────┘ rrr\rrrfs r]rDataFrame.explode4s>ww666r_rUrWr#)r!ztype[Series[Any]])r!ztype[LazyFrame[Any]]rgrrerVr!Noner!r )r!r.)NN)rnrrl bool | Noner!rKr!rrY)rvz object | Noner!r9)r(ModuleType | Implementation | str | Noner!zLazyFrame[Any])r!rP)r!z pd.DataFrame)r!z pl.DataFrame)rrmr!r)rzstr | Path | BytesIOr!rm)rzstr | Path | BytesIO | Noner!r7)r!rK)r!ztuple[int, int])rrr! Series[Any])b)rrIr!z int | float)rz-tuple[SingleIndexSelector, SingleColSelector]r!r)rz2str | tuple[MultiIndexSelector, SingleColSelector]r!rr)rzSingleIndexSelector | MultiIndexSelector | MultiColSelector | tuple[SingleIndexSelector, MultiColSelector] | tuple[MultiIndexSelector, MultiColSelector]r!r2)ra SingleIndexSelector | SingleColSelector | MultiColSelector | MultiIndexSelector | tuple[SingleIndexSelector, SingleColSelector] | tuple[SingleIndexSelector, MultiColSelector] | tuple[MultiIndexSelector, SingleColSelector] | tuple[MultiIndexSelector, MultiColSelector]r!zSeries[Any] | Self | Any)rrr!r)r Literal[True]r!zdict[str, Series[Any]])rLiteral[False]r!zdict[str, list[Any]])rrr!z-dict[str, Series[Any]] | dict[str, list[Any]])rr.r!ztuple[Any, ...]r%r(r&r'r$r*)rrur!zlist[tuple[Any, ...]])rrtr!zlist[dict[str, Any]])rrr!z,list[tuple[Any, ...]] | list[dict[str, Any]])r!zIterator[Series[Any]])rrurr.r!zIterator[tuple[Any, ...]])rrtrr.r!zIterator[dict[str, Any]])rrrr.r!z4Iterator[tuple[Any, ...]] | Iterator[dict[str, Any]]r+r,r-rr1rrr!r2)rr)rrJrrr!r2r/)r'r1rrr!z GroupBy[Self]r0r2r3r6)r!rr)r!rr!r2)r int | NonerFzint | str | Noner!rr4r5)rzstr | list[str]rr)rNr)rOzPivotAgg | NonerrorPrrQrr!r2)r!zpa.Table) rrzr[z float | Noner\rr]rzr!r2r8r:)Ar;r<r=r>__doc__rlr@rQrYr`rerhrmrrryrrrrrrrrrrrrrrrrrrr~rrrrrrrrrrrrrr)rrr r:r=r9rBrrIrrWr|r_rrrA __classcell__rfs@r]rCrCs0@2 &552/APN2=AM 9M  M ^3.1*1066 @@522&?"++ W8?0ZZ F   :    o> :o> "o>b#47WW PP < < 6<<$(B B 6B:067477 7 7>11:,,2   (  .3RR HH WW %77 57,:>;>(&(58( "((:='%'47' !''14CC+.C =CC %UU36U =U>#;3#;DL#; #;J"5-"5 "5  "5H'.(0BF>>4*.* $)$ * &* ! *  *  * X8:?8:8:  8:vBG<H(<H:><H <HD-2 'X 'X'X* 'X  'X  'X'XX&*# / +/+// /  #/  / ( / )/ /  / / j##*.+/%)%/S S  S  S  S (S )S  #S #S S  S S l!, R,,>B.C88<)-)-.2&*"P P & P ' P , P $P P P  P d0,( "&!& ( (  (  (  (  ( X&*8 )-'! 8 "8 & 8  8  8  8 8 t77r_rCc ^\rSrSrSrS1Sjr\S2Sj5rS3SjrS4Sjr \S5Sj5r S6Sjr S7S8S jjr S9S jr S:U4S jjrS7S;U4S jjjrSU4Sjj5rS>U4Sjjr\S?U4Sjj5rS@U4SjjrS@U4SjjrSAU4SjjrSBSCU4SjjjrSBSCU4SjjjrSS.SDU4SjjjrS7SS.SESjjjrSFU4SjjrSS.SGS jjrSSS!.SHU4S"jjjrSIS S S#S$.SJU4S%jjjjrS S S S S S S&S#S'.SKU4S(jjjrSLS)jr SMSNU4S*jjjr!S7S S+S,S-.SOU4S.jjjjr"SPU4S/jjr#S0r$U=r%$)QrXiVasNarwhals 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) ``` cSSKJn SSKJn [ U[ 5(a UR $[ X5(a Sn[U5e[ U[5(a!UR5nURU5$[ X5(aURRR5(a Sn[U5eURRR!5(a Sn[#U5eUR%UR55$['5b2S[[)U55;aS[)U5S 3n[U5e[*R,"[)U55e) NrrEr<zABinary operations between Series and LazyFrame are not supported.aNOrder-dependent expressions are not supported for use in LazyFrame. Hints: - Instead of `lf.select(nw.col('a').sort())`, use `lf.select('a').sort()`. - Instead of `lf.select(nw.col('a').cum_sum())`, use `lf.select(nw.col('a').cum_sum().over(order_by='date'))`. See https://narwhals-dev.github.io/narwhals/basics/order_dependence/.a1Length-changing expressions are not supported for use in LazyFrame, unless followed by an aggregation. Hints: - Instead of `lf.select(nw.col('a').head())`, use `lf.select('a').head() - Instead of `lf.select(nw.col('a').drop_nulls()).select(nw.sum('a'))`, use `lf.select(nw.col('a').drop_nulls().sum()) rGrHrI)rKrFrLr=rrSrUrPrrar _metadata _window_kindis_openrr is_filtrationrrrrOrrS)r\r{rFr=rrs r]rlLazyFrame._extract_compliantcs=&* c9 % %'' ' c " "UCC. c3  --/C773<  c }}))1133\.c22}}!!//11I.c22))$*E*E*GH H < #CS N(B1$s)=77  C. "44T#Y??r_c[$rY)rCr[s r] _dataframeLazyFrame._dataframer[r_cX lU [U5(aUR5UlgS[ U53n[ U5e)NzVExpected Polars LazyFrame or an object that implements `__narwhals_lazyframe__`, got: )rWr%__narwhals_lazyframe__rUrOr^r_s r]r`LazyFrame.__init__sE  !" % %$&$=$=$?D !jkoprksjtuC % %r_cR[SUR5R55$)NzNarwhals LazyFramerqr[s r]rrLazyFrame.__repr__rtr_c.URR$)aReturn implementation of native frame. This can be useful when you need to use special-casing for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import dask.dataframe as dd >>> lf_native = dd.from_dict({"a": [1, 2]}, npartitions=1) >>> nw.from_native(lf_native).implementation rcr[s r]reLazyFrame.implementations"$$444r_cSn[U5e)Nz%Slicing is not supported on LazyFrame)rP)r\rrs r]rLazyFrame.__getitem__s5nr_Nc &UcSO[R"U5n[R[R[R4nUbX4;aSUSUS3n[ U5eUR URR"SSU0UD6SS9$) uM Materialize this LazyFrame into a DataFrame. As each underlying lazyframe has different arguments to set when materializing the lazyframe into a dataframe, we allow to pass them as kwargs (see examples below for how to generalize the specification). Arguments: backend: specifies which eager backend collect to. This will be the underlying backend for the resulting Narwhals DataFrame. If None, then the following default conversions will be applied: - `polars.LazyFrame` -> `polars.DataFrame` - `dask.DataFrame` -> `pandas.DataFrame` - `duckdb.PyRelation` -> `pyarrow.Table` - `pyspark.DataFrame` -> `pyarrow.Table` `backend` can be specified in various ways: - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW` or `POLARS`. - As a string: `"pandas"`, `"pyarrow"` or `"polars"` - Directly as a module `pandas`, `pyarrow` or `polars`. kwargs: backend specific kwargs to pass along. To know more please check the backend specific documentation: - [polars.LazyFrame.collect](https://docs.pola.rs/api/python/dev/reference/lazyframe/api/polars.LazyFrame.collect.html) - [dask.dataframe.DataFrame.compute](https://docs.dask.org/en/stable/generated/dask.dataframe.DataFrame.compute.html) Returns: DataFrame Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 2), (3, 4) df(a, b)") >>> lf = nw.from_native(lf_native) >>> lf ┌──────────────────┐ |Narwhals LazyFrame| |------------------| |┌───────┬───────┐ | |│ a │ b │ | |│ int32 │ int32 │ | |├───────┼───────┤ | |│ 1 │ 2 │ | |│ 3 │ 4 │ | |└───────┴───────┘ | └──────────────────┘ >>> lf.collect() ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | a: int32 | | b: int32 | | ---- | | a: [[1,3]] | | b: [[2,4]] | └──────────────────┘ Nz-Unsupported `backend` value. Expected one of z or None, got: rrrrdr) r rrPANDASPYARROWrrrUcollect)r\rr eager_backendsupported_eager_backendsrs r]rLazyFrame.collectsB!(^5P5PQX5Y  ! !  ! !  " "$   $)VBC[B\\klykzz{|CS/ !  ! ! ) ) J- J6 J  r_c[USS9$)uDConvert Narwhals LazyFrame to native one. Returns: Object of class that user started with. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 2), (3, 4) df(a, b)") >>> nw.from_native(lf_native).to_native() ┌───────┬───────┐ │ a │ b │ │ int32 │ int32 │ ├───────┼───────┤ │ 1 │ 2 │ │ 3 │ 4 │ └───────┴───────┘ F)narwhals_object pass_throughrr[s r]rLazyFrame.to_native s(EBBr_c,>[TU]"U/UQ70UD6$)uwPipe function call. Arguments: function: Function to apply. args: Positional arguments to pass to function. kwargs: Keyword arguments to pass to function. Returns: The original object with the function applied. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 2), (3, 4) df(a, b)") >>> nw.from_native(lf_native).pipe(lambda x: x.select("a")).to_native() ┌───────┐ │ a │ │ int32 │ ├───────┤ │ 1 │ │ 3 │ └───────┘ rrs r]rLazyFrame.pipe s<w|H6t6v66r_c>[TU]US9$)u Drop rows that contain null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Returns: The original object with the rows removed that contained the null values. Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md/) for reference. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, NULL), (3, 4) df(a, b)") >>> nw.from_native(lf_native).drop_nulls() ┌──────────────────┐ |Narwhals LazyFrame| |------------------| |┌───────┬───────┐ | |│ a │ b │ | |│ int32 │ int32 │ | |├───────┼───────┤ | |│ 3 │ 4 │ | |└───────┴───────┘ | └──────────────────┘ rrrs r]rLazyFrame.drop_nulls< s>w!!00r_c">[TU]U5$)uInsert column which enumerates rows. Arguments: name: The name of the column as a string. The default is "index". Returns: The original object with the column added. Examples: >>> import dask.dataframe as dd >>> import narwhals as nw >>> lf_native = dd.from_dict({"a": [1, 2], "b": [4, 5]}, npartitions=1) >>> nw.from_native(lf_native).with_row_index().collect() ┌──────────────────┐ |Narwhals DataFrame| |------------------| | index a b | | 0 0 1 4 | | 1 1 2 5 | └──────────────────┘ rrs r]rLazyFrame.with_row_index] s,w%d++r_c>[TU]$)anGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).schema Schema({'a': Int32, 'b': Decimal}) rrs r]r~LazyFrame.schemau rr_c >[TU]5$)axGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).collect_schema() Schema({'a': Int32, 'b': Decimal}) rrs r]rLazyFrame.collect_schema rr_c>[TU]$)a Get column names. Returns: The column names stored in a list. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).columns ['a', 'b'] rrs r]rLazyFrame.columns rr_cZ>U(dU(d Sn[U5e[TU]"U0UD6$)u]Add columns to this LazyFrame. Added columns will replace existing columns with the same name. Arguments: *exprs: Column(s) to add, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to add, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: LazyFrame: A new LazyFrame with the columns added. Note: Creating a new LazyFrame using this method does not create a new copy of existing data. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).with_columns(c=nw.col("a") + 1) ┌────────────────────────────────┐ | Narwhals LazyFrame | |--------------------------------| |┌───────┬──────────────┬───────┐| |│ a │ b │ c │| |│ int32 │ decimal(2,1) │ int32 │| |├───────┼──────────────┼───────┤| |│ 1 │ 4.5 │ 2 │| |│ 3 │ 2.0 │ 4 │| |└───────┴──────────────┴───────┘| └────────────────────────────────┘ z@At least one expression must be passed to LazyFrame.with_columns)rrrr\rprqrrfs r]rLazyFrame.with_columns s/N[TCS/ !w#U:k::r_cZ>U(dU(d Sn[U5e[TU]"U0UD6$)uSelect columns from this LazyFrame. Arguments: *exprs: Column(s) to select, specified as positional arguments. Accepts expression input. Strings are parsed as column names. **named_exprs: Additional columns to select, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: The LazyFrame containing only the selected columns. Notes: If you'd like to select a column whose name isn't a string (for example, if you're working with pandas) then you should explicitly use `nw.col` instead of just passing the column name. For example, to select a column named `0` use `df.select(nw.col(0))`, not `df.select(0)`. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).select("a", a_plus_1=nw.col("a") + 1) ┌────────────────────┐ | Narwhals LazyFrame | |--------------------| |┌───────┬──────────┐| |│ a │ a_plus_1 │| |│ int32 │ int32 │| |├───────┼──────────┤| |│ 1 │ 2 │| |│ 3 │ 4 │| |└───────┴──────────┘| └────────────────────┘ z:At least one expression must be passed to LazyFrame.select)rrrrs r]rLazyFrame.select s.N[NCS/ !w~u4 44r_c">[TU]U5$)u2Rename column names. Arguments: mapping: Key value pairs that map from old name to new name, or a function that takes the old name as input and returns the new name. Returns: The LazyFrame with the specified columns renamed. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 4.5), (3, 2.) df(a, b)") >>> nw.from_native(lf_native).rename({"a": "c"}) ┌────────────────────────┐ | Narwhals LazyFrame | |------------------------| |┌───────┬──────────────┐| |│ c │ b │| |│ int32 │ decimal(2,1) │| |├───────┼──────────────┤| |│ 1 │ 4.5 │| |│ 3 │ 2.0 │| |└───────┴──────────────┘| └────────────────────────┘ rrs r]rLazyFrame.rename s8w~g&&r_c">[TU]U5$)uNGet `n` rows. Arguments: n: Number of rows to return. Returns: A subset of the LazyFrame of shape (n, n_columns). Examples: >>> import dask.dataframe as dd >>> import narwhals as nw >>> lf_native = dd.from_dict({"a": [1, 2, 3], "b": [4, 5, 6]}, npartitions=1) >>> nw.from_native(lf_native).head(2).collect() ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 1 4 | | 1 2 5 | └──────────────────┘ rrs r]rLazyFrame.head r r_c">[TU]U5$)aZGet the last `n` rows. !!! warning `LazyFrame.tail` is deprecated and will be removed in a future version. Note: this will remain available in `narwhals.stable.v1`. See [stable api](../backcompat.md/) for more information. Arguments: n: Number of rows to return. Returns: A subset of the LazyFrame of shape (n, n_columns). rrs r]rLazyFrame.tail2 sw|Ar_Trc6>[TU]"[U5SU06$)uPRemove columns from the LazyFrame. Arguments: *columns: Names of the columns that should be removed from the dataframe. strict: Validate that all column names exist in the schema and throw an exception if a column name does not exist in the schema. Returns: The LazyFrame with the specified columns removed. Warning: `strict` argument is ignored for `polars<1.0.0`. Please consider upgrading to a newer version or pass to eager mode. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 2), (3, 4) df(a, b)") >>> nw.from_native(lf_native).drop("a").to_native() ┌───────┐ │ b │ │ int32 │ ├───────┤ │ 2 │ │ 4 │ └───────┘ rr r s r]rLazyFrame.dropB s<w|WW-=f==r_r)rcUS;aSUS3n[U5e[U[5(aU/nURURR XS95$)uKDrop duplicate rows from this LazyFrame. Arguments: subset: Column name(s) to consider when identifying duplicate rows. If set to `None`, use all columns. keep: {'any', 'none'} Which of the duplicate rows to keep. * 'any': Does not give any guarantee of which row is kept. * 'none': Don't keep duplicate rows. Returns: The LazyFrame with unique rows. Examples: >>> import duckdb >>> import narwhals as nw >>> lf_native = duckdb.sql("SELECT * FROM VALUES (1, 1), (3, 4) df(a, b)") >>> nw.from_native(lf_native).unique("a").sort("a", descending=True) ┌──────────────────┐ |Narwhals LazyFrame| |------------------| |┌───────┬───────┐ | |│ a │ b │ | |│ int32 │ int32 │ | |├───────┼───────┤ | |│ 3 │ 4 │ | |│ 1 │ 1 │ | |└───────┴───────┘ | └──────────────────┘ >rrz}narwhals.LazyFrame makes no assumptions about row order, so only 'any' and 'none' are supported for `keep` in `unique`. Got: r)rrr)r\rrrs r]rLazyFrame.uniqueb spJ  &OOSfTUW S/ ! fc " "XF##  ! ! ( ( ( B  r_c>[U5S:Xa,[US[5(aU(d Sn[U5e[TU]"U0UD6$)u Filter the rows in the LazyFrame based on a predicate expression. The original order of the remaining rows is preserved. Arguments: *predicates: Expression that evaluates to a boolean Series. Can also be a (single!) boolean list. **constraints: Column filters; use `name = value` to filter columns by the supplied value. Each constraint will behave the same as `nw.col(name).eq(value)`, and will be implicitly joined with the other filter conditions using &. Returns: The filtered LazyFrame. Examples: >>> import duckdb >>> import narwhals as nw >>> df_native = duckdb.sql(''' ... SELECT * FROM VALUES ... (1, 6, 'a'), ... (2, 7, 'b'), ... (3, 8, 'c') ... df(foo, bar, ham) ... ''') Filter on one condition >>> nw.from_native(df_native).filter(nw.col("foo") > 1).to_native() ┌───────┬───────┬─────────┐ │ foo │ bar │ ham │ │ int32 │ int32 │ varchar │ ├───────┼───────┼─────────┤ │ 2 │ 7 │ b │ │ 3 │ 8 │ c │ └───────┴───────┴─────────┘ Filter on multiple conditions with implicit `&` >>> nw.from_native(df_native).filter( ... nw.col("foo") < 3, nw.col("ham") == "a" ... ).to_native() ┌───────┬───────┬─────────┐ │ foo │ bar │ ham │ │ int32 │ int32 │ varchar │ ├───────┼───────┼─────────┤ │ 1 │ 6 │ a │ └───────┴───────┴─────────┘ Filter on multiple conditions with `|` >>> nw.from_native(df_native).filter( ... (nw.col("foo") == 1) | (nw.col("ham") == "c") ... ).to_native() ┌───────┬───────┬─────────┐ │ foo │ bar │ ham │ │ int32 │ int32 │ varchar │ ├───────┼───────┼─────────┤ │ 1 │ 6 │ a │ │ 3 │ 8 │ c │ └───────┴───────┴─────────┘ Filter using `**kwargs` syntax >>> nw.from_native(df_native).filter(foo=2, ham="b").to_native() ┌───────┬───────┬─────────┐ │ foo │ bar │ ham │ │ int32 │ int32 │ varchar │ ├───────┼───────┼─────────┤ │ 2 │ 7 │ b │ └───────┴───────┴─────────┘ rrzX`LazyFrame.filter` is not supported with Python boolean masks - use expressions instead.)rr'rrPrr)r\rrrrfs r]rLazyFrame.filter sGb  Oq Z 1 t%D%D[lCC. w~z9[99r_Frc^^SSKJm SSKJn SSKJm [ U5n[UU4SjU55(a Sn[U5eU"U/UQ7SU06$)uStart a group by operation. Arguments: *keys: Column(s) to group by. Accepts expression input. Strings are parsed as column names. drop_null_keys: if True, then groups where any key is null won't be included in the result. Returns: Object which can be used to perform aggregations. Examples: >>> import duckdb >>> import narwhals as nw >>> df_native = duckdb.sql( ... "SELECT * FROM VALUES (1, 'a'), (2, 'b'), (3, 'a') df(a, b)" ... ) >>> df = nw.from_native(df_native) >>> df.group_by("b").agg(nw.col("a").sum()).sort("b").to_native() ┌─────────┬────────┐ │ b │ a │ │ varchar │ int128 │ ├─────────┼────────┤ │ a │ 4 │ │ b │ 2 │ └─────────┴────────┘ rrEr:r<c3@># UHn[UTT45v M g7frYr r!s r]r%LazyFrame.group_by.. r#r$r%r) rKrFr&r;rLr=r"rrz)r\rr'r;r(rrFr=s @@r]r)LazyFrame.group_by sV@ '1*DM @i@ @ @W &c* *4K)KNKKr_rc,>[TU]"U/UQ7X#S.6$)u9Sort the LazyFrame by the given columns. Arguments: by: Column(s) names to sort by. *more_by: Additional columns to sort by, specified as positional arguments. descending: Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans. nulls_last: Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control. Returns: The sorted LazyFrame. Warning: Unlike Polars, it is not possible to specify a sequence of booleans for `nulls_last` in order to control per-column behaviour. Instead a single boolean is applied for all `by` columns. Examples: >>> import duckdb >>> import narwhals as nw >>> df_native = duckdb.sql( ... "SELECT * FROM VALUES (1, 6.0, 'a'), (2, 5.0, 'c'), (NULL, 4.0, 'b') df(a, b, c)" ... ) >>> df = nw.from_native(df_native) >>> df.sort("a") ┌──────────────────────────────────┐ | Narwhals LazyFrame | |----------------------------------| |┌───────┬──────────────┬─────────┐| |│ a │ b │ c │| |│ int32 │ decimal(2,1) │ varchar │| |├───────┼──────────────┼─────────┤| |│ NULL │ 4.0 │ b │| |│ 1 │ 6.0 │ a │| |│ 2 │ 5.0 │ c │| |└───────┴──────────────┴─────────┘| └──────────────────────────────────┘ rr,r-s r]rLazyFrame.sort s\w|BWWZWWr_rrc ">[TU]XXEX&S9$)uAdd a join operation to the Logical Plan. Arguments: other: Lazy DataFrame to join with. on: Name(s) of the join columns in both DataFrames. If set, `left_on` and `right_on` should be None. how: Join strategy. * *inner*: Returns rows that have matching values in both tables. * *left*: Returns all rows from the left table, and the matched rows from the right table. * *full*: Returns all rows in both dataframes, with the suffix appended to the right join keys. * *cross*: Returns the Cartesian product of rows from both tables. * *semi*: Filter rows that have a match in the right table. * *anti*: Filter rows that do not have a match in the right table. left_on: Join column of the left DataFrame. right_on: Join column of the right DataFrame. suffix: Suffix to append to columns with a duplicate name. Returns: A new joined LazyFrame. Examples: >>> import duckdb >>> import narwhals as nw >>> df_native1 = duckdb.sql( ... "SELECT * FROM VALUES (1, 'a'), (2, 'b') df(a, b)" ... ) >>> df_native2 = duckdb.sql( ... "SELECT * FROM VALUES (1, 'x'), (3, 'y') df(a, c)" ... ) >>> df1 = nw.from_native(df_native1) >>> df2 = nw.from_native(df_native2) >>> df1.join(df2, on="a") ┌─────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------| |┌───────┬─────────┬─────────┐| |│ a │ b │ c │| |│ int32 │ varchar │ varchar │| |├───────┼─────────┼─────────┤| |│ 1 │ a │ x │| |└───────┴─────────┴─────────┘| └─────────────────────────────┘ r0r1r2s r]rLazyFrame.joinH s#lw| G2  r_rrc .>[T U]UUUUUUUUU S9 $)u Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. Both DataFrames must be sorted by the asof_join key. Arguments: other: DataFrame to join with. left_on: Name(s) of the left join column(s). right_on: Name(s) of the right join column(s). on: Join column of both DataFrames. If set, left_on and right_on should be None. by_left: join on these columns before doing asof join by_right: join on these columns before doing asof join by: join on these columns before doing asof join strategy: Join strategy. The default is "backward". * *backward*: selects the last row in the right DataFrame whose "on" key is less than or equal to the left's key. * *forward*: selects the first row in the right DataFrame whose "on" key is greater than or equal to the left's key. * *nearest*: search selects the last row in the right DataFrame whose value is nearest to the left's key. suffix: Suffix to append to columns with a duplicate name. Returns: A new joined LazyFrame. Examples: >>> from datetime import datetime >>> import polars as pl >>> import narwhals as nw >>> data_gdp = { ... "datetime": [ ... datetime(2016, 1, 1), ... datetime(2017, 1, 1), ... datetime(2018, 1, 1), ... datetime(2019, 1, 1), ... datetime(2020, 1, 1), ... ], ... "gdp": [4164, 4411, 4566, 4696, 4827], ... } >>> data_population = { ... "datetime": [ ... datetime(2016, 3, 1), ... datetime(2018, 8, 1), ... datetime(2019, 1, 1), ... ], ... "population": [82.19, 82.66, 83.12], ... } >>> gdp_native = pl.DataFrame(data_gdp) >>> population_native = pl.DataFrame(data_population) >>> gdp = nw.from_native(gdp_native) >>> population = nw.from_native(population_native) >>> population.join_asof(gdp, on="datetime", strategy="backward").to_native() shape: (3, 3) ┌─────────────────────┬────────────┬──────┐ │ datetime ┆ population ┆ gdp │ │ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ f64 ┆ i64 │ ╞═════════════════════╪════════════╪══════╡ │ 2016-03-01 00:00:00 ┆ 82.19 ┆ 4164 │ │ 2018-08-01 00:00:00 ┆ 82.66 ┆ 4566 │ │ 2019-01-01 00:00:00 ┆ 83.12 ┆ 4696 │ └─────────────────────┴────────────┴──────┘ rr5r6s r]r LazyFrame.join_asof s8Xw !  r_cU$)zRestrict available API methods to lazy-only ones. This is a no-op, and exists only for compatibility with `DataFrame.lazy`. Returns: A LazyFrame. rr[s r]rLazyFrame.lazy s  r_c6>Sn[USS9 [TU] XS9$)aTake every nth row in the DataFrame and return as a new DataFrame. !!! warning `LazyFrame.gather_every` is deprecated and will be removed in a future version. Note: this will remain available in `narwhals.stable.v1`. See [stable api](../backcompat.md/) for more information. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: The LazyFrame containing only the selected rows. z`LazyFrame.gather_every` is deprecated and will be removed in a future version. Note: this will remain available in `narwhals.stable.v1`. See https://narwhals-dev.github.io/narwhals/backcompat/ for more information. z1.29.0)_versionr)r*rr)r\rrrrfs r]rLazyFrame.gather_every s-  ^ "#9w#a#77r_rarrbc >[TU]XX4S9$)uUnpivot a DataFrame from wide to long format. Optionally leaves identifiers set. This function is useful to massage a DataFrame into a format where one or more columns are identifier variables (index) while all other columns, considered measured variables (on), are "unpivoted" to the row axis leaving just two non-identifier columns, 'variable' and 'value'. Arguments: on: Column(s) to use as values variables; if `on` is empty all columns that are not in `index` will be used. index: Column(s) to use as identifier variables. variable_name: Name to give to the `variable` column. Defaults to "variable". value_name: Name to give to the `value` column. Defaults to "value". Returns: The unpivoted LazyFrame. Notes: If you're coming from pandas, this is similar to `pandas.DataFrame.melt`, but with `index` replacing `id_vars` and `on` replacing `value_vars`. In other frameworks, you might know this operation as `pivot_longer`. Examples: >>> import duckdb >>> import narwhals as nw >>> df_native = duckdb.sql( ... "SELECT * FROM VALUES ('x', 1, 2), ('y', 3, 4), ('z', 5, 6) df(a, b, c)" ... ) >>> df = nw.from_native(df_native) >>> df.unpivot(on=["b", "c"], index="a").sort("a", "variable").to_native() ┌─────────┬──────────┬───────┐ │ a │ variable │ value │ │ varchar │ varchar │ int32 │ ├─────────┼──────────┼───────┤ │ x │ b │ 1 │ │ x │ c │ 2 │ │ y │ b │ 3 │ │ y │ c │ 4 │ │ z │ b │ 5 │ │ z │ c │ 6 │ └─────────┴──────────┴───────┘ r rdres r]rLazyFrame.unpivot s!jwm  r_c&>[TU]"U/UQ76$)ubExplode the dataframe to long format by exploding the given columns. Notes: It is possible to explode multiple columns only if these columns have matching element counts. Arguments: columns: Column names. The underlying columns being exploded must be of the `List` data type. *more_columns: Additional names of columns to explode, specified as positional arguments. Returns: New LazyFrame Examples: >>> import duckdb >>> import narwhals as nw >>> df_native = duckdb.sql( ... "SELECT * FROM VALUES ('x', [1, 2]), ('y', [3, 4]), ('z', [5, 6]) df(a, b)" ... ) >>> df = nw.from_native(df_native) >>> df.explode("b").to_native() ┌─────────┬───────┐ │ a │ b │ │ varchar │ int32 │ ├─────────┼───────┤ │ x │ 1 │ │ x │ 2 │ │ y │ 3 │ │ y │ 4 │ │ z │ 5 │ │ z │ 6 │ └─────────┴───────┘ rhris r]rLazyFrame.explode5 sFww666r_rkr#)r!ztype[DataFrame[Any]]rlrprn)rz str | slicer!r rY)rrqrrr!zDataFrame[Any])r!rOr%r(r&r'r$r*r+r,rvr-rx)rr)rrCr!r2r/)r'r1rrr!zLazyGroupBy[Self]r0r2r3r6ryr4r5r8r:)&r;r<r=r>r{rlr@rr`rrrerrrrrrr~rrrrrrrrrrr)rrr rrrrrAr|r}s@r]rXrXVs *@X&P55$ =AM 9M M   M ^C.7477 7 7@11B,,0   (  *;3*;DL*; *;X*5-*5 *5  *5X'<0 BF>>D*./ (- / &/ % /  / bV:?V:V:  V:rBG+L(+L:>+L +Lb-2 .X .X.X* .X  .X  .X.Xf&*# 8 +/+/8 8  #8  8 ( 8 )8 8  8 8 |##*.+/%)%/V V  V  V  V (V )V  #V #V V  V V p884&*7 )-'! 7 "7 & 7  7  7  7 7 r#7#7r_rX)j __future__rabcr itertoolsrtypingrrrr r r r r rrrwarningsrnarwhals._expression_parsingrrrrrnarwhals.dependenciesrrnarwhals.exceptionsrrrrnarwhals.schemarnarwhals.translaternarwhals.utilsr r!r"r#r$r%r&r'r(r)r*r+r,ior-pathlibr.typesr/pandaspdrGplrzr~typing_extensionsr0r1r2r3narwhals._compliantr4r5r6narwhals._compliant.typingr7r&r9r;rLr=narwhals.typingr>r?r@rArBrCrD_MultiColSelectorrE_MultiIndexSelectorrFrGrHrIrJrKrLrMrOrPrQr?rSrCrXrr_r]rsi" 1BJ37,03477"()*"(11,%+(4(2 -+&+665<)-&0-(),6EI(13(2( 4B ); /  - \ 9  CL>)> BIBoW oWd F7 *%F7R6B7 &!B7r_