-PhaUddlmZddlmZddlmZddlmZmZm Z m Z m Z m Z m Z mZmZmZmZddlmZddlmZmZmZmZddlmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&ddl'm(Z(m)Z)dd l*m+Z+m,Z,m-Z-dd l.m/Z/dd l0m1Z1dd l2m3Z3ermdd l4m5Z5ddl6m7Z7ddl8m9Z9ddl:Z;ddlZ?ddl@mAZAmBZBmCZCmDZDddlEmFZFmGZGddlHmIZImJZJddlKmLZLmMZMddlNmOZOmPZPmQZQmRZRmSZSmTZTmUZVmWZXmYZYmZZZm[Z[m\Z\m]Z]m^Z^eBdZ_eddZ`eddZaeddZbedZcdZUdedd <d!ZWdedd"<Gd#d$e e`ZeGd%d&eeebZfGd'd(eeeaZgdS))) annotations)abstractmethod)chain) TYPE_CHECKINGAnyCallableGenericIterableIteratorLiteralNoReturnSequenceTypeVaroverload)warn)ExprKindall_exprs_are_scalar_like!check_expressions_preserve_lengthis_scalar_like) Implementationfind_stacklevelflatten generate_repris_compliant_dataframeis_compliant_lazyframeis_index_selector is_list_ofis_sequence_like is_slice_noneissue_deprecation_warning parse_versionsupports_arrow_c_stream) get_polarsis_numpy_array)InvalidIntoExprErrorLengthChangingExprErrorOrderDependentExprError)SchemaSeries to_native)BytesIO)Path) ModuleTypeN) Concatenate ParamSpecSelf TypeAlias)CompliantDataFrameCompliantLazyFrame)CompliantExprAnyEagerNamespaceAny)GroupBy LazyGroupBy)AsofJoinStrategy IntoDataFrameIntoExpr IntoFrame JoinStrategyLazyUniqueKeepStrategyMultiColSelectorMultiIndexSelectorPivotAggSingleColSelectorSingleIndexSelectorSizeUnitUniqueKeepStrategy_2DArrayPS_FrameTr=)boundFrameT DataFrameTr;Rz_MultiColSelector[Series[Any]]r3r@z _MultiIndexSelector[Series[Any]]rAc TeZdZUded<ded<dddZdedZdfd ZdgdZedhdZ e didZ didZ djdZ dkdld"Zdmd%Ze dnd'Zdod(Zdod)Zdpd,Zdqd/Zdqd0Zdrd5Zdsd9Zd:d:d;dtdBZ dudCdCdEdFdvdNZdwdxdQZdCdCdCdCdCdCdRdEdSdydYZdzd\Zd{d_Zd{d`Zd|dcZdCS)} BaseFramer_compliant_frame&Literal['full', 'lazy', 'interchange']_levelreturnr/c4|jSN)rP__native_namespace__selfs R/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/narwhals/dataframe.pyrVzBaseFrame.__native_namespace__`s$99;;;c4|jSrU)rP__narwhals_namespace__rWs rYr\z BaseFrame.__narwhals_namespace__cs$;;===rZdfr2c:|||jS)Nlevel) __class__rR)rXr]s rY_with_compliantzBaseFrame._with_compliantfs~~b ~444rZexprsIntoExpr | Iterable[IntoExpr] named_exprsr<-tuple[list[CompliantExprAny], list[ExprKind]]cg}g}t|D]U}||}|||tj|dV|D]k\}}|||}|||tj|dl||fS)zjProcess `args` and `kwargs`, extracting underlying objects as we go, interpreting strings as column names.F) str_as_lit)r_extract_compliantappendrfrom_into_expritemsalias)rXrcre out_exprs out_kindsexprcompliant_exprrms rY_flatten_and_extractzBaseFrame._flatten_and_extractjs  ENN N ND!44T::N   ^ , , ,   X4TeLLL M M M M&,,.. N NKE4!44T::@@GGN   ^ , , ,   X4TeLLL M M M M)##rZargctrUNotImplementedError)rXrss rYrizBaseFrame._extract_compliantzs!!rZr(cXt|jjSrU)r(rPschemarlrWs rYrxzBaseFrame.schema~s"d+288::;;;rZclt|j}t|SrU)dictrPcollect_schemar()rX native_schemas rYr{zBaseFrame.collect_schemas,T2AACCDD m$$$rZfunction"Callable[Concatenate[Self, PS], R]argsPS.argskwargs PS.kwargsrMc||g|Ri|SrU)rXr}rrs rYpipezBaseFrame.pipes$ x.t...v...rZindexnamestrc\||j|SrU)rbrPwith_row_indexrXrs rYrzBaseFrame.with_row_indexs'##D$9$H$H$N$NOOOrZsubsetstr | list[str] | Nonect|tr|gn|}||j|S)Nr) isinstancerrbrP drop_nulls)rXrs rYrzBaseFrame.drop_nullssD'44@&&##D$9$D$DF$D$S$STTTrZ list[str]c|jjSrU)rPcolumnsrWs rYrzBaseFrame.columnss$,,rZc|j|i|\}}dt||D}||jj|S)Nc`g|]+\}}t|r||n|,Srr broadcast.0rqkinds rY z*BaseFrame.with_columns..L   $/=T.B.B VN $ $T * * *   rZ)rrziprbrP with_columns)rXrcrecompliant_exprskindss rYrzBaseFrame.with_columnssl";!:E!Q[!Q!Q  (+OU(C(C   ##$FD$9$F$XYYYrZctt|}|rptd|DrW|sU ||jj|S#t $r%}|j|x}r||d}~wwxYw|j|i|\}}|r.t|i|r"||jj |Sdt||D}||jj |S)Nc3@K|]}t|tVdSrUrr)rxs rY z#BaseFrame.select..s,EEQjC00EEEEEErZc`g|]+\}}t|r||n|,Srrrs rYrz$BaseFrame.select..rrZ) tuplerallrbrP simple_select Exception_check_columns_existrrr aggregaterselect)rXrcre flat_exprseerrorrrs rYrzBaseFrame.selectsf75>>**  #EE*EEEEE k  ++7D)7D    1FFzRRR5'Q&   ";!:J!V+!V!V  [8*T TT [''(G(=(G(YZZ Z  (+OU(C(C   ##$@D$9$@/$RSSSs!A B ' BB mappingdict[str, str]c\||j|SrU)rbrPrename)rXrs rYrzBaseFrame.renames'##D$9$@$@$I$IJJJrZnintc\||j|SrU)rbrPheadrXrs rYrzBaseFrame.head'##D$9$>$>q$A$ABBBrZc\||j|SrU)rbrPtailrs rYrzBaseFrame.tailrrZr Iterable[str]strictboolc`||j||S)Nr)rbrPdrop)rXrrs rYrzBaseFrame.drops,##D$9$>$>wv$>$V$VWWWrZ predicates*IntoExpr | Iterable[IntoExpr] | list[bool] constraintsc t|dkr$t|dtr |d}n{ddlmt |}t |ddi| |j|\}} fd| D} j t||}| |j |S)Nrcol function_namefilterc3bK|])\}}||kV*dSrU)_to_compliant_expr)rrvrplxs rYrz#BaseFrame.filter..sU%%D!Ta33C88%%%%%%rZ)lenrrnarwhals.functionsrrrr\rrrlall_horizontalrrbrPr) rXrr predicateflat_predicatescompliant_predicates_kindscompliant_constraintsrrs @@rYrzBaseFrame.filters z??a  Jz!}d$C$C "1 II . . . . . .%j11O - Wh W W W--//C+D4+Do+V ( &%%%%%*0022%%% !+*+-BCCI##D$9$@$@$K$KLLLrZF descending nulls_lastbystr | Iterable[str]more_byrbool | Sequence[bool]rctgt|g|}||jj|||dS)Nr)rrbrPsort)rXrrrrs rYrzBaseFrame.sortsV/wt}}/w/ 0 0## &D ! &zj Y Y Y   rZNinner_rightleft_onright_onsuffixotheronhowr>rrrc t|tr|gn|}t|tr|gn|}t|tr|gn|}|dx}vrd|d|d}t||dkr|||d}t||dkr|||d|d}t||dkr|||d |d}t|||x}}t|trFt|tr1t |t |krd }t|||j| ||||| S) N)rleftfullcrossantisemiz2Only 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 z3`left_on` and `right_on` must have the same length.)rrrr) rrrv ValueErrorlistrrbrPjoinri) rXrrrrrr_supported_joinsmsgs rYrzBaseFrame.joins C(( 0bTTb)'377D7))W!+Hc!:!:HH::  R R   jGWiibeiiiC%c** * '>>  8#72>RCS// ! '>>rzw(BRb\_bbbCS// ! '>> N 3x7K]WZ]]]CS// ! >!# #Gh w % % "*Xt*D*D " LLCMM ) )GCS// !##  ! & &''..! '     rZroffsetc`||j||S)Nrr)rbrP gather_every)rXrrs rYrzBaseFrame.gather_every s3##  ! . .6 . B B   rZbackwardrrrby_leftby_rightrstrategyr str | Nonerrrr:c d} || vrd| d|d} t| |||d} t| |||d} t| |||||d} t| |||d} t| ||x}}||x}}t|tr|g}t|tr|g}t|trFt|tr1t |t |krd } t| ||j| ||||||| S) 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.z3`by_left` and `by_right` must have the same length.)rrrrrr) rvrrrrrrbrP join_asofri) rXrrrrrrrrr_supported_strategiesrs rYrzBaseFrame.join_asof%s!C 0 0 0nBWnnbjnnnC%c** * JW_0@WCS// ! N!48LRCS// ! J _!5#(8Z S// ! N!48LRCS// ! >!# #Gh >!# #Gh gs # # iG h $ $ " zH w % % "*Xt*D*D " LLCMM ) )GCS// !##  ! + +''..!!! ,     rZ variable_name value_namect|tr|gn|}t|tr|gn|}||j||||S)Nrrrr )rrrbrPunpivot)rXrrrr s rYr zBaseFrame.unpivotdst C(( 0bTTb%eS11<u##  ! ) )U-J *     rZobjectr c$d}t|)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)rurXrrs rY__neq__zBaseFrame.__neq__u + "#&&&rZc$d}t|)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)rurs rY__eq__zBaseFrame.__eq__rrZstr | Sequence[str] more_columnsct|tr|g|ng||}||j|S)Nr)rrrbrPexplode)rXrr to_explodes rYrzBaseFrame.explodes_'3'' +W $| $ $*7*\*  ##D$9$A$A*$A$U$UVVVrZ)rSr/)rSr)r]rrSr2)rcrdrer<rSrfrsrrSrrSr(r}r~rrrrrSrMrrrrSr2rrrSr2rSrrcrdrer<rSr2rrrSr2rrrSr2)rrrrrSr2rrrrrSr2 rrrrrrrrrSr2Nrrr2rrrr>rrrrrrrSr2rrrrrrSr2rr2rrrrrrrrrrrrrr:rrrSr2 rrrrrrr rrSr2)rr rSr rrrrrSr2) __name__ __module__ __qualname____annotations__rVr\rbrrrripropertyrxr{rrrrrrrrrrrrrrrr rrrrrZrYrOrO\s2222<<<<>>>>5555$$$$ """^"<<<X<%%%% ////PPPPPUUUU---X-ZZZZTTTT0KKKKCCCCCCCCXXXXMMMM2-2       &*# 5 +/+/5 5 5 5 5 5 n     ##*.+/%)%/= = = = = = ~    " ' ' ' ' ' ' ' 'WWWWWWrZrOc .eZdZdZddZeddZedd ZddZeddZ ddZ dddZ ddZ dddZ ddd"Zdd$Zdd&Zdd(Zeddd*Zedd,Zddd/Zdd0Zdd1Zedd3Zdd6Zddd;Zedd>Zedd@ZeddCZddFZddIZedJdKddOZeddRZeddTZdUdKddVZddYZdfda Zddfdd Zddfde Zed fdg Z d fdh Z!ed fdj Z"edkdld doZ#ed dqZ#ed dsZ#dkdld dtZ#ddvZ$edJdwddzZ%edJdwdd|Z%edJdwdd~Z%dkddddZ%dfd Z&dfd Z'dfd Z(ddfd Z)ddfd Z*dUddfdZ+ dddkdddZ,dfd Z-edJdddZ.eddZ.dkdddZ.dkdkddfdZ/ ddddddfdZ0ddddddddddfdZ1d dZ2d!dZ3d dZ4d"dZ5dd#dƄZ6d"dDŽZ7d$d%fdʄ Z8dddddkdd̜d&dӄZ9d'dՄZ: dddkdd֜d(dۄZ; dddddޜd)fdZ<d*fd Z=xZ>S(+ DataFramea{Narwhals 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), ) ``` rsrrScddlm}ddlm}|}t |t r|jSt ||r|j St ||r'| |St |tr| |St@dtt|vr"dt|d}t|t!|r.|j|| St'jt|)NrExprr)polarsExpected Narwhals object, got: [. Perhaps you: - Forgot a `nw.from_native` somewhere? - Used `pl.col` instead of `nw.col`?)context) narwhals.exprr6narwhals.seriesr*r\rrOrP_compliant_series_to_exprrrrr#type TypeErrorr$_series from_numpyr%from_invalid_type)rXrsr6r*rrs rYrizDataFrame._extract_compliantsl&&&&&&******!%!!> c9 % % (' ' c6 " " 4(1133 3 c4  I))$*E*E*G*GHH H c3   773<<  << #CS NN(B(B7$s))777  C.. #   G;))#s);;DDFF F"4T#YY???rZtype[Series[Any]]ctSrUr)rWs rYrAzDataFrame._seriess rZtype[LazyFrame[Any]]ctSrU) LazyFramerWs rY _lazyframezDataFrame._lazyframerZr]r`rQNonec||_|t|r||_dSdt |}t |)NzCExpected an object which implements `__narwhals_dataframe__`, got: )rRr__narwhals_dataframe__rPr?AssertionErrorrXr]r`rs rY__init__zDataFrame.__init__s^>C  M !" % % &$&$=$=$?$?D ! ! !bX\]_X`X`bbC %% %rZrc|jjS)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 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 rP_implementationrWs rYimplementationzDataFrame.implementations0$44rZrc4|jSrU)rP__len__rWs rYrVzDataFrame.__len__s$,,...rZNdtypecopy bool | NonerGc:|j||S)NrX)rP __array__)rXrWrXs rYr\zDataFrame.__array__s$..u4.@@@rZrcjtd|S)NzNarwhals DataFramerr,__repr__rWs rYr_zDataFrame.__repr__)14>>3C3C3L3L3N3NOOOrZrequested_schema object | Noner c|jj}t|r||S ddl}n4#t $r'}dt |}t ||d}~wwxYwt|dkr"dt |}t |d|}||S)ahExport 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. )rarNzT'pyarrow>=14.0.0' is required for `DataFrame.__arrow_c_stream__` for object of type )r) rP _native_framer"__arrow_c_stream__pyarrowModuleNotFoundErrorr?r!to_arrow)rXra native_framepaexcrpa_tables rYrfzDataFrame.__arrow_c_stream__s,: "< 0 0 V22DT2UU U 4 " 4 4 4}imnzi{i{}}C%c** 3 4   w & &}imnzi{i{}}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 )rnlazyr_) r from_backendDASKDUCKDBPOLARSrrIrPrr)rXrn lazy_backendsupported_lazy_backendsrs rYrrzDataFrame.lazys| 'ttN4OPW4X4X    !  !#   # __P\__ 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 )rPrerWs rYr,zDataFrame.to_nativeas*$22rZ pd.DataFramec4|jS)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 )rP to_pandasrWs rYr|zDataFrame.to_pandasxs&$..000rZ pl.DataFramec4|jS)uConvert 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 │ └─────┴─────┘ )rP to_polarsrWs rYrzDataFrame.to_polarss,$..000rZfilecdSrUrrXrs rY write_csvzDataFrame.write_csvs363rZstr | Path | BytesIOcdSrUrrs rYrzDataFrame.write_csvs=@SrZstr | Path | BytesIO | Nonerc6|j|S)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. )rPrrs rYrzDataFrame.write_csvs.$..t444rZc:|j|dS)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)rP write_parquetrs rYrzDataFrame.write_parquets!" ++D11111rZc:|jddS)aConvert 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. ]]) Nr[)rPto_numpyrWs rYrzDataFrame.to_numpys $--d->>>rZtuple[int, int]c|jjS)a_Get 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) )rPshaperWs rYrzDataFrame.shapes$**rZr Series[Any]cj||j||jS)alGet 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 r_)rArP get_columnrRrs rYrzDataFrame.get_columns-4||D1<>> 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 )r)rPestimated_size)rXrs rYrzDataFrame.estimated_sizes($333>>>rZitem-tuple[SingleIndexSelector, SingleColSelector]cdSrUrrXrs rY __getitem__zDataFrame.__getitem__-sWZWZrZ2str | tuple[MultiIndexSelector, SingleColSelector]cdSrUrrs rYrzDataFrame.__getitem__0s crZSingleIndexSelector | MultiIndexSelector | MultiColSelector | tuple[SingleIndexSelector, MultiColSelector] | tuple[MultiIndexSelector, MultiColSelector]r2cdSrUrrs rYrzDataFrame.__getitem__5s srZ SingleIndexSelector | SingleColSelector | MultiColSelector | MultiIndexSelector | tuple[SingleIndexSelector, SingleColSelector] | tuple[SingleIndexSelector, MultiColSelector] | tuple[MultiIndexSelector, SingleColSelector] | tuple[MultiIndexSelector, MultiColSelector]Series[Any] | Self | Anycddlm}dt|d}t|tr~t |dkrd}t ||rt|drdn|d}t |dkst|drdn|d}|||SnSt|r|}d}n?t|st|ttfrd}|}nt |t|trt ||j }t|ttfrpt|tr|||St|tr|n |j|}||} || |n| St||r|j}t||r|j}|||dd|fS||||ddfS||||fS) 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)r<r*r?rrrr@rrrslicerrPrrrrr=rb) rXrr*r tuple_msgrowsr compliantcol_nameseriess rYrzDataFrame.__getitem__@st| +***** Nd N N N  dE " " !4yy1}}U ***#J}T!W'='=J4447D!$ii!mm}T!W/E/Emdd4PQ7G| t $ $ !DGG d # # !z$ 'E'E !DGGC.. dC  !C.. ) gSz * * @$$$ 0yyw///",Wc":":Uww W@UH__X..F#'#36$<< ? dF # # *)D gv & & 0/G <'' !!!W*(=>> > ?'' $'(:;; ;##IdGm$<===rZkeyrc||jvSrUr)rXrs rY __contains__zDataFrame.__contains__sdl""rZ. as_seriesr Literal[True]dict[str, Series[Any]]cdSrUrrXrs rYto_dictzDataFrame.to_dictTWTWrZLiteral[False]dict[str, list[Any]]cdSrUrrs rYrzDataFrame.to_dictsMPSrZ-dict[str, Series[Any]] | dict[str, list[Any]]cdSrUrrs rYrzDataFrame.to_dicts 9<rZTc|r9fdj|DSj|S)avConvert 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 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']} cPi|]"\}}||j#S)r_)rArR)rrvaluerXs rY z%DataFrame.to_dict..sACT\\%t{\;;rZr)rPrrlrs` rYrzDataFrame.to_dictsy(  "&"7"?"?'#@##%''   $,,y,AAArZrtuple[Any, ...]c6|j|S)aGet 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) (, ) )rProw)rXrs rYrz DataFrame.rows0$((///rZr}r~rrrrrMc>tj|g|Ri|S)aPipe 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 superrrXr}rrras rYrzDataFrame.pipes+:uww|H6t666v666rZrrcHt|S)aPDrop 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](../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]] rrrrXrras rYrzDataFrame.drop_nullss 6ww!!!000rZcFt|S)auInsert 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]] rrrXrras rYrzDataFrame.with_row_index0s.ww%%d+++rZr(c*tjS)aGet 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}) rrxrXras rYrxzDataFrame.schemaIww~rZcDtS)aGet 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}) rr{rs rYr{zDataFrame.collect_schemaYww%%'''rZrc*tjS)aOGet 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 rYrzDataFrame.columnshwwrZFnamedrlist[tuple[Any, ...]]cdSrUrrXrs rYrzDataFrame.rowsxsORsrZlist[dict[str, Any]]cdSrUrrs rYrzDataFrame.rows{sEHSrZ,list[tuple[Any, ...]] | list[dict[str, Any]]cdSrUrrs rYrzDataFrame.rows~rrZc8|j|S)apReturns 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)rPrrs rYrzDataFrame.rowss($)))666rZIterator[Series[Any]]c#~K|jD] }|||jV!dS)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| └─────────────────────────┘ r_N)rP iter_columnsrArR)rXrs rYrzDataFrame.iter_columnssQ8+88:: : :F,,vT[,99 9 9 9 9 : :rZ) buffer_sizerIterator[tuple[Any, ...]]cdSrUrrXrrs rY iter_rowszDataFrame.iter_rowss %(CrZIterator[dict[str, Any]]cdSrUrrs rYrzDataFrame.iter_rowss $'3rZ4Iterator[tuple[Any, ...]] | Iterator[dict[str, Any]]cdSrUrrs rYrzDataFrame.iter_rowss @CsrZirrc:|j||S)aReturns 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)rPrrs rYrzDataFrame.iter_rowss :$..U .TTTrZrcrdrer<c6tj|i|S)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 )rrrXrcreras rYrzDataFrame.with_columnss"F$uww#U:k:::rZc6tj|i|S)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 rYrzDataFrame.select s!@uww~u4 444rZrrcFt|S)aKRename 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]] rrrXrras rYrzDataFrame.rename+s*ww~~g&&&rZrcFt|S)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 rrrXrras rYrzDataFrame.headBs$ww||ArZcFt|S)uGet 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 rYrzDataFrame.tailV,ww||ArZrrrrcPtjt|d|iS)aRemove 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 rrrrrXrrras rYrzDataFrame.dropns(,uww|WW--=f===rZanykeepmaintain_orderrrFrc|dvrddd|}t|t|tr|g}||j|||S)aMDrop 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: rrrrrbrPunique)rXrrrrs rYrzDataFrame.uniquesF 7 7 7K=KKTKKCS// ! fc " " XF##  ! ( (d> ( Z Z   rZrrrc6tj|i|S)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)rXrrras rYrzDataFrame.filters!luww~z9[999rZdrop_null_keyskeysr  GroupBy[Self]cdSrUrrXr r s rYgroup_byzDataFrame.group_by rZcdSrUrr s rYrzDataFrame.group_byrrZc ddlm}t|}td|Dr||||Sddlm ddlm ddlm t fd|D}|r t|rd }t| fd t||D}|j|\}} td | Dsdd lm} d }| |||||S)aStart 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: 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 Expressions are also accepted. >>> nw.from_native(df_native, eager_only=True).group_by( ... "a", nw.col("b") // 2 ... ).agg(nw.col("c").mean()).to_native() a b c 0 a 0 4.0 1 b 1 3.0 2 c 1 1.0 r)r8c3@K|]}t|tVdSrUrrrs rYrz%DataFrame.group_by..4,99z#s##999999rZrrr5r)c3<K|]}t|fVdSrUr)rkr6r*s rYrz%DataFrame.group_by..;s1%W%WjT6N&C&C%W%W%W%W%W%WrZz?drop_null_keys cannot be True when keys contains Expr or Seriesc4g|]\}}|r|n |Srrrris_exprrs rYrz&DataFrame.group_by..As>   7 $AAcc!ff   rZc32K|]}|tjuVdSrUr ELEMENTWISErrs rYrz%DataFrame.group_by..G*BBD48//BBBBBBrZ ComputeErrorHGroup by is not supported with keys that are not elementwise expressions)narwhals.group_byr8rrnarwhalsrr;r6r<r*rrrvrrrnarwhals.exceptionsr!)rXr r r8 flat_keyskey_is_expr_or_seriesr_keysexpr_flat_keysrr!r6r*rs @@@rYrzDataFrame.group_bysx .-----DMM 99y999 9 9 K74>JJJ J      &&&&&&****** %%W%W%W%W%WY%W%W%W W W  +c"788 +SC%c** *    !)-BCC   !: 95 ABBEBBBBB $ 8 8 8 8 8 8[ ,s## #wt^NKKKKrZrrrrrrc@tj|g|R||dS)u Sort 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 | └──────────────────┘ rrrrXrrrrras rYrzDataFrame.sortQs.Nuww|BWWWZJWWWWrZrrrrrrr>rrrcRt||||||S)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 | └──────────────────┘ rrrrrrrrXrrrrrrras rYrzDataFrame.joinzs2Zww|| sGh2f   rZrrrrrr:c Xt|||||||||  S)up Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. For Polars, both DataFrames must be sorted by the `on` key (within each `by` group if specified). 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 rXrrrrrrrrrras rYrzDataFrame.join_asofsBTww  !   rZc,|S)uGet 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_uniquerWs rY is_duplicatedzDataFrame.is_duplicateds(    rZc(t|dkS)aCheck 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)rrWs rYis_emptyzDataFrame.is_emptys4yyA~rZch||j|jS)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 | └───────────────┘ r_)rArPr5rRrWs rYr5zDataFrame.is_unique's+(||D1;;==T[|QQQrZc|j}|j|}||S)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](../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]] | └──────────────────┘ )rPr\rr null_countrb)rXrresults rYr;zDataFrame.null_count=sV6#::<<&--cggii.B.B.D.DEE##F+++rZr int | Nonecolumnint | str | Nonec:|j||S)aReturn 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 )rr>)rPr)rXrr>s rYrzDataFrame.item\s *$))c&)AAArZcZ||jS)ztCreate a copy of this DataFrame. Returns: An identical copy of the original dataframe. )rbrPclonerWs rYrBzDataFrame.cloness' ##D$9$?$?$A$ABBBrZrrcJt||S)u)Take 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)rXrrras rYrzDataFrame.gather_every{s"0ww##a#777rZ_)rvaluesaggregate_functionr sort_columns separatorstr | list[str]rErFPivotAgg | NonerGrHc |||d}t||%d}t|ttt |t r|gn|}t |t r|gn|}t |t r|gn|}||j||||||S)u Create 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| └─────────────────────────────────┘ Nz3At 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)rrrErFrGrH) rr UserWarningrrrrbrPpivot) rXrrrErFrrGrHrs rYrPzDataFrame.pivotst >emGCS// !  %7  {?P?P Q Q Q QC(( 0bTTb'44@&&%eS11<u##  ! ' '#5)# (     rZpa.Tablec4|jS)aConvert 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]] )rPrirWs rYrizDataFrame.to_arrows$$--///rZ)fractionwith_replacementseedrS float | NonerTrUcd||j||||S)uVSample 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 | └──────────────────┘ )rrSrTrU)rbrPsample)rXrrSrTrUs rYrXzDataFrame.samplesCH##  ! ( (h9IPT )     rZvariablerrrr rr cNt||||S)u[Unpivot 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 rr rXrrrr ras rYr zDataFrame.unpivot%s.dwwm    rZrrc8tj|g|RS)ukExplode 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 │ └─────┴─────┘ rrrXrrras rYrzDataFrame.explode[s#>uwww66666rZr)rSrD)rSrFr]rr`rQrSrKrSr)rSr)NN)rWrrXrYrSrGrSrrU)rarbrSr )rnrorSrp)rSrL)rSrz)rSr})rrKrSr)rrrSrK)rrrSr)rSrG)rSr)rrrSr)r)rrErSr)rrrSr)rrrSr)rrrSr2)rrrSr)rrrSr)rrrSr)rrrSr)rrrSr)rrrSrrrrrrr )rrrSr)rrrSr)rrrSr)rSr)rrrrrSr)rrrrrSr)rrrrrSrr!r"rr#rrrrrSr2)rrrrFrrrSr2r$)r rdr rrSr )r rr rrSr )r rdr rrSr r%r&r'r*)rSr)rSrrSr2)rr=r>r?rSrr(r))rrIrrrErrFrJrrYrGrrHrrSr2)rSrQ) rr=rSrVrTrrUr=rSr2r+r,)?r-r.r/__doc__rir1rArIrPrTrVr\r_rfrrr,r|rrrrrrrrrrrrrrrrxr{rrrrrrrrrrrrrrrrr6r8r5r;rrBrrPrirXr r __classcell__ras@rYr3r3sX 0@@@@2XX&&&&555X52////AAAAAPPPPNNNNN0CGL L L L L \3333.1111*111106666X6 @@@X@5555522222&????"+++X+ WWWW8?????0ZZZXZ X   X o>o>o>o>b####47WWWWWXW PPPXP <<<X<$(BBBBBB:00006777777>1111111:,,,,,,,2     X  ( ( ( ( ( (     X .3RRRRRXR HHHXH WWWXW %777777,::::>;>(((((X(:='''''X'14CCCCCXC %UUUUUU>#;#;#;#;#;#;J 5 5 5 5 5 5D''''''.(0BF>>>>>>>>4*.* $)$ * * * * * * X6:6:6:6:6:6:pUXXX LQ[L[L[L[L[L[LB-2 'X'X'X'X'X'X'X'XX&*# / +/+// / / / / / / / j##*.+/%)%/T T T T T T T T n!!!!,    RRRR,,,,,>BBBBB.CCCC8888888<)-)-.2&*"P P P P P P d0000,( "&!& ( ( ( ( ( ( X&*4 )-'! 4 4 4 4 4 4 4 4 l7777777777rZr3c (eZdZdZddZeddZdd ZddZeddZ ddZ dddZ ddZ dfd# Z ddfd' Zddfd* Zedfd, Zdfd- Zedfd/ Zdfd4 Zdfd5 Zdfd8 Zddfd< Zddfd= Zd>d?dfdDZ ddEdFddIZdfdM ZedNdOddTZeddVZdWdOddXZdWdWdYdfd_Z ddddadbdfdjZdddddddkdadldfdrZddsZ ddfdv Z! dddwdxdydfd|Z"dfd Z#xZ$S)rHaNarwhals 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) ``` rsrrScddlm}ddlm}t |t r|jSt ||rd}t|t |tr)| }| |St ||ra|j j rd}t||j jrd}t||| St#@dtt%|vr"dt%|d }t|t'jt%|) Nrr5r)zABinary operations between Series and LazyFrame are not supported.aOrder-dependent expressions are not supported for use in LazyFrame. Hint: To make the expression valid, use `.over` with `order_by` specified. For example, if you wrote `nw.col('price').cum_sum()` and you have a column `'date'` which orders your data, then replace: nw.col('price').cum_sum() with: nw.col('price').cum_sum().over(order_by='date') ^^^^^^^^^^^^^^^^^^^^^^ See https://narwhals-dev.github.io/narwhals/concepts/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()) r7r8r9)r;r6r<r*rrOrPr@rr\r _metadatan_orderable_opsr' is_filtrationr&rr#r?r%rC)rXrsr6r*rrs rYrizLazyFrame._extract_compliants&&&&&&****** c9 % % (' ' c6 " " !UCC.. c3   --//C773<<  c4  I}, 3^.c222}* 3I.c222))$*E*E*G*GHH H << #CS NN(B(B7$s))777  C.. "4T#YY???rZtype[DataFrame[Any]]ctSrU)r3rWs rY _dataframezLazyFrame._dataframerJrZr]r`rQrKc||_|t|r||_dSdt |}t |)NzVExpected Polars LazyFrame or an object that implements `__narwhals_lazyframe__`, got: )rRr__narwhals_lazyframe__rPr?rNrOs rYrPzLazyFrame.__init__s^  D !" % % &$&$=$=$?$?D ! ! !ukoprksksuuC %% %rZrcjtd|S)NzNarwhals LazyFramer^rWs rYr_zLazyFrame.__repr__r`rZrc|jjS)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 rRrWs rYrTzLazyFrame.implementations"$44rZr str | slicer c$d}t|)Nz%Slicing is not supported on LazyFrame)r@)rXrrs rYrzLazyFrame.__getitem__s5nnrZNrnrorDataFrame[Any]c |dntj|}tjtjtjf}|||vrd|d|d}t |||jjdd|i|dS) u 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: rrnrr_r) rrsrvPANDASPYARROWrrqrPcollect)rXrnr eager_backendsupported_eager_backendsrs rYr|zLazyFrame.collects~!(^5PQX5Y5Y  !  !  "$   $>V)V)V|C[||ly|||CS// ! )D ! ) J J- J6 J JRX   rZrKc$t|dS)uConvert 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_throughr+rWs rYr,zLazyFrame.to_native, s(EBBBBrZr}r~rrrrMc>tj|g|Ri|S)uPipe 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 rYrzLazyFrame.pipeC s+<uww|H6t666v666rZrrr2cHt|S)uDrop 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](../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 rYrzLazyFrame.drop_nullsc s >ww!!!000rZrrcFt|S)u Insert 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 rYrzLazyFrame.with_row_index s,ww%%d+++rZr(c*tjS)aGet 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 rYrxzLazyFrame.schema rrZcDtS)aGet 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 rYr{zLazyFrame.collect_schema rrZrc*tjS)aUGet 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 rYrzLazyFrame.columns rrZrcrdrer<c`|s|sd}t|tj|i|S)uEAdd 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)rrrrXrcrerras rYrzLazyFrame.with_columns sBN "[ "TCS// !#uww#U:k:::rZc`|s|sd}t|tj|i|S)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 rYrzLazyFrame.select sAJ "[ "NCS// !uww~u4 444rZrrcFt|S)uRename 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 rYrzLazyFrame.rename! s8ww~~g&&&rZrrrcFt|S)uGet `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 rYrzLazyFrame.head? rrZcFt|S)aGet 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 rYrzLazyFrame.tailW sww||ArZTrrrrrcPtjt|d|iS)uRemove 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 │ └───────┘ rrrs rYrzLazyFrame.dropg s(<uww|WW--=f===rZr)rrr?c|dvrd|d}t|t|tr|g}||j||S)uDrop 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)rXrrrs rYrzLazyFrame.unique sJ  & &WOSWWW S// ! fc " " XF##  ! ( (T ( B B   rZrrrct|dkr.t|dtr|sd}t|t j|i|S)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.)rrrr@rr)rXrrrras rYrzLazyFrame.filter s[^  OOq Z 1 t%D%D [ lCC.. uww~z9[999rZ.rr r rLazyGroupBy[Self]cdSrUrr s rYrzLazyFrame.group_by  CrZrcdSrUrr s rYrzLazyFrame.group_by rrZFc ddlm}t|}td|Dr||||Sddlm ddlm t fd|D}|r t|rd}t| fd t||D}|j |\}} td | Dsdd l m} d }| |||||S) ueStart 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 │ └─────────┴────────┘ Expressions are also accepted. >>> df.group_by(nw.col("b").str.len_chars()).agg( ... nw.col("a").sum() ... ).to_native() ┌───────┬────────┐ │ b │ a │ │ int64 │ int128 │ ├───────┼────────┤ │ 1 │ 6 │ └───────┴────────┘ r)r9c3@K|]}t|tVdSrUrrs rYrz%LazyFrame.group_by..H rrZrrr5c38K|]}t|VdSrUr)rrr6s rYrz%LazyFrame.group_by..N s-CCAJq$//CCCCCCrZz5drop_null_keys cannot be True when keys contains Exprc4g|]\}}|r|n |Srrrs rYrz&LazyFrame.group_by..T s.XXXjag)33q66XXXrZc32K|]}|tjuVdSrUrrs rYrz%LazyFrame.group_by..W rrZr r")r#r9rrr$rr;r6rrrvrrrr%r!) rXr r r9r& key_is_exprrr(r)rr!r6rs @@rYrzLazyFrame.group_by sgX 211111DMM 99y999 9 9 O;tY~NNN N      &&&&&&CCCCCCCCC  +c+.. +IC%c** *XXXXC ;>> 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 rYrzLazyFrame.sorta s.\uww|BWWWZJWWWWrZrrrrrrr>rrrcRt||||||S)u Add 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 │| |└───────┴─────────┴─────────┘| └─────────────────────────────┘ r.r/r0s rYrzLazyFrame.join s2lww|| sGh2f   rZrrrrrrr:c Xt|||||||||  S)u Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. For Polars, both DataFrames must be sorted by the `on` key (within each `by` group if specified). 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 │ └─────────────────────┴────────────┴──────┘ rr2r3s rYrzLazyFrame.join_asof sBZww  !   rZc|S)zRestrict available API methods to lazy-only ones. This is a no-op, and exists only for compatibility with `DataFrame.lazy`. Returns: A LazyFrame. rrWs rYrrzLazyFrame.lazy$ s  rZrrcpd}t|dt||S)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)rXrrrras rYrzLazyFrame.gather_every. s@  ^ "#9999ww##a#777rZrYrrZrr cNt||||S)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 r\r]s rYr zLazyFrame.unpivotF s.jwwm    rZrrc8tj|g|RS)uJExplode 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 │ └─────────┴───────┘ r_r`s rYrzLazyFrame.explode s$Fuwww66666rZr)rSrorarcrb)rrvrSr rU)rnrorrrSrx)rSrKrrrrrr r!r"rdr#re)rrrr?rSr2r$)r rdr rrSr)r rr rrSr)r rdr rrSrr%r&r'r*rfr(r)r+r,)%r-r.r/rgrir1rqrPr_rTrr|r,rrrrxr{rrrrrrrrrrrrrrrrrr rrhris@rYrHrH}s  -@-@-@-@^X&&&&PPPP555X5$ CGJ J J J J XCCCC.777777@1111111B,,,,,,,0     X  ( ( ( ( ( (     X *;*;*;*;*;*;X(5(5(5(5(5(5T''''''<0 BF>>>>>>>>D*./ (- / / / / / / bT:T:T:T:T:T:lUX     X    X LQGPGPGPGPGPGPZ-2 .X.X.X.X.X.X.X.Xf&*# 8 +/+/8 8 8 8 8 8 8 8 |##*.+/%)%/W W W W W W W W r88888884&*7 )-'! 7 7 7 7 7 7 7 7 r#7#7#7#7#7#7#7#7#7#7rZrH)h __future__rabcr itertoolsrtypingrrrr r r r r rrrwarningsrnarwhals._expression_parsingrrrrnarwhals._utilsrrrrrrrrrrr r!r"narwhals.dependenciesr#r$r%r%r&r'narwhals.schemar(r<r*narwhals.translater,ior-pathlibr.typesr/pandaspdr7plrgrktyping_extensionsr0r1r2r3narwhals._compliantr4r5narwhals._compliant.typingr6r7r#r8r9narwhals.typingr:r;r<r=r>r?r@_MultiColSelectorrA_MultiIndexSelectorrBrCrDrErFrGrHrIrKrLrMr0rOr3rHrrZrYrs"""""""                           =<<<<<<< #"""""""""""((((((      IIIIIIIIIIIIJJJJJJJJNNNNNNNN66666666" 4B '); / / /  - - - W\ 9 9 9  GCLL>>>>> BBBBBvWvWvWvWvW vWvWvWr e7e7e7e7e7 *%e7e7e7P7e7e7e7e7e7 &!e7e7e7e7e7rZ