Ë TÇ.h;žãó—ddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZddlmZddlmZddlmZddlmZddlmZddlmZerTddlmZddlmZddlmZddlZ ddl!Z"ddl#Z$ddl%m&Z&ddl'm(Z(ddl'm)Z)ddl*m+Z+ddl,m-Z-ddl,m.Z.ddl,m/Z/ddl,m0Z0dd lm1Z1e d!d"¬#«Z2e d$d%¬#«Z3Gd&„d'ee2«Z4Gd(„d)e4e3«Z5Gd*„d+e4e2«Z6y),é)Ú annotations)Ú TYPE_CHECKING)ÚAny)ÚCallable)ÚGeneric)ÚIterable)ÚIterator)ÚLiteral)ÚNoReturn)ÚSequence)ÚTypeVar)Úoverload)Ú get_polars)Úis_numpy_array)ÚSchema©Ú to_native)Úflatten)Úis_sequence_but_not_str)Ú parse_version)ÚBytesIO)ÚPath)Ú ModuleTypeN)ÚSelf©ÚGroupBy©Ú LazyGroupBy©ÚSeries)Ú IntoDataFrame)ÚIntoExpr)Ú IntoFrame)ÚSizeUnit)ÚImplementationÚFrameTr#)ÚboundÚ DataFrameTr!cóâ—eZdZUded<ded<d)d„Zd*d„Zd+d„Zd,d„Zd-d „Ze d.d „«Z d.d „Z d/d „Z d0d1d „Z d2d3d„Ze d4d„«Z d5d„Z d5d„Zd6d„Zd7d„Zd7d„Zd8d„Z d2dddœ d9d„Z d:d„Zdddœ d;d„Z dd!„Zd?d@d"„Zddddddd#d$œ dAd%„Z dBd&„ZdCd'„ZdDd(„Zy)EÚ BaseFramerÚ_compliant_frameú&Literal['full', 'lazy', 'interchange']Ú_levelcó6—|jj«S©N)r+Ú__native_namespace__©Úselfs úf/var/www/html/School_Mangement_New/src/backend/venv/lib/python3.12/site-packages/narwhals/dataframe.pyr0zBaseFrame.__native_namespace__2s€Ø×$Ñ$×9Ñ9Ó;Ð;ócó6—|jj«Sr/)r+Ú__narwhals_namespace__r1s r3r6z BaseFrame.__narwhals_namespace__5s€Ø×$Ñ$×;Ñ;Ó=Ð=r4có<—|j||j¬«S)N©Úlevel)Ú __class__r-)r2Údfs r3Ú_from_compliant_dataframez#BaseFrame._from_compliant_dataframe8s"€à~‰~Ø Ø—+‘+ðó ð r4cóҗt|«Dcgc]}|j|«‘Œ}}|j«Dcic]\}}||j|«“Œ}}}||fScc}wcc}}w)zDProcess `args` and `kwargs`, extracting underlying objects as we go.)rÚ_extract_compliantÚitems)r2ÚargsÚkwargsÚvÚks r3Ú_flatten_and_extractzBaseFrame._flatten_and_extract?sd€ä4;žD³MÖBšq×'Ñ'šÕ*ÐBˆÐBØzBaseFrame._extract_compliantEsš€Ý&Ý*ä cœ9Ô %Ø×'Ñ'Ð 'Ü c˜6Ô "Ø×(Ñ(Ð (Ü c˜4Ô Ø×)Ñ)š$×*EÑ*EÓ*GÓHÐ HÜ ‹<Ð #šŽCŒžS» ³NÑ(Bà1Ž$°s³)°ð=7ð7ð ô ˜C“.Р؈ r4có\—t|jjj««Sr/)rr+Úschemar?r1s r3rSzBaseFrame.schemaYs"€äd×+Ñ+×2Ñ2×8Ñ8Ó:Ó;Ð;r4có^—t|jj««}t|«Sr/)Údictr+Úcollect_schemar)r2Ú native_schemas r3rVzBaseFrame.collect_schema]s&€Ü˜T×2Ñ2×AÑAÓCÓDˆ ämÓ$Ð$r4có—||g|¢­i|€ŽSr/©)r2Úfunctionr@rAs r3ÚpipezBaseFrame.pipebs€Ù˜Ð.˜tÒ. vÑ.Ð.r4cóV—|j|jj|««Sr/)r<r+Úwith_row_index©r2Únames r3r]zBaseFrame.with_row_indexes)€Ø×-Ñ-Ø × !Ñ !× 0Ñ 0°Ó 6ó ð r4NcóX—|j|jj|¬««S)N©Úsubset)r<r+Ú drop_nulls)r2rbs r3rczBaseFrame.drop_nullsjs,€Ø×-Ñ-Ø × !Ñ !× ,Ñ ,°FÐ ,Ó ;ó ð r4có.—|jjSr/)r+Úcolumnsr1s r3rezBaseFrame.columnsos€à×$Ñ$×,Ñ,Ð,r4có‚—|j|i|€Ž\}}|j|jj|i|€Ž«Sr/)rDr<r+Ú with_columns©r2ÚexprsÚ named_exprss r3rgzBaseFrame.with_columnsssN€ð7˜T×6Ñ6žÐMÀÑMшˆ{Ø×-Ñ-Ø .ˆD× !Ñ !× .Ñ .°Ð EžÑ Eó ð r4có‚—|j|i|€Ž\}}|j|jj|i|€Ž«Sr/)rDr<r+Úselectrhs r3rlzBaseFrame.select{sN€ð 7˜T×6Ñ6žÐMÀÑMшˆ{Ø×-Ñ-Ø (ˆD× !Ñ !× (Ñ (š%Ð ?°;Ñ ?ó ð r4cóV—|j|jj|««Sr/)r<r+Úrename)r2Úmappings r3rnzBaseFrame.rename…s$€Ø×-Ñ-šd×.CÑ.C×.JÑ.JÈ7Ó.SÓTÐTr4cóV—|j|jj|««Sr/)r<r+Úhead©r2Úns r3rqzBaseFrame.headˆó$€Ø×-Ñ-šd×.CÑ.C×.HÑ.HÈÓ.KÓLÐLr4cóV—|j|jj|««Sr/)r<r+Útailrrs r3rvzBaseFrame.tail‹rtr4cóZ—|j|jj||¬««S)N©Ústrict)r<r+Údrop)r2ryres r3rzzBaseFrame.dropŽs.€Ø×-Ñ-Ø × !Ñ !× &Ñ & w°vÐ &Ó >ó ð r4ÚanyF©ÚkeepÚmaintain_ordercó\—|j|jj|||¬««S)N)rbr}r~)r<r+Úunique)r2rbr}r~s r3r€zBaseFrame.unique“s7€ð×-Ñ-Ø × !Ñ !× (Ñ (Ø Džð )ó ó ð r4cóî—t|«dk(r(t|dt«rtd„|dD««s|j|i|€Ž\}}|j |j j|i|€Ž«S)Nérc3ó<K—|]}t|t«–—Œy­wr/)rJÚbool)Ú.0Úxs r3ú z#BaseFrame.filter..Šsèø€Ò?šA”J˜q€$×'Ñ?ùs‚)ÚlenrJÚlistÚallrDr<r+Úfilter)r2Ú predicatesÚ constraintss r3r‹zBaseFrame.filter s‚€ô  ‹O˜qÒ Ü˜: a™=¬$Ô/ÜÑ?°žA±Ô?Ô?à&? d×&?Ñ&?Øð'Ø*ñ'Ñ #ˆJ˜ ð×-Ñ-Ø (ˆD× !Ñ !× (Ñ (š*Ð Dž Ñ Dó ð r4©Ú descendingÚ nulls_lastcób—|j|jj|g|¢­||dœŽ«S)NrŽ)r<r+Úsort)r2ÚbyrrÚmore_bys r3r’zBaseFrame.sort¯sB€ð×-Ñ-Ø &ˆD× !Ñ !× &Ñ &Øð Øñ Ø)3À ò ó ð r4Ú_right©Úleft_onÚright_onÚsuffixc ó^—d}||vrd|›d|›d}t|«‚|dk(r|€|€| d}t|«‚|dk7r|€||€d|›d}t|«‚|dk7r||€|d |›d}t|«‚||x}}|j|jj |j |«||||¬ ««S) N)ÚinnerÚleftÚcrossÚantiÚsemiz2Only the following join strategies are supported: ú ; found 'ú'.rz>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 )Úhowr—r˜r™)ÚNotImplementedErrorÚ ValueErrorr<r+Újoinr>) r2ÚotherÚonr£r—r˜r™Ú_supported_joinsrQs r3rŠzBaseFrame.joinŒs€ðFÐà Ð&Ñ &ØFÐGWÐFXÐXaÐbeÐafÐfhÐiˆCÜ% cÓ*Ð *à 'Š>Ø Ð  8Ð#7ž2ž>àRˆCܘS“/Ð !à 'Š>˜r˜zšwšÀ(ÐBRØ[Ð\_Ð[`Ð`aÐbˆCܘS“/Ð !à 'Š>Ø ˆN Ð 3°xÐ7KàVÐWZÐV[Ð[\Ð]ˆCܘS“/Ð !à ˆ>Ø!#Ð #ˆGhà×-Ñ-Ø × !Ñ !× &Ñ &Ø×'Ñ'šÓ.ØØØ!Øð 'ó ó ð r4cóT—|j|jj««Sr/)r<r+Úcloner1s r3r«zBaseFrame.cloneés"€Ø×-Ñ-šd×.CÑ.C×.IÑ.IÓ.KÓLÐLr4cóZ—|j|jj||¬««S)N©rsÚoffset)r<r+Ú gather_every)r2rsr®s r3r¯zBaseFrame.gather_everyìs.€Ø×-Ñ-Ø × !Ñ !× .Ñ .°ž6Ð .Ó Bó ð r4Úbackward©r—r˜ršÚby_leftÚby_rightr“Ústrategyc óØ—d} || vrd| ›d|›d} t| «‚|€||€ d} t| «‚||€| d} t| «‚|€|€|€||€ d} t| «‚||€| d} t| «‚|?|j|jj |j |«|||||¬ ««S|j|jj |j |«||||||¬ ««S) N)r°ÚforwardÚnearestz-Only the following strategies are supported: r r¡zCEither (`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.)ršr²r³r“rŽ)r—r˜r²r³r“rŽ)r€r¥r<r+Ú join_asofr>) r2r§r—r˜ršr²r³r“rŽÚ_supported_strategiesrQs r3ržzBaseFrame.join_asofñs_€ð!CÐà Ð0Ñ 0ØAÐBWÐAXÐXaÐbjÐakÐkmÐnˆCÜ% cÓ*Ð *à ˆJ˜W˜_°Ð0@ØWˆCܘS“/Ð !Ø ˆN Ð!4žÐ8LØRˆCܘS“/Ð !Ø ˆJØ ˆ_ Ð!5ØÐ#šÐ(8ðZð ô˜S“/Ð !Ø ˆN Ð!4žÐ8LØRˆCܘS“/Ð !Ø ˆ>Ø×1Ñ1Ø×%Ñ%×/Ñ/Ø×+Ñ+šEÓ2ØØ#Ø%ØØ%ð 0óó ð ð×-Ñ-Ø × !Ñ !× +Ñ +Ø×'Ñ'šÓ.ØØ!ØØ!ØØ!ð ,ó ó  ð r4có^—|j|jj||||¬««S)N©ršÚindexÚ variable_nameÚ value_name)r<r+Úunpivot)r2ršrŒrœrŸs r3r¿zBaseFrame.unpivot+s<€ð×-Ñ-Ø × !Ñ !× )Ñ )ØØØ+Ø%ð *ó ó ð r4có—d}t|«‚)Nz«DataFrame.__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)©r€©r2r§rQs r3Ú__neq__zBaseFrame.__neq__<ó€ð +ð ô" #Ó&Ð&r4có—d}t|«‚)Nz©DataFrame.__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)rÁrÂs r3Ú__eq__zBaseFrame.__eq__GrÄr4)r2rÚreturnr©rÇr)r;rrÇr)r@rrArrÇr)rPrrÇr©rÇr©rZzCallable[[Any], Self]r@rrArrÇr©rŒ©r_rMrÇrr/©r2rrbústr | list[str] | NonerÇr©rÇz list[str]©rizIntoExpr | Iterable[IntoExpr]rjr"rÇr©rozdict[str, str]rÇr©rsÚintrÇr)rez Iterable[str]ryr„rÇr©rbrÎr}z'Literal['any', 'first', 'last', 'none']r~r„rÇr©rŒz*IntoExpr | Iterable[IntoExpr] | list[bool]rrrÇr© r“ústr | Iterable[str]r”rMrzbool | Sequence[bool]rr„rÇr©Nr›©r§rršrÎr£z1Literal['inner', 'left', 'cross', 'semi', 'anti']r—rÎr˜rÎr™rMrÇr©rÇr©r©r2rrsrÓr®rÓrÇr©r§rr—ú str | Noner˜rÞršrÞr²rÎr³rÎr“rÎrŽz)Literal['backward', 'forward', 'nearest']rÇr© r2rršrÎrŒrÎrœrÞrŸrÞrÇr)r§rrÇr )r§ÚobjectrÇr ) Ú__name__Ú __module__Ú __qualname__Ú__annotations__r0r6r<rDr>ÚpropertyrSrVr[r]rcrergrlrnrqrvrzr€r‹r’rŠr«r¯ržr¿rÃrÆrYr4r3r*r*.sx…ØÓØ 2Ó2ó<ó>ó óó ð(ò<óð<ó%ó /ô ô  ð ò-óð-ð Ø3ð ØDLð à ó ð à-ð ð ð ð ó  óUóMóMó ð*.ð  ð9>Ø$ñ  à&ð  ð6ð  ð ð  ð ó  ð  ØEð  ØVYð  à ó  ð&-2Ø ñ  à ð  ðð  ð*ð  ð ð  ð ó  ð &*ØAHð + ð +/Ø+/Øñ+ àð+ ð #ð+ ð?ð + ð (ð + ð)ð+ ðð+ ð ó+ óZMô ð#Ø#ØØ*.Ø+/Ø%)Ø>Hñ8 àð8 ðð 8 ð ð 8 ð ð 8 ð(ð8 ð)ð8 ð #ð8 ð<ð8 ð ó8 ðt Øð à "ð ð&ð  ð "ð  ð ð  ð ó ó" 'ô 'r4r*cóÔ‡—eZdZdZedcd„«Zeddd„«Z ded„Zedfd„«Zdgd„Z dhdid„Z djd „Z dkdld „Z dmd „Z dnd „Zdod „Zdkdpd„Zdqd„Zdrd„Zedsd„«Zdtd„Zdudvd„Zedwd„«Zedxd„«Zedyd„«Zedzd„«Zed{d„«Zed|d„«Zed}d„«Zed~d„«Zedd„«Zed€d„«Zedd„«Zed‚d„«Zedƒd „«Zed„d!„«Z d…d"„Zd†d#„Zed$d%œd‡d&„«Zedˆd'„«Ze d‰d(„«Zd)d%œ d‰d*„ZdŠd+„Zd‹ˆfd,„ ZdkdŒˆfd-„ ZddŽˆfd.„ Zedˆfd/„ «Zdˆfd0„ Zed‘ˆfd1„ «Z ed2d3œ d’d4„«Z!e d“d5„«Z!e d”d6„«Z!d2d3œ d”d7„Z!ed$d8œ d•d9„«Z"ed$d8œ d–d:„«Z"ed$d8œ d—d;„«Z"d2d„Z" d˜ˆfd?„ Z# d˜ˆfd@„ Z$d™ˆfdA„ Z%dšd›ˆfdB„ Z&dšd›ˆfdC„ Z'd)dDœdœˆfdE„Z( dkdFd2dGœ dˆfdH„Z) džˆfdI„ Z*d2dJœ dŸdK„Z+d2d2dLœ d ˆfdM„Z, d¡dddNdOœ d¢ˆfdP„Z-dddddddQdRœ d£ˆfdS„Z.d€dT„Z/d¥dU„Z0d€dV„Z1dŠdW„Z2dhd§dX„Z3dšˆfdY„ Z4d©dªˆfdZ„ Z5dddd)d2d[d\œ d«d]„Z6d¬d^„Z7 dkdd2dd_œ d­d`„Z8 dkddddaœ d®ˆfdb„Z9ˆxZ:S)¯Ú DataFramezåNarwhals DataFrame, backed by a native dataframe. The native dataframe might be pandas.DataFrame, polars.DataFrame, ... This class is not meant to be instantiated directly - instead, use `narwhals.from_native`. có—ddlm}|S)Nrr)rIr )r2r s r3Ú_serieszDataFrame._series\s €å*àˆ r4có—tSr/)Ú LazyFramer1s r3Ú _lazyframezDataFrame._lazyframebó€äÐr4có†—||_t|d«r|j«|_ydt |«›}t |«‚)NÚ__narwhals_dataframe__zCExpected an object which implements `__narwhals_dataframe__`, got: )r-Úhasattrrïr+rNÚAssertionError©r2r;r9rQs r3Ú__init__zDataFrame.__init__fsG€ð ?DˆŒ Ü 2Ð/Ô 0Ø)+×)BÑ)BÓ)DˆDÕ !àWÔX\Ð]_ÓX`ÐWaÐbˆCÜ  Ó%Ð %r4có.—|jjS)aóReturn implementation of native frame. This can be useful when you need to some special-casing for some libraries for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import pandas as pd >>> 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 ©r+Ú_implementationr1s r3ÚimplementationzDataFrame.implementationss€ð2×$Ñ$×4Ñ4Ð4r4có6—|jj«Sr/)r+Ú__len__r1s r3rùzDataFrame.__len__Žs€Ø×$Ñ$×,Ñ,Ó.Ð.r4Ncó<—|jj||¬«S)N)Úcopy)r+Ú __array__)r2Údtyperûs r3rüzDataFrame.__array__‘s€Ø×$Ñ$×.Ñ.šuž4Ð.Ó@Ð@r4có^—d}t|«}dd|zzdzd|›dzdzdzd|zzd zS) Nz' Narwhals DataFrame õ┌õ─õ┐ ú|ú| ú*| Use `.to_native` to see native output | õ└õ┘©rˆ©r2ÚheaderÚlengths r3Ú__repr__zDataFrame.__repr__”ój€Ø:ˆÜV“ˆà ؐf‰nñ àñ ð&˜ˆoñ ð<ñ  <ð ñ  ð f‰nñ  ðñ ð r4cór—|jj}t|d«r|j|¬«S ddl}t|j«dkrdt |«›}t |«d‚|j«}|j|¬«S#t $r}dt |«›}t |«|‚d}~wwxYw)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. Ú__arrow_c_stream__)Úrequested_schemarNzRPyArrow>=14.0.0 is required for `DataFrame.__arrow_c_stream__` for object of type )ér) r+Ú _native_framerðrÚpyarrowÚModuleNotFoundErrorrNrÚ __version__Úto_arrow)r2rÚ native_frameÚpaÚexcrQÚpa_tables r3rzDataFrame.__arrow_c_stream__¢sĀð×,Ñ,×:Ñ:ˆ Ü <Ð!5Ô 6Ø×2Ñ2ÐDTÐ2ÓUÐ Uð 4Û ô ˜Ÿ™Ó (š7Ò 2ØfÔgkÐlxÓgyÐfzÐ{ˆCÜ% cÓ*°Ð 4Ø—=‘=“?ˆØ×*Ñ*Ð>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_lazy(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.lazy().to_native() Note that then, pandas and pyarrow dataframe stay eager, but Polars DataFrame becomes a Polars LazyFrame: >>> agnostic_lazy(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_lazy(df_pl) >>> agnostic_lazy(df_pa) pyarrow.Table foo: int64 bar: double ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] Úlazyr8)rìr+rr1s r3rzDataFrame.lazy¹s'€ð^‰˜t×4Ñ4×9Ñ9Ó;À6ˆÓJÐJr4có.—|jjS)uõConvert Narwhals DataFrame to native one. Returns: Object of class that user started with. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Calling `to_native` on a Narwhals DataFrame returns the native object: >>> nw.from_native(df_pd).to_native() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> nw.from_native(df_pl).to_native() shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ 2 ┆ 7.0 ┆ b │ │ 3 ┆ 8.0 ┆ c │ └─────┮─────┮─────┘ >>> nw.from_native(df_pa).to_native() pyarrow.Table foo: int64 bar: double ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] )r+rr1s r3rzDataFrame.to_nativeês€ðX×$Ñ$×2Ñ2Ð2r4có6—|jj«S)ašConvert this DataFrame to a pandas DataFrame. Returns: A pandas DataFrame. Examples: Construct pandas, Polars (eager) and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_to_pandas(df_native: IntoDataFrame) -> pd.DataFrame: ... df = nw.from_native(df_native) ... return df.to_pandas() We can then pass any supported library such as pandas, Polars (eager), or PyArrow to `agnostic_to_pandas`: >>> agnostic_to_pandas(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_to_pandas(df_pl) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_to_pandas(df_pa) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c )r+Ú to_pandasr1s r3rzDataFrame.to_pandass€ð\×$Ñ$×.Ñ.Ó0Ð0r4có8—|jj|«S)a\Write 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: Construct pandas, Polars (eager) and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def func(df): ... df = nw.from_native(df) ... return df.write_csv() We can pass any supported library such as pandas, Polars or PyArrow to `func`: >>> func(df_pd) 'foo,bar,ham\n1,6.0,a\n2,7.0,b\n3,8.0,c\n' >>> func(df_pl) 'foo,bar,ham\n1,6.0,a\n2,7.0,b\n3,8.0,c\n' >>> func(df_pa) '"foo","bar","ham"\n1,6,"a"\n2,7,"b"\n3,8,"c"\n' If we had passed a file name to `write_csv`, it would have been written to that file. )r+Ú write_csv©r2Úfiles r3r zDataFrame.write_csvHs€ðP×$Ñ$×.Ñ.štÓ4Ð4r4có:—|jj|«y)a Write dataframe to parquet file. Arguments: file: String, path object or file-like object to which the dataframe will be written. Returns: None. Examples: Construct pandas, Polars and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def func(df): ... df = nw.from_native(df) ... df.write_parquet("foo.parquet") We can then pass either pandas, Polars or PyArrow to `func`: >>> func(df_pd) # doctest:+SKIP >>> func(df_pl) # doctest:+SKIP >>> func(df_pa) # doctest:+SKIP N)r+Ú write_parquetr!s r3r$zDataFrame.write_parquetrs€ðD ×Ñ×+Ñ+šDÕ1r4có6—|jj«S)a‘Convert this DataFrame to a NumPy ndarray. Returns: A NumPy ndarray array. Examples: Construct pandas and polars DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> import numpy as np >>> from narwhals.typing import IntoDataFrame >>> >>> df = {"foo": [1, 2, 3], "bar": [6.5, 7.0, 8.5], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_to_numpy(df_native: IntoDataFrame) -> np.ndarray: ... df = nw.from_native(df_native) ... return df.to_numpy() We can then pass either pandas, Polars or PyArrow to `agnostic_to_numpy`: >>> agnostic_to_numpy(df_pd) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) >>> agnostic_to_numpy(df_pl) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) >>> agnostic_to_numpy(df_pa) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) )r+Úto_numpyr1s r3r&zDataFrame.to_numpy–s€ðT×$Ñ$×-Ñ-Ó/Ð/r4có.—|jjS)aGet the shape of the DataFrame. Returns: The shape of the dataframe as a tuple. Examples: Construct pandas and polars DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> >>> df = {"foo": [1, 2, 3, 4, 5]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_shape(df_native: IntoDataFrame) -> tuple[int, int]: ... df = nw.from_native(df_native) ... return df.shape We can then pass either pandas, Polars or PyArrow to `agnostic_shape`: >>> agnostic_shape(df_pd) (5, 1) >>> agnostic_shape(df_pl) (5, 1) >>> agnostic_shape(df_pa) (5, 1) )r+Úshaper1s r3r(zDataFrame.shapeÂs€ðH×$Ñ$×*Ñ*Ð*r4cón—|j|jj|«|j¬«S)a^Get 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 polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def agnostic_get_column(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native) ... name = df.columns[0] ... return df.get_column(name).to_native() We can then pass either pandas or Polars to `agnostic_get_column`: >>> agnostic_get_column(df_pd) 0 1 1 2 Name: a, dtype: int64 >>> agnostic_get_column(df_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 1 2 ] r8)rér+Ú get_columnr-r^s r3r*zDataFrame.get_columnès6€ð`|‰|Ø × !Ñ !× ,Ñ ,šTÓ 2Ø—+‘+ðó ð r4có:—|jj|¬«S)aƒReturn an estimation of the total (heap) allocated size of the `DataFrame`. Estimated size is given in the specified unit (bytes by default). Arguments: unit: 'b', 'kb', 'mb', 'gb', 'tb', 'bytes', 'kilobytes', 'megabytes', 'gigabytes', or 'terabytes'. Returns: Integer or Float. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrameT >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_estimated_size(df_native: IntoDataFrameT) -> int | float: ... df = nw.from_native(df_native) ... return df.estimated_size() We can then pass either pandas, Polars or PyArrow to `agnostic_estimated_size`: >>> agnostic_estimated_size(df_pd) np.int64(330) >>> agnostic_estimated_size(df_pl) 51 >>> agnostic_estimated_size(df_pa) 63 )Úunit)r+Úestimated_size)r2r,s r3r-zDataFrame.estimated_sizes€ðT×$Ñ$×3Ñ3žÐ3Ó>Ð>r4có—yr/rY©r2Úitems r3Ú __getitem__zDataFrame.__getitem__Ió€ØFIr4có—yr/rYr/s r3r1zDataFrame.__getitem__Kó€ØNQr4có—yr/rYr/s r3r1zDataFrame.__getitem__Mr2r4có—yr/rYr/s r3r1zDataFrame.__getitem__Oó€ØKNr4có—yr/rYr/s r3r1zDataFrame.__getitem__Qó€ØCFr4có—yr/rYr/s r3r1zDataFrame.__getitem__Sr4r4có—yr/rYr/s r3r1zDataFrame.__getitem__Ur2r4có—yr/rYr/s r3r1zDataFrame.__getitem__Wr7r4có—yr/rYr/s r3r1zDataFrame.__getitem__Yr9r4có—yr/rYr/s r3r1zDataFrame.__getitem__\ó€Ø8;r4có—yr/rYr/s r3r1zDataFrame.__getitem___s€Ø58r4có—yr/rYr/s r3r1zDataFrame.__getitem__br?r4có—yr/rYr/s r3r1zDataFrame.__getitem__es€Ø03r4có—yr/rYr/s r3r1zDataFrame.__getitem__hs€Ø>Ar4cóT—t|t«r|g}t|t«rAt|«dk(r3t|dttf«rdt |«›d}t |«‚t|t«rqt|«dk(rct|d«st|dt«rB|dtd«k(r|dtd«k(r|S|j|j|«St|t«st|t«r8t|«dk(r*|j|j||j¬«St|«s*t|t«st|«r-|jdk(r|j|j|«Sdt |«›}t |«‚)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 polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_slice(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native) ... return df["a"].to_native() We can then pass either pandas, Polars or PyArrow to `agnostic_slice`: >>> agnostic_slice(df_pd) 0 1 1 2 Name: a, dtype: int64 >>> agnostic_slice(df_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 1 2 ] >>> agnostic_slice(df_pa) # doctest:+ELLIPSIS [ [ 1, 2 ] ] érzExpected str or slice, got: z]. Hint: if you were trying to get a single element out of a dataframe, use `DataFrame.item`.r‚Nr8)rJrÓÚtuplerˆrMrNrOrÚslicer<r+rér-rÚndim©r2r0rQs r3r1zDataFrame.__getitem__ksy€ô| dœCÔ Ø6ˆDä tœUÔ #ܐD“ ˜Q’ܘD ™G€c¬3 ZÔ0ð/¬t°D«zšlð;3ð3ð ô ˜C“.Ð ä tœUÔ #ܐD“ ˜Q’Ü(šša©Ô1ŽZÀÀQÁÌÔ5OàA‰wœ% ›+Ò%š$šq©'ŽUž4³[Ò*@ؐ Ø×1Ñ1°$×2GÑ2GÈÑ2MÓNÐ NÜ dœCÔ €Z°ŽeÔ%<ÄÀTÃÈaÂØ—<‘<Ø×%Ñ% dÑ+Ø—k‘kð óð ô $ DÔ )ܘ$€Ô&ܘtÔ$š¯©°aªà×1Ñ1°$×2GÑ2GÈÑ2MÓNÐ Nð1Ž°d³° Ð=ˆCܘC“.Ð r4có—||jvSr/)re)r2Úkeys r3Ú __contains__zDataFrame.__contains__ïs€Ød—l‘lÐ"Ð"r4.©Ú as_seriescó—yr/rY©r2rNs r3Úto_dictzDataFrame.to_dictòs€ØTWr4có—yr/rYrPs r3rQzDataFrame.to_dictôs€ØMPr4có—yr/rYrPs r3rQzDataFrame.to_dictös€ð9>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> >>> df = { ... "A": [1, 2, 3, 4, 5], ... "fruits": ["banana", "banana", "apple", "apple", "banana"], ... "B": [5, 4, 3, 2, 1], ... "animals": ["beetle", "fly", "beetle", "beetle", "beetle"], ... "optional": [28, 300, None, 2, -30], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_to_dict( ... df_native: IntoDataFrame, ... ) -> dict[str, list[int | str | float | None]]: ... df = nw.from_native(df_native) ... return df.to_dict(as_series=False) We can then pass either pandas, Polars or PyArrow to `agnostic_to_dict`: >>> agnostic_to_dict(df_pd) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28.0, 300.0, nan, 2.0, -30.0]} >>> agnostic_to_dict(df_pl) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} >>> agnostic_to_dict(df_pa) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} rMr8)r+rQr?rér-)r2rNrKÚvalues r3rQzDataFrame.to_dictúsŒ€ñ^ ð #'×"7Ñ"7×"?Ñ"?Ø'ð#@ó#ç‘%“'÷ñ C˜ð T—\‘\ØØŸ+™+ð"óñóð ð×$Ñ$×,Ñ,°yÐ,ÓAÐAùós°(A8có8—|jj|«S)a~Get values at given row. !!!note 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. Notes: cuDF doesn't support this method. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoDataFrame >>> from typing import Any >>> >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a library-agnostic function to get the second row. >>> def agnostic_row(df_native: IntoDataFrame) -> tuple[Any, ...]: ... df = nw.from_native(df_native) ... return df.row(1) We can then pass pandas / Polars / any other supported library: >>> agnostic_row(df_pd) (2, 5) >>> agnostic_row(df_pl) (2, 5) )r+Úrow)r2rŒs r3rWz DataFrame.row5s€ðJ×$Ñ$×(Ñ(šÓ/Ð/r4có*•—t‰||g|¢­i|€ŽS)uÒPipe function call. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "ba": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_pipe(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.pipe( ... lambda _df: _df.select( ... [x for x in _df.columns if len(x) == 1] ... ).to_native() ... ) We can then pass either pandas or Polars: >>> agnostic_pipe(df_pd) a 0 1 1 2 2 3 >>> agnostic_pipe(df_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ ©Úsuperr[©r2rZr@rAr:s €r3r[zDataFrame.pipe]sø€ôT‰w‰|˜HÐ6 tÒ6švÑ6Ð6r4có$•—t‰||¬«S)ušDrop null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1.0, 2.0, None], "ba": [1.0, None, 2.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_drop_nulls(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop_nulls().to_native() We can then pass either pandas or Polars: >>> agnostic_drop_nulls(df_pd) a ba 0 1.0 1.0 >>> agnostic_drop_nulls(df_pl) shape: (1, 2) ┌─────┬─────┐ │ a ┆ ba │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞═════╪═════╡ │ 1.0 ┆ 1.0 │ └─────┮─────┘ ra©rZrc©r2rbr:s €r3rczDataFrame.drop_nulls‰óø€ôT‰wÑ!šÐ!Ó0Ð0r4có"•—t‰||«S)u­Insert column which enumerates rows. Examples: Construct pandas as polars DataFrames: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_with_row_index(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_row_index().to_native() We can then pass either pandas or Polars: >>> agnostic_with_row_index(df_pd) index a b 0 0 1 4 1 1 2 5 2 2 3 6 >>> agnostic_with_row_index(df_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ index ┆ a ┆ b │ │ --- ┆ --- ┆ --- │ │ u32 ┆ i64 ┆ i64 │ ╞═══════╪═════╪═════╡ │ 0 ┆ 1 ┆ 4 │ │ 1 ┆ 2 ┆ 5 │ │ 2 ┆ 3 ┆ 6 │ └───────┮─────┮─────┘ ©rZr]©r2r_r:s €r3r]zDataFrame.with_row_indexµsø€ôP‰wÑ% dÓ+Ð+r4có•—t‰|S)a‚Get an ordered mapping of column names to their data type. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.schema import Schema >>> from narwhals.typing import IntoFrame >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def agnostic_schema(df_native: IntoFrame) -> Schema: ... df = nw.from_native(df_native) ... return df.schema You can pass either pandas or Polars to `agnostic_schema`: >>> df_pd_schema = agnostic_schema(df_pd) >>> df_pd_schema Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> df_pl_schema = agnostic_schema(df_pl) >>> df_pl_schema Schema({'foo': Int64, 'bar': Float64, 'ham': String}) ©rZrS©r2r:s €r3rSzDataFrame.schemaßsø€ôF‰w‰~Ðr4có •—t‰|«S)a¬Get an ordered mapping of column names to their data type. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.schema import Schema >>> from narwhals.typing import IntoFrame >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def agnostic_collect_schema(df_native: IntoFrame) -> Schema: ... df = nw.from_native(df_native) ... return df.collect_schema() You can pass either pandas or Polars to `agnostic_collect_schema`: >>> df_pd_schema = agnostic_collect_schema(df_pd) >>> df_pd_schema Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> df_pl_schema = agnostic_collect_schema(df_pl) >>> df_pl_schema Schema({'foo': Int64, 'bar': Float64, 'ham': String}) ©rZrVres €r3rVzDataFrame.collect_schemasø€ôD‰wÑ%Ó'Ð'r4có•—t‰|S)aèGet column names. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> df_pa = pa.table(df) We define a library agnostic function: >>> def agnostic_columns(df_native: IntoFrame) -> list[str]: ... df = nw.from_native(df_native) ... return df.columns We can pass any supported library such as pandas, Polars, or PyArrow to `func`: >>> agnostic_columns(df_pd) ['foo', 'bar', 'ham'] >>> agnostic_columns(df_pl) ['foo', 'bar', 'ham'] >>> agnostic_columns(df_pa) ['foo', 'bar', 'ham'] ©rZreres €r3rezDataFrame.columns(sø€ô>‰w‰Ðr4F©Únamedcó—yr/rY©r2rks r3ÚrowszDataFrame.rowsIs€ð !$r4có—yr/rYrms r3rnzDataFrame.rowsOs€ð #r4có—yr/rYrms r3rnzDataFrame.rowsUs€ð 8;r4có:—|jj|¬«S)a^Returns 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) We define a library agnostic function: >>> @nw.narwhalify ... def func(df, *, named): ... return df.rows(named=named) We can then pass either pandas or Polars to `func`: >>> func(df_pd, named=False) [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> func(df_pd, named=True) [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> func(df_pl, named=False) [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> func(df_pl, named=True) [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] rj)r+rnrms r3rnzDataFrame.rows\s€ðJ×$Ñ$×)Ñ)°Ð)Ó6Ð6r4)Ú buffer_sizecó—yr/rY©r2rkrrs r3Ú iter_rowszDataFrame.iter_rowsƒs€ð%(r4có—yr/rYrts r3ruzDataFrame.iter_rowsˆs€ð$'r4có—yr/rYrts r3ruzDataFrame.iter_rowss €ð@Cr4i©rkrrcó<—|jj||¬«S)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 Notes: cuDF doesn't support this method. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) We define a library agnostic function: >>> @nw.narwhalify ... def func(df, *, named): ... return df.iter_rows(named=named) We can then pass either pandas or Polars to `func`: >>> [row for row in func(df_pd, named=False)] [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> [row for row in func(df_pd, named=True)] [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> [row for row in func(df_pl, named=False)] [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> [row for row in func(df_pl, named=True)] [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] rx)r+rurts r3ruzDataFrame.iter_rows’s!€ðR×$Ñ$×.Ñ.°UÈ Ð.ÓTÐTr4có"•—t‰||i|€ŽS)u1 Add 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 polars as pl >>> import narwhals as nw >>> df = { ... "a": [1, 2, 3, 4], ... "b": [0.5, 4, 10, 13], ... "c": [True, True, False, True], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function in which we pass an expression to add it as a new column: >>> @nw.narwhalify ... def func(df): ... return df.with_columns((nw.col("a") * 2).alias("a*2")) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a b c a*2 0 1 0.5 True 2 1 2 4.0 True 4 2 3 10.0 False 6 3 4 13.0 True 8 >>> func(df_pl) shape: (4, 4) ┌─────┬──────┬───────┬─────┐ │ a ┆ b ┆ c ┆ a*2 │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ i64 │ ╞═════╪══════╪═══════╪═════╡ │ 1 ┆ 0.5 ┆ true ┆ 2 │ │ 2 ┆ 4.0 ┆ true ┆ 4 │ │ 3 ┆ 10.0 ┆ false ┆ 6 │ │ 4 ┆ 13.0 ┆ true ┆ 8 │ └─────┮──────┮───────┮─────┘ ©rZrg©r2rirjr:s €r3rgzDataFrame.with_columnsœsø€ô|‰wÑ# UÐ:škÑ:Ð:r4có"•—t‰||i|€ŽS)uÅSelect 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function in which we pass the name of a column to select that column. >>> @nw.narwhalify ... def func(df): ... return df.select("foo") We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo 0 1 1 2 2 3 >>> func(df_pl) shape: (3, 1) ┌─────┐ │ foo │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ Multiple columns can be selected by passing a list of column names. >>> @nw.narwhalify ... def func(df): ... return df.select(["foo", "bar"]) >>> func(df_pd) foo bar 0 1 6 1 2 7 2 3 8 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 6 │ │ 2 ┆ 7 │ │ 3 ┆ 8 │ └─────┮─────┘ Multiple columns can also be selected using positional arguments instead of a list. Expressions are also accepted. >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("foo"), nw.col("bar") + 1) >>> func(df_pd) foo bar 0 1 7 1 2 8 2 3 9 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ Use keyword arguments to easily name your expression inputs. >>> @nw.narwhalify ... def func(df): ... return df.select(threshold=nw.col("foo") * 2) >>> func(df_pd) threshold 0 2 1 4 2 6 >>> func(df_pl) shape: (3, 1) ┌───────────┐ │ threshold │ │ --- │ │ i64 │ ╞═══════════╡ │ 2 │ │ 4 │ │ 6 │ └───────────┘ ©rZrlr|s €r3rlzDataFrame.selectýsø€ôp‰w‰~˜uÐ4š Ñ4Ð4r4có"•—t‰||«S)u4Rename column names. Arguments: mapping: Key value pairs that map from old name to new name. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) We define a library agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.rename({"foo": "apple"}) We can then pass either pandas or Polars to `func`: >>> func(df_pd) apple bar ham 0 1 6 a 1 2 7 b 2 3 8 c >>> func(df_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ apple ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═══════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └───────┮─────┮─────┘ ©rZrn©r2ror:s €r3rnzDataFrame.renamewsø€ôN‰w‰~˜gÓ&Ð&r4có"•—t‰||«S)u¿Get 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)`. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = { ... "foo": [1, 2, 3, 4, 5], ... "bar": [6, 7, 8, 9, 10], ... "ham": ["a", "b", "c", "d", "e"], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function that gets the first 3 rows. >>> @nw.narwhalify ... def func(df): ... return df.head(3) We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo bar ham 0 1 6 a 1 2 7 b 2 3 8 c >>> func(df_pl) shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ ©rZrq©r2rsr:s €r3rqzDataFrame.head óø€ôX‰w‰|˜A‹Ðr4có"•—t‰||«S)uŸGet 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)`. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df = { ... "foo": [1, 2, 3, 4, 5], ... "bar": [6, 7, 8, 9, 10], ... "ham": ["a", "b", "c", "d", "e"], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function that gets the last 3 rows. >>> @nw.narwhalify ... def func(df): ... return df.tail(3) We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo bar ham 2 3 8 c 3 4 9 d 4 5 10 e >>> func(df_pl) shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 3 ┆ 8 ┆ c │ │ 4 ┆ 9 ┆ d │ │ 5 ┆ 10 ┆ e │ └─────┮─────┮─────┘ ©rZrvr„s €r3rvzDataFrame.tailÎr…r4rxcó4•—t‰|t|«d|iŽS)u“Remove columns from the dataframe. 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 polars as pl >>> import narwhals as nw >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.drop("ham") We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo bar 0 1 6.0 1 2 7.0 2 3 8.0 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ f64 │ ╞═════╪═════╡ │ 1 ┆ 6.0 │ │ 2 ┆ 7.0 │ │ 3 ┆ 8.0 │ └─────┮─────┘ Use positional arguments to drop multiple columns. >>> @nw.narwhalify ... def func(df): ... return df.drop("foo", "ham") >>> func(df_pd) bar 0 6.0 1 7.0 2 8.0 >>> func(df_pl) shape: (3, 1) ┌─────┐ │ bar │ │ --- │ │ f64 │ ╞═════╡ │ 6.0 │ │ 7.0 │ │ 8.0 │ └─────┘ ry©rZrzr©r2ryrer:s €r3rzzDataFrame.dropüsø€ô@‰w‰|œW WÓ-Ð=°fÑ=Ð=r4r{r|có(•—t‰||||¬«S)utDrop 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. Settings this to `True` blocks the possibility to run on the streaming engine for Polars. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = { ... "foo": [1, 2, 3, 1], ... "bar": ["a", "a", "a", "a"], ... "ham": ["b", "b", "b", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.unique(["bar", "ham"]) We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo bar ham 0 1 a b >>> func(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ a ┆ b │ └─────┮─────┮─────┘ r|©rZr€©r2rbr}r~r:s €r3r€zDataFrame.unique>sø€ôp‰w‰~˜fš4Àˆ~ÓOÐOr4có"•—t‰||i|€ŽS)u(Filter 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 &. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> >>> df = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function in which we filter on one condition. >>> def agnostic_filter(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.filter(nw.col("foo") > 1).to_native() We can then pass either pandas or Polars to `agnostic_filter`: >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ Filter on multiple conditions, combined with and/or operators: >>> def agnostic_filter(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.filter((nw.col("foo") < 3) & (nw.col("ham") == "a")).to_native() >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> def agnostic_filter(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... dframe = df.filter( ... (nw.col("foo") == 1) | (nw.col("ham") == "c") ... ).to_native() ... return dframe >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ Provide multiple filters using `*args` syntax: >>> def agnostic_filter(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... dframe = df.filter( ... nw.col("foo") <= 2, ... ~nw.col("ham").is_in(["b", "c"]), ... ).to_native() ... return dframe >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ Provide multiple filters using `**kwargs` syntax: >>> def agnostic_filter(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.filter(foo=2, ham="b").to_native() >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ └─────┮─────┮─────┘ ©rZr‹©r2rŒrr:s €r3r‹zDataFrame.filterxsø€ôF‰w‰~˜zÐ9š[Ñ9Ð9r4©Údrop_null_keyscó8—ddlm}||gt|«¢­d|iŽS)u× Start 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 polars as pl >>> import narwhals as nw >>> df = { ... "a": ["a", "b", "a", "b", "c"], ... "b": [1, 2, 1, 3, 3], ... "c": [5, 4, 3, 2, 1], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) Let's define a dataframe-agnostic function in which we group by one column and call `agg` to compute the grouped sum of another column. >>> @nw.narwhalify ... def func(df): ... return df.group_by("a").agg(nw.col("b").sum()).sort("a") We can then pass either pandas or Polars to `func`: >>> func(df_pd) a b 0 a 2 1 b 5 2 c 3 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ a ┆ 2 │ │ b ┆ 5 │ │ c ┆ 3 │ └─────┮─────┘ Group by multiple columns by passing a list of column names. >>> @nw.narwhalify ... def func(df): ... return df.group_by(["a", "b"]).agg(nw.max("c")).sort("a", "b") >>> func(df_pd) a b c 0 a 1 5 1 b 2 4 2 b 3 2 3 c 3 1 >>> func(df_pl) shape: (4, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 1 ┆ 5 │ │ b ┆ 2 ┆ 4 │ │ b ┆ 3 ┆ 2 │ │ c ┆ 3 ┆ 1 │ └─────┮─────┮─────┘ rrr’)Únarwhals.group_byrr)r2r’Úkeysrs r3Úgroup_byzDataFrame.group_byýs!€õV .átÐKœg d›mÒKžNÑKÐKr4rŽcó,•—t‰||g|¢­||dœŽS)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. 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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = { ... "a": [1, 2, None], ... "b": [6.0, 5.0, 4.0], ... "c": ["a", "c", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function in which we sort by multiple columns in different orders >>> @nw.narwhalify ... def func(df): ... return df.sort("c", "a", descending=[False, True]) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a b c 0 1.0 6.0 a 2 NaN 4.0 b 1 2.0 5.0 c >>> func(df_pl) shape: (3, 3) ┌──────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞══════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ null ┆ 4.0 ┆ b │ │ 2 ┆ 5.0 ┆ c │ └──────┮─────┮─────┘ rŽ©rZr’©r2r“rrr”r:s €r3r’zDataFrame.sortLs!ø€ôv‰w‰|˜BÐW ÑW°ZÈJÒWÐWr4r•r–có.•—t‰|||||||¬«S)uN Join 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. * *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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> data_other = { ... "apple": ["x", "y", "z"], ... "ham": ["a", "b", "d"], ... } >>> df_pd = pd.DataFrame(data) >>> other_pd = pd.DataFrame(data_other) >>> df_pl = pl.DataFrame(data) >>> other_pl = pl.DataFrame(data_other) Let's define a dataframe-agnostic function in which we join over "ham" column: >>> @nw.narwhalify ... def join_on_ham(df, other_any): ... return df.join(other_any, left_on="ham", right_on="ham") We can now pass either pandas or Polars to the function: >>> join_on_ham(df_pd, other_pd) foo bar ham apple 0 1 6.0 a x 1 2 7.0 b y >>> join_on_ham(df_pl, other_pl) shape: (2, 4) ┌─────┬─────┬─────┬───────┐ │ foo ┆ bar ┆ ham ┆ apple │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str ┆ str │ ╞═════╪═════╪═════╪═══════╡ │ 1 ┆ 6.0 ┆ a ┆ x │ │ 2 ┆ 7.0 ┆ b ┆ y │ └─────┮─────┮─────┮───────┘ ©r£r—r˜ršr™©rZrŠ©r2r§ršr£r—r˜r™r:s €r3rŠzDataFrame.join‰s)ø€ôT‰w‰|Ø s G°hÀ2Èfðó ð r4r°r±c ó2•—t‰ |||||||||¬«S)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. Returns: A new joined DataFrame Examples: >>> from datetime import datetime >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> 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_pd = pd.DataFrame(data_gdp) >>> population_pd = pd.DataFrame(data_population) >>> gdp_pl = pl.DataFrame(data_gdp).sort("datetime") >>> population_pl = pl.DataFrame(data_population).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" column: >>> @nw.narwhalify ... def join_asof_datetime(df, other_any, strategy): ... return df.join_asof(other_any, on="datetime", strategy=strategy) We can now pass either pandas or Polars to the function: >>> join_asof_datetime(population_pd, gdp_pd, strategy="backward") datetime population gdp 0 2016-03-01 82.19 4164 1 2018-08-01 82.66 4566 2 2019-01-01 83.12 4696 >>> join_asof_datetime(population_pl, gdp_pl, strategy="backward") 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 │ └─────────────────────┮────────────┮──────┘ Here is a real-world times-series example that uses `by` argument. >>> from datetime import datetime >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data_quotes = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 30), ... datetime(2016, 5, 25, 13, 30, 0, 41), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 49), ... datetime(2016, 5, 25, 13, 30, 0, 72), ... datetime(2016, 5, 25, 13, 30, 0, 75), ... ], ... "ticker": [ ... "GOOG", ... "MSFT", ... "MSFT", ... "MSFT", ... "GOOG", ... "AAPL", ... "GOOG", ... "MSFT", ... ], ... "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01], ... "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03], ... } >>> data_trades = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 38), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... ], ... "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"], ... "price": [51.95, 51.95, 720.77, 720.92, 98.0], ... "quantity": [75, 155, 100, 100, 100], ... } >>> quotes_pd = pd.DataFrame(data_quotes) >>> trades_pd = pd.DataFrame(data_trades) >>> quotes_pl = pl.DataFrame(data_quotes).sort("datetime") >>> trades_pl = pl.DataFrame(data_trades).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" and by "ticker" columns: >>> @nw.narwhalify ... def join_asof_datetime_by_ticker(df, other_any): ... return df.join_asof(other_any, on="datetime", by="ticker") We can now pass either pandas or Polars to the function: >>> join_asof_datetime_by_ticker(trades_pd, quotes_pd) datetime ticker price quantity bid ask 0 2016-05-25 13:30:00.000023 MSFT 51.95 75 51.95 51.96 1 2016-05-25 13:30:00.000038 MSFT 51.95 155 51.97 51.98 2 2016-05-25 13:30:00.000048 GOOG 720.77 100 720.50 720.93 3 2016-05-25 13:30:00.000048 GOOG 720.92 100 720.50 720.93 4 2016-05-25 13:30:00.000048 AAPL 98.00 100 NaN NaN >>> join_asof_datetime_by_ticker(trades_pl, quotes_pl) shape: (5, 6) ┌────────────────────────────┬────────┬────────┬──────────┬───────┬────────┐ │ datetime ┆ ticker ┆ price ┆ quantity ┆ bid ┆ ask │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ str ┆ f64 ┆ i64 ┆ f64 ┆ f64 │ ╞════════════════════════════╪════════╪════════╪══════════╪═══════╪════════╡ │ 2016-05-25 13:30:00.000023 ┆ MSFT ┆ 51.95 ┆ 75 ┆ 51.95 ┆ 51.96 │ │ 2016-05-25 13:30:00.000038 ┆ MSFT ┆ 51.95 ┆ 155 ┆ 51.97 ┆ 51.98 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.77 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.92 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ AAPL ┆ 98.0 ┆ 100 ┆ null ┆ null │ └────────────────────────────┮────────┮────────┮──────────┮───────┮────────┘ r±©rZrž© r2r§r—r˜ršr²r³r“rŽr:s €r3ržzDataFrame.join_asof×s5ø€ô\‰wÑ Ø ØØØØØØØð!ó  ð r4cól—|j|jj«|j¬«S)aîGet a mask of all duplicated rows in this DataFrame. Returns: A new Series. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> df_pd = pd.DataFrame( ... { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } ... ) >>> df_pl = pl.DataFrame( ... { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } ... ) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.is_duplicated() We can then pass either pandas or Polars to `func`: >>> func(df_pd) # doctest: +NORMALIZE_WHITESPACE 0 True 1 False 2 False 3 True dtype: bool >>> func(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ true false false true ] r8)rér+Ú is_duplicatedr-r1s r3r¢zDataFrame.is_duplicated‘ s4€ð`|‰|Ø × !Ñ !× /Ñ /Ó 1Ø—+‘+ðó ð r4có6—|jj«S)aÕCheck if the dataframe is empty. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl Let's define a dataframe-agnostic function that filters rows in which "foo" values are greater than 10, and then checks if the result is empty or not: >>> @nw.narwhalify ... def func(df): ... return df.filter(nw.col("foo") > 10).is_empty() We can then pass either pandas or Polars to `func`: >>> df_pd = pd.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]}) >>> df_pl = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]}) >>> func(df_pd), func(df_pl) (True, True) >>> df_pd = pd.DataFrame({"foo": [100, 2, 3], "bar": [4, 5, 6]}) >>> df_pl = pl.DataFrame({"foo": [100, 2, 3], "bar": [4, 5, 6]}) >>> func(df_pd), func(df_pl) (False, False) )r+Úis_emptyr1s r3r€zDataFrame.is_emptyÆ s€ð6×$Ñ$×-Ñ-Ó/Ð/r4cól—|j|jj«|j¬«S)aèGet a mask of all unique rows in this DataFrame. Returns: A new Series. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> df_pd = pd.DataFrame( ... { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } ... ) >>> df_pl = pl.DataFrame( ... { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } ... ) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.is_unique() We can then pass either pandas or Polars to `func`: >>> func(df_pd) # doctest: +NORMALIZE_WHITESPACE 0 False 1 True 2 True 3 False dtype: bool >>> func(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ false true true false ] r8)rér+Ú is_uniquer-r1s r3rŠzDataFrame.is_uniqueã s4€ð`|‰|Ø × !Ñ !× +Ñ +Ó -Ø—+‘+ðó ð r4cóT—|j|jj««S)u[Create a new DataFrame that shows the null counts per column. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> df_pd = pd.DataFrame( ... { ... "foo": [1, None, 3], ... "bar": [6, 7, None], ... "ham": ["a", "b", "c"], ... } ... ) >>> df_pl = pl.DataFrame( ... { ... "foo": [1, None, 3], ... "bar": [6, 7, None], ... "ham": ["a", "b", "c"], ... } ... ) Let's define a dataframe-agnostic function that returns the null count of each columns: >>> @nw.narwhalify ... def func(df): ... return df.null_count() We can then pass either pandas or Polars to `func`: >>> func(df_pd) foo bar ham 0 1 1 0 >>> func(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ u32 ┆ u32 ┆ u32 │ ╞═════╪═════╪═════╡ │ 1 ┆ 1 ┆ 0 │ └─────┮─────┮─────┘ )r<r+Ú null_countr1s r3ršzDataFrame.null_count s%€ðb×-Ñ-šd×.CÑ.C×.NÑ.NÓ.PÓQÐQr4có<—|jj||¬«S)aãReturn the DataFrame as a scalar, or return the element at the given row/column. 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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function that returns item at given row/column >>> @nw.narwhalify ... def func(df, row, column): ... return df.item(row, column) We can then pass either pandas or Polars to `func`: >>> func(df_pd, 1, 1), func(df_pd, 2, "b") (np.int64(5), np.int64(6)) >>> func(df_pl, 1, 1), func(df_pl, 2, "b") (5, 6) )rWÚcolumn)r+r0)r2rWrªs r3r0zDataFrame.itemK s €ð:×$Ñ$×)Ñ)šcž&Ð)ÓAÐAr4có •—t‰|«S)u»Create a copy of this DataFrame. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function in which we clone the DataFrame: >>> @nw.narwhalify ... def func(df): ... return df.clone() >>> func(df_pd) a b 0 1 3 1 2 4 >>> func(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┮─────┘ ©rZr«res €r3r«zDataFrame.clonej sø€ôB‰w‰}‹Ðr4có&•—t‰|||¬«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. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function in which gather every 2 rows, starting from a offset of 1: >>> @nw.narwhalify ... def func(df): ... return df.gather_every(n=2, offset=1) >>> func(df_pd) a b 1 2 6 3 4 8 >>> func(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 2 ┆ 6 │ │ 4 ┆ 8 │ └─────┮─────┘ r­©rZr¯©r2rsr®r:s €r3r¯zDataFrame.gather_every sø€ôL‰wÑ# a°Ð#Ó7Ð7r4Ú_)rŒÚvaluesÚaggregate_functionr~Ú sort_columnsÚ separatorc ód—|j|jj|||||||¬««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: Sort the grouped keys so that the output order is predictable. 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. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> 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_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.pivot("col", index="ix", aggregate_function="sum") We can then pass either pandas or Polars to `func`: >>> func(df_pd) ix foo_a foo_b bar_a bar_b 0 1 1 7 2 9 1 2 4 1 0 4 >>> func(df_pl) shape: (2, 5) ┌─────┬───────┬───────┬───────┬───────┐ │ ix ┆ foo_a ┆ foo_b ┆ bar_a ┆ bar_b │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │ ╞═════╪═══════╪═══════╪═══════╪═══════╡ │ 1 ┆ 1 ┆ 7 ┆ 2 ┆ 9 │ │ 2 ┆ 4 ┆ 1 ┆ 0 ┆ 4 │ └─────┮───────┮───────┮───────┮───────┘ )ršrŒr±r²r~r³rŽ)r<r+Úpivot)r2ršrŒr±r²r~r³rŽs r3r¶zDataFrame.pivotµ sF€ðP×-Ñ-Ø × !Ñ !× 'Ñ 'ØØØØ#5Ø-Ø)Ø#ð (ó ó  ð r4có6—|jj«S)aƒConvert to arrow table. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2, 3], "bar": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function that converts to arrow table: >>> @nw.narwhalify ... def func(df): ... return df.to_arrow() >>> func(df_pd) pyarrow.Table foo: int64 bar: string ---- foo: [[1,2,3]] bar: [["a","b","c"]] >>> func(df_pl) # doctest:+NORMALIZE_WHITESPACE pyarrow.Table foo: int64 bar: large_string ---- foo: [[1,2,3]] bar: [["a","b","c"]] )r+rr1s r3rzDataFrame.to_arrow s€ðB×$Ñ$×-Ñ-Ó/Ð/r4)ÚfractionÚwith_replacementÚseedcó^—|j|jj||||¬««S)upSample 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. Notes: The results may not be consistent across libraries. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = {"a": [1, 2, 3, 4], "b": ["x", "y", "x", "y"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.sample(n=2, seed=123) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a b 3 4 y 0 1 x >>> func(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ str │ ╞═════╪═════╡ │ 2 ┆ y │ │ 3 ┆ x │ └─────┮─────┘ As you can see, by using the same seed, the result will be consistent within the same backend, but not necessarely across different backends. )rsržr¹rº)r<r+Úsample)r2rsržr¹rºs r3rŒzDataFrame.sample, s<€ðj×-Ñ-Ø × !Ñ !× (Ñ (ؘhÐ9IÐPTð )ó ó ð r4©rŒrœrŸcó*•—t‰|||||¬«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". 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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": ["x", "y", "z"], ... "b": [1, 3, 5], ... "c": [2, 4, 6], ... } We define a library agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.unpivot(on=["b", "c"], index="a") We can pass any supported library such as pandas, Polars or PyArrow to `func`: >>> func(pl.DataFrame(data)) shape: (6, 3) ┌─────┬──────────┬───────┐ │ a ┆ variable ┆ value │ │ --- ┆ --- ┆ --- │ │ str ┆ str ┆ i64 │ ╞═════╪══════════╪═══════╡ │ x ┆ b ┆ 1 │ │ y ┆ b ┆ 3 │ │ z ┆ b ┆ 5 │ │ x ┆ c ┆ 2 │ │ y ┆ c ┆ 4 │ │ z ┆ c ┆ 6 │ └─────┮──────────┮───────┘ >>> func(pd.DataFrame(data)) 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 >>> func(pa.table(data)) pyarrow.Table a: string variable: string value: int64 ---- a: [["x","y","z"],["x","y","z"]] variable: [["b","b","b"],["c","c","c"]] value: [[1,3,5],[2,4,6]] r»©rZr¿©r2ršrŒrœrŸr:s €r3r¿zDataFrame.unpivotg s%ø€ôd‰w‰Ø˜šmÈ ðó ð r4)rÇztype[Series[Any]])rÇztype[LazyFrame[Any]]©r;rr9r,rÇÚNone©rÇr%rÈ)NN)rýrrûz bool | NonerÇú np.ndarray©rÇrMr/)rz object | NonerÇrà)rÇzLazyFrame[Any])rÇr()rÇz pd.DataFrame)r"zstr | Path | BytesIO | NonerÇr)r"zstr | Path | BytesIOrÇrÂ)rÇrÄ)rÇztuple[int, int])r_rMrÇú Series[Any])Úb)r,r$rÇz int | float)r0ztuple[Sequence[int], slice]rÇr)r0z#tuple[Sequence[int], Sequence[int]]rÇr)r0ztuple[slice, Sequence[int]]rÇr)r0ztuple[Sequence[int], str]rÇrÆ)r0ztuple[slice, str]rÇrÆ)r0z#tuple[Sequence[int], Sequence[str]]rÇr)r0ztuple[slice, Sequence[str]]rÇr)r0ztuple[Sequence[int], int]rÇrÆ)r0ztuple[slice, int]rÇrÆ)r0z Sequence[int]rÇr)r0rMrÇrÆ)r0z Sequence[str]rÇr)r0rGrÇr)r0ztuple[slice, slice]rÇr)r0zÃstr | slice | Sequence[int] | Sequence[str] | tuple[Sequence[int], str | int] | tuple[slice, str | int] | tuple[slice | Sequence[int], Sequence[int] | Sequence[str] | slice] | tuple[slice, slice]rÇzSeries[Any] | Self)rKrMrÇr„)rNú Literal[True]rÇzdict[str, Series[Any]])rNúLiteral[False]rÇzdict[str, list[Any]])rNr„rÇz-dict[str, Series[Any]] | dict[str, list[Any]])rŒrÓrÇztuple[Any, ...]rÊrÍrËrÌrÉ©r2rrÇrrÏ)rkrÉrÇzlist[tuple[Any, ...]])rkrÈrÇzlist[dict[str, Any]])rkr„rÇz,list[tuple[Any, ...]] | list[dict[str, Any]])rkrÉrrrÓrÇzIterator[tuple[Any, ...]])rkrÈrrrÓrÇzIterator[dict[str, Any]])rkr„rrrÓrÇz4Iterator[tuple[Any, ...]] | Iterator[dict[str, Any]]rÐrÑ©érÒ©rer×ryr„rÇrrÔrÕ)r•r×r’r„rÇz GroupBy[Self]rÖrØrÙrÝ)r2rrÇrÆ)r2rrÇr„)r2rrÇr)r2rrWú int | Nonerªzint | str | NonerÇrrÚrÛrÜ)r2rršzstr | list[str]rŒrÎr±rÎr²zMLiteral['min', 'max', 'first', 'last', 'sum', 'mean', 'median', 'len'] | Noner~r„r³r„rŽrMrÇr)r2rrÇzpa.Table) r2rrsrÎržz float | Noner¹r„rºrÎrÇrrß);rárârãÚ__doc__rårérìrór÷rùrür rrrrr r$r&r(r*r-rr1rLrQrWr[rcr]rSrVrernrurgrlrnrqrvrzr€r‹r–r’rŠržr¢r€rŠršr0r«r¯r¶rrŒr¿Ú __classcell__©r:s@r3rçrçSs-ø„ñðòóðð òóðð &à ð &ð6ð &ð ó &ðò5óð5ó4/ôAó  ôNó./Kób,3ó\.1ô`(5óT"2óH*0ðXò#+óð#+óJ3 ôj*?ðXÚIóØIØ ÚQóØQØ ÚIóØIØ ÚNóØNØ ÚFóØFØ ÚQóØQØ ÚIóØIØ ÚNóØNØ ÚFóØFà Ú;óØ;à Ú8óØ8à Ú;óØ;à Ú3óØ3à ÚAóØAðB!ð "ðB!ð óB!óH#ðØ47ÔWóØWØ ÚPóØPØ ð<Ø ð<à 6ò<óð<ð$(ñ9BØ ð9Bà 6ó9Bóv%0õP*7öX*1öX(,ðTô"óð"õH"(ðHôóðð@ð!&ñ$ðð$ð ò $óð$ð ð#ðð#ð ò #óð#ð ð;ðð;ð 6ò ;óð;ðñ%7ðð%7ð 6ó %7ðNà;>ñ(Ø&ð(Ø58ð(à "ò(óð(ðà:=ñ'Ø%ð'Ø47ð'à !ò'óð'ðà14ñCØðCØ+.ðCà =òCóðCð %žñ)UØð)UØ36ð)Uà =ó)UðV>;Ø3ð>;ØDLð>;à õ>;ð@x5à-ðx5ð ðx5ð õ x5õt''öR,ö\,ð\BF÷@>ðH*.ð8Pð9>Ø$ñ 8Pà&ð8Pð6ð 8Pð ð 8Pð õ 8PðtC:ØEðC:ØVYðC:à õC:ðLBGñMLØ(ðMLØ:>ðMLà óMLðf-2Ø ñ ;Xà ð;Xðð;Xð*ð ;Xð ð ;Xð õ ;Xð@&*ØAHð L ð +/Ø+/ØñL àðL ð #ðL ð?ð L ð (ð L ð)ðL ððL ð õL ðd#Ø#ØØ*.Ø+/Ø%)Ø>Hñw àðw ðð w ð ð w ð ð w ð(ðw ð)ðw ð #ðw ð<ðw ð õw ót3 ój0ó:3 ój1RôfBõ>!öF&8ðX)-Ø)-ðØ#Ø"ØñR ØðR à ðR ð&ð R ð 'ð R ð ð R ððR ððR ððR ð óR óh!0ðJð9 ð"&Ø!&Øñ 9 Øð9 à ð9 ðð 9 ð ð 9 ð ð 9 ð ó9 ðz&*ðT ð)-Ø$(Ø!%ñ T ØðT à "ðT ð&ð T ð "ð T ð ð T ð ÷T ñT r4rçcó~‡—eZdZdZed,d„«Z d-d„Zd.d„Zed/d„«Zd0d„Z d1d„Z d2d„Z d3ˆfd „ Z d4d5ˆfd „ Z d6d7ˆfd „ Zed8ˆfd „ «Zd9ˆfd„ Zed:ˆfd„ «Z d;ˆfd„ Z d;ˆfd„ Zd<ˆfd„ Zd=d>ˆfd„ Zd=d>ˆfd„ Zddœd?ˆfd„Z d4dddœ d@ˆfd„Z dAˆfd„ Zddœ dBd„Zdddœ dCˆfd „Z dDd d d!d"œ dEˆfd#„Zd d d d d d d$d%œ dFˆfd&„ZdGˆfd'„ ZdGd(„ZdHdIˆfd)„ Z d4d d d d*œ dJˆfd+„Z!ˆxZ"S)KrëzåNarwhals DataFrame, backed by a native dataframe. The native dataframe might be pandas.DataFrame, polars.LazyFrame, ... This class is not meant to be instantiated directly - instead, use `narwhals.from_native`. có—tSr/)rçr1s r3Ú _dataframezLazyFrame._dataframeÇ rír4có†—||_t|d«r|j«|_ydt |«›}t |«‚)NÚ__narwhals_lazyframe__zVExpected Polars LazyFrame or an object that implements `__narwhals_lazyframe__`, got: )r-rðrÖr+rNrñròs r3rózLazyFrame.__init__Ë sF€ð ˆŒ Ü 2Ð/Ô 0Ø)+×)BÑ)BÓ)DˆDÕ !àjÔkoÐprÓksÐjtÐuˆCÜ  Ó%Ð %r4có^—d}t|«}dd|zzdzd|›dzdzdzd|zzd zS) Nz' Narwhals LazyFrame rÿrrrrrrrrrs r3r zLazyFrame.__repr__Ø r r4có.—|jjS)a¯Return implementation of native frame. This can be useful when you need to some special-casing for some libraries for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import polars as pl >>> lf_native = pl.LazyFrame({"a": [1, 2, 3]}) >>> lf = nw.from_native(lf_native) >>> lf.implementation >>> lf.implementation.is_pandas() False >>> lf.implementation.is_polars() True rõr1s r3r÷zLazyFrame.implementationæ s€ð.×$Ñ$×4Ñ4Ð4r4có—d}t|«‚)Nz%Slicing is not supported on LazyFrame)rOrIs r3r1zLazyFrame.__getitem__ÿ s€Ø5ˆÜ˜‹nÐr4cóX—|j|jj«d¬«S)uÀMaterialize this LazyFrame into a DataFrame. Returns: DataFrame Examples: >>> import narwhals as nw >>> import polars as pl >>> lf_pl = pl.LazyFrame( ... { ... "a": ["a", "b", "a", "b", "b", "c"], ... "b": [1, 2, 3, 4, 5, 6], ... "c": [6, 5, 4, 3, 2, 1], ... } ... ) >>> lf = nw.from_native(lf_pl) >>> lf ┌───────────────────────────────────────┐ | Narwhals LazyFrame | | Use `.to_native` to see native output | └───────────────────────────────────────┘ >>> df = lf.group_by("a").agg(nw.all().sum()).collect() >>> df.to_native().sort("a") shape: (3, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 4 ┆ 10 │ │ b ┆ 11 ┆ 10 │ │ c ┆ 6 ┆ 1 │ └─────┮─────┮─────┘ Úfullr8)rÔr+Úcollectr1s r3rÜzLazyFrame.collect s0€ðF‰Ø × !Ñ !× )Ñ )Ó +Øðó ð r4có—t|d¬«S)uConvert Narwhals LazyFrame to native one. Returns: Object of class that user started with. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) >>> df_pa = pa.table(data) Calling `to_native` on a Narwhals DataFrame returns the native object: >>> nw.from_native(df_pd).lazy().to_native() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> nw.from_native(lf_pl).to_native().collect() shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ 2 ┆ 7.0 ┆ b │ │ 3 ┆ 8.0 ┆ c │ └─────┮─────┮─────┘ F)Únarwhals_objectÚ pass_throughrr1s r3rzLazyFrame.to_native+ s€ôHšžEÔBÐBr4có*•—t‰||g|¢­i|€ŽS)uTPipe function call. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "ba": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_pipe(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.pipe(lambda _df: _df.select("a")).to_native() We can then pass either pandas or Polars: >>> agnostic_pipe(df_pd) a 0 1 1 2 2 3 >>> agnostic_pipe(lf_pl).collect() shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ rYr[s €r3r[zLazyFrame.pipeR sø€ôL‰w‰|˜HÐ6 tÒ6švÑ6Ð6r4Ncó$•—t‰||¬«S)u€Drop null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1.0, 2.0, None], "ba": [1.0, None, 2.0]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_drop_nulls(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop_nulls().to_native() We can then pass either pandas or Polars: >>> agnostic_drop_nulls(df_pd) a ba 0 1.0 1.0 >>> agnostic_drop_nulls(lf_pl).collect() shape: (1, 2) ┌─────┬─────┐ │ a ┆ ba │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞═════╪═════╡ │ 1.0 ┆ 1.0 │ └─────┮─────┘ rar]r^s €r3rczLazyFrame.drop_nullsz r_r4có"•—t‰||«S)uƒInsert column which enumerates rows. Examples: >>> import polars as pl >>> import pandas as pd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function: >>> def agnostic_with_row_index(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_row_index().to_native() We can then pass either pandas or Polars: >>> agnostic_with_row_index(df_pd) index a b 0 0 1 4 1 1 2 5 2 2 3 6 >>> agnostic_with_row_index(lf_pl).collect() shape: (3, 3) ┌───────┬─────┬─────┐ │ index ┆ a ┆ b │ │ --- ┆ --- ┆ --- │ │ u32 ┆ i64 ┆ i64 │ ╞═══════╪═════╪═════╡ │ 0 ┆ 1 ┆ 4 │ │ 1 ┆ 2 ┆ 5 │ │ 2 ┆ 3 ┆ 6 │ └───────┮─────┮─────┘ rarbs €r3r]zLazyFrame.with_row_indexŠ sø€ôL‰wÑ% dÓ+Ð+r4có•—t‰|S)a'Get an ordered mapping of column names to their data type. Examples: >>> import polars as pl >>> import narwhals as nw >>> lf_pl = pl.LazyFrame( ... { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } ... ) >>> lf = nw.from_native(lf_pl) >>> lf.schema # doctest: +SKIP Schema({'foo': Int64, 'bar': Float64, 'ham', String}) rdres €r3rSzLazyFrame.schemaÎ sø€ô$‰w‰~Ðr4có •—t‰|«S)aGet an ordered mapping of column names to their data type. Examples: >>> import polars as pl >>> import narwhals as nw >>> lf_pl = pl.LazyFrame( ... { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } ... ) >>> lf = nw.from_native(lf_pl) >>> lf.collect_schema() Schema({'foo': Int64, 'bar': Float64, 'ham': String}) rgres €r3rVzLazyFrame.collect_schemaâ sø€ô"‰wÑ%Ó'Ð'r4có•—t‰|S)aVGet column names. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) We define a library agnostic function: >>> def agnostic_columns(df_native: IntoFrame) -> list[str]: ... df = nw.from_native(df_native) ... return df.columns We can then pass either pandas or Polars to `agnostic_columns`: >>> agnostic_columns(df_pd) ['foo', 'bar', 'ham'] >>> agnostic_columns(lf_pl) # doctest: +SKIP ['foo', 'bar', 'ham'] rires €r3rezLazyFrame.columnsõ sø€ô6‰w‰Ðr4có"•—t‰||i|€ŽS)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 pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> df = { ... "a": [1, 2, 3, 4], ... "b": [0.5, 4, 10, 13], ... "c": [True, True, False, True], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) Let's define a dataframe-agnostic function in which we pass an expression to add it as a new column: >>> def agnostic_with_columns(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns((nw.col("a") * 2).alias("2a")).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_with_columns(df_pd) a b c 2a 0 1 0.5 True 2 1 2 4.0 True 4 2 3 10.0 False 6 3 4 13.0 True 8 >>> agnostic_with_columns(df_pl) shape: (4, 4) ┌─────┬──────┬───────┬─────┐ │ a ┆ b ┆ c ┆ 2a │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ i64 │ ╞═════╪══════╪═══════╪═════╡ │ 1 ┆ 0.5 ┆ true ┆ 2 │ │ 2 ┆ 4.0 ┆ true ┆ 4 │ │ 3 ┆ 10.0 ┆ false ┆ 6 │ │ 4 ┆ 13.0 ┆ true ┆ 8 │ └─────┮──────┮───────┮─────┘ >>> agnostic_with_columns(lf_pl).collect() shape: (4, 4) ┌─────┬──────┬───────┬─────┐ │ a ┆ b ┆ c ┆ 2a │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ i64 │ ╞═════╪══════╪═══════╪═════╡ │ 1 ┆ 0.5 ┆ true ┆ 2 │ │ 2 ┆ 4.0 ┆ true ┆ 4 │ │ 3 ┆ 10.0 ┆ false ┆ 6 │ │ 4 ┆ 13.0 ┆ true ┆ 8 │ └─────┮──────┮───────┮─────┘ r{r|s €r3rgzLazyFrame.with_columns sø€ôZ‰wÑ# UÐ:škÑ:Ð:r4có"•—t‰||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. 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 pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> df = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) Let's define a dataframe-agnostic function in which we pass the name of a column to select that column. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("foo").to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_select(df_pd) foo 0 1 1 2 2 3 >>> agnostic_select(df_pl) shape: (3, 1) ┌─────┐ │ foo │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ >>> agnostic_select(lf_pl).collect() shape: (3, 1) ┌─────┐ │ foo │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ Multiple columns can be selected by passing a list of column names. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(["foo", "bar"]).to_native() >>> >>> agnostic_select(df_pd) foo bar 0 1 6 1 2 7 2 3 8 >>> agnostic_select(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 6 │ │ 2 ┆ 7 │ │ 3 ┆ 8 │ └─────┮─────┘ >>> agnostic_select(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 6 │ │ 2 ┆ 7 │ │ 3 ┆ 8 │ └─────┮─────┘ Multiple columns can also be selected using positional arguments instead of a list. Expressions are also accepted. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo"), nw.col("bar") + 1).to_native() >>> >>> agnostic_select(df_pd) foo bar 0 1 7 1 2 8 2 3 9 >>> agnostic_select(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ >>> agnostic_select(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ Use keyword arguments to easily name your expression inputs. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(threshold=nw.col("foo") * 2).to_native() >>> >>> agnostic_select(df_pd) threshold 0 2 1 4 2 6 >>> agnostic_select(df_pl) shape: (3, 1) ┌───────────┐ │ threshold │ │ --- │ │ i64 │ ╞═══════════╡ │ 2 │ │ 4 │ │ 6 │ └───────────┘ >>> agnostic_select(lf_pl).collect() shape: (3, 1) ┌───────────┐ │ threshold │ │ --- │ │ i64 │ ╞═══════════╡ │ 2 │ │ 4 │ │ 6 │ └───────────┘ r~r|s €r3rlzLazyFrame.selecta sø€ô\‰w‰~˜uÐ4š Ñ4Ð4r4có"•—t‰||«S)ubRename 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) We define a library agnostic function: >>> def agnostic_rename(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.rename({"foo": "apple"}).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_rename(df_pd) apple bar ham 0 1 6 a 1 2 7 b 2 3 8 c >>> agnostic_rename(lf_pl).collect() shape: (3, 3) ┌───────┬─────┬─────┐ │ apple ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═══════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └───────┮─────┮─────┘ r€rs €r3rnzLazyFrame.renamesø€ôV‰w‰~˜gÓ&Ð&r4có"•—t‰||«S)u'Get the first `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3, 4, 5, 6], ... "b": [7, 8, 9, 10, 11, 12], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function that gets the first 3 rows. >>> def agnostic_head(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.head(3).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_head(df_pd) a b 0 1 7 1 2 8 2 3 9 >>> agnostic_head(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ >>> agnostic_head(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ rƒr„s €r3rqzLazyFrame.head>óø€ôp‰w‰|˜A‹Ðr4có"•—t‰||«S)u)Get the last `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3, 4, 5, 6], ... "b": [7, 8, 9, 10, 11, 12], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function that gets the last 3 rows. >>> def agnostic_tail(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.tail(3).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_tail(df_pd) a b 3 4 10 4 5 11 5 6 12 >>> agnostic_tail(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 4 ┆ 10 │ │ 5 ┆ 11 │ │ 6 ┆ 12 │ └─────┮─────┘ >>> agnostic_tail(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 4 ┆ 10 │ │ 5 ┆ 11 │ │ 6 ┆ 12 │ └─────┮─────┘ r‡r„s €r3rvzLazyFrame.tailxrêr4Trxcó4•—t‰|t|«d|iŽS)uF Remove 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. Warning: `strict` argument is ignored for `polars<1.0.0`. Please consider upgrading to a newer version or pass to eager mode. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) We define a library agnostic function: >>> def agnostic_drop(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop("ham").to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_drop(df_pd) foo bar 0 1 6.0 1 2 7.0 2 3 8.0 >>> agnostic_drop(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ f64 │ ╞═════╪═════╡ │ 1 ┆ 6.0 │ │ 2 ┆ 7.0 │ │ 3 ┆ 8.0 │ └─────┮─────┘ Use positional arguments to drop multiple columns. >>> def agnostic_drop(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop("foo", "ham").to_native() >>> agnostic_drop(df_pd) bar 0 6.0 1 7.0 2 8.0 >>> agnostic_drop(lf_pl).collect() shape: (3, 1) ┌─────┐ │ bar │ │ --- │ │ f64 │ ╞═════╡ │ 6.0 │ │ 7.0 │ │ 8.0 │ └─────┘ ryr‰rŠs €r3rzzLazyFrame.drop²sø€ôN‰w‰|œW WÓ-Ð=°fÑ=Ð=r4r{Fr|có(•—t‰||||¬«S)u€Drop duplicate rows from this LazyFrame. Arguments: subset: Column name(s) to consider when identifying duplicate rows. If set to `None`, use all columns. 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. Settings this to `True` blocks the possibility to run on the streaming engine for Polars. Returns: LazyFrame: LazyFrame with unique rows. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3, 1], ... "bar": ["a", "a", "a", "a"], ... "ham": ["b", "b", "b", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) We define a library agnostic function: >>> def agnostic_unique(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.unique(["bar", "ham"]).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_unique(df_pd) foo bar ham 0 1 a b >>> agnostic_unique(lf_pl).collect() shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ a ┆ b │ └─────┮─────┮─────┘ r|rŒrs €r3r€zLazyFrame.uniqueûsø€ô|‰w‰~˜fš4Àˆ~ÓOÐOr4có"•—t‰||i|€ŽS)uKFilter 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 &. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function in which we filter on one condition. >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(nw.col("foo") > 1).to_native() We can then pass either pandas or Polars to `agnostic_filter`: >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_pl).collect() shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ Filter on multiple conditions: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter((nw.col("foo") < 3) & (nw.col("ham") == "a")).to_native() >>> >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_pl).collect() shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ Provide multiple filters using `*args` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter( ... nw.col("foo") == 1, ... nw.col("ham") == "a", ... ).to_native() >>> >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_pl).collect() shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ Filter on an OR condition: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter( ... (nw.col("foo") == 1) | (nw.col("ham") == "c") ... ).to_native() >>> >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_pl).collect() shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ Provide multiple filters using `**kwargs` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(foo=2, ham="b").to_native() >>> >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_pl).collect() shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ └─────┮─────┮─────┘ rrs €r3r‹zLazyFrame.filter;sø€ôn‰w‰~˜zÐ9š[Ñ9Ð9r4r‘có8—ddlm}||gt|«¢­d|iŽS)užStart 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. Examples: Group by one column and call `agg` to compute the grouped sum of another column. >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> df = { ... "a": ["a", "b", "a", "b", "c"], ... "b": [1, 2, 1, 3, 3], ... "c": [5, 4, 3, 2, 1], ... } >>> df_pd = pd.DataFrame(df) >>> df_pl = pl.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) Let's define a dataframe-agnostic function in which we group by one column and call `agg` to compute the grouped sum of another column. >>> def agnostic_group_by_agg(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.group_by("a").agg(nw.col("b").sum()).sort("a").to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_group_by_agg(df_pd) a b 0 a 2 1 b 5 2 c 3 >>> agnostic_group_by_agg(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ a ┆ 2 │ │ b ┆ 5 │ │ c ┆ 3 │ └─────┮─────┘ >>> agnostic_group_by_agg(lf_pl).collect() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ a ┆ 2 │ │ b ┆ 5 │ │ c ┆ 3 │ └─────┮─────┘ Group by multiple columns by passing a list of column names. >>> def agnostic_group_by_agg(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.group_by(["a", "b"]).agg(nw.max("c")).sort(["a", "b"]).to_native() ... ) >>> >>> agnostic_group_by_agg(df_pd) a b c 0 a 1 5 1 b 2 4 2 b 3 2 3 c 3 1 >>> agnostic_group_by_agg(df_pl) shape: (4, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 1 ┆ 5 │ │ b ┆ 2 ┆ 4 │ │ b ┆ 3 ┆ 2 │ │ c ┆ 3 ┆ 1 │ └─────┮─────┮─────┘ >>> agnostic_group_by_agg(lf_pl).collect() shape: (4, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 1 ┆ 5 │ │ b ┆ 2 ┆ 4 │ │ b ┆ 3 ┆ 2 │ │ c ┆ 3 ┆ 1 │ └─────┮─────┮─────┘ rrr’)r”rr)r2r’r•rs r3r–zLazyFrame.group_byôs!€õT 2á˜4ÐO€'š$£-ÒOÀÑOÐOr4rŽcó,•—t‰||g|¢­||dœŽS)uÿSort 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. 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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, None], ... "b": [6.0, 5.0, 4.0], ... "c": ["a", "c", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function in which we sort by multiple columns in different orders >>> def agnostic_sort(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.sort("c", "a", descending=[False, True]).to_native() We can then pass either pandas or Polars to `func`: >>> agnostic_sort(df_pd) a b c 0 1.0 6.0 a 2 NaN 4.0 b 1 2.0 5.0 c >>> agnostic_sort(lf_pl).collect() shape: (3, 3) ┌──────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞══════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ null ┆ 4.0 ┆ b │ │ 2 ┆ 5.0 ┆ c │ └──────┮─────┮─────┘ rŽr˜r™s €r3r’zLazyFrame.sortbs!ø€ô|‰w‰|˜BÐW ÑW°ZÈJÒWÐWr4r•r–có.•—t‰|||||||¬«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. * *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 narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> data_other = { ... "apple": ["x", "y", "z"], ... "ham": ["a", "b", "d"], ... } >>> df_pd = pd.DataFrame(data) >>> other_pd = pd.DataFrame(data_other) >>> lf_pl = pl.LazyFrame(data) >>> other_pl = pl.LazyFrame(data_other) Let's define a dataframe-agnostic function in which we join over "ham" column: >>> def agnostic_join_on_ham( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join(other, left_on="ham", right_on="ham").to_native() We can now pass either pandas or Polars to the function: >>> agnostic_join_on_ham(df_pd, other_pd) foo bar ham apple 0 1 6.0 a x 1 2 7.0 b y >>> agnostic_join_on_ham(lf_pl, other_pl).collect() shape: (2, 4) ┌─────┬─────┬─────┬───────┐ │ foo ┆ bar ┆ ham ┆ apple │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str ┆ str │ ╞═════╪═════╪═════╪═══════╡ │ 1 ┆ 6.0 ┆ a ┆ x │ │ 2 ┆ 7.0 ┆ b ┆ y │ └─────┮─────┮─────┮───────┘ r›rœrs €r3rŠzLazyFrame.join¢s)ø€ô`‰w‰|Ø s G°hÀ2Èfðó ð r4r°r±c ó2•—t‰ |||||||||¬«S)ue$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. Returns: A new joined DataFrame Examples: >>> from datetime import datetime >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from typing import Literal >>> from narwhals.typing import IntoFrameT >>> >>> 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_pd = pd.DataFrame(data_gdp) >>> population_pd = pd.DataFrame(data_population) >>> gdp_pl = pl.LazyFrame(data_gdp).sort("datetime") >>> population_pl = pl.LazyFrame(data_population).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" column: >>> def agnostic_join_asof_datetime( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... strategy: Literal["backward", "forward", "nearest"], ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join_asof(other, on="datetime", strategy=strategy).to_native() We can now pass either pandas or Polars to the function: >>> agnostic_join_asof_datetime(population_pd, gdp_pd, strategy="backward") datetime population gdp 0 2016-03-01 82.19 4164 1 2018-08-01 82.66 4566 2 2019-01-01 83.12 4696 >>> agnostic_join_asof_datetime( ... population_pl, gdp_pl, strategy="backward" ... ).collect() 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 │ └─────────────────────┮────────────┮──────┘ Here is a real-world times-series example that uses `by` argument. >>> from datetime import datetime >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data_quotes = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 30), ... datetime(2016, 5, 25, 13, 30, 0, 41), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 49), ... datetime(2016, 5, 25, 13, 30, 0, 72), ... datetime(2016, 5, 25, 13, 30, 0, 75), ... ], ... "ticker": [ ... "GOOG", ... "MSFT", ... "MSFT", ... "MSFT", ... "GOOG", ... "AAPL", ... "GOOG", ... "MSFT", ... ], ... "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01], ... "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03], ... } >>> data_trades = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 38), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... ], ... "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"], ... "price": [51.95, 51.95, 720.77, 720.92, 98.0], ... "quantity": [75, 155, 100, 100, 100], ... } >>> quotes_pd = pd.DataFrame(data_quotes) >>> trades_pd = pd.DataFrame(data_trades) >>> quotes_pl = pl.LazyFrame(data_quotes).sort("datetime") >>> trades_pl = pl.LazyFrame(data_trades).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" and by "ticker" columns: >>> def agnostic_join_asof_datetime_by_ticker( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join_asof(other, on="datetime", by="ticker").to_native() We can now pass either pandas or Polars to the function: >>> agnostic_join_asof_datetime_by_ticker(trades_pd, quotes_pd) datetime ticker price quantity bid ask 0 2016-05-25 13:30:00.000023 MSFT 51.95 75 51.95 51.96 1 2016-05-25 13:30:00.000038 MSFT 51.95 155 51.97 51.98 2 2016-05-25 13:30:00.000048 GOOG 720.77 100 720.50 720.93 3 2016-05-25 13:30:00.000048 GOOG 720.92 100 720.50 720.93 4 2016-05-25 13:30:00.000048 AAPL 98.00 100 NaN NaN >>> agnostic_join_asof_datetime_by_ticker(trades_pl, quotes_pl).collect() shape: (5, 6) ┌────────────────────────────┬────────┬────────┬──────────┬───────┬────────┐ │ datetime ┆ ticker ┆ price ┆ quantity ┆ bid ┆ ask │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ str ┆ f64 ┆ i64 ┆ f64 ┆ f64 │ ╞════════════════════════════╪════════╪════════╪══════════╪═══════╪════════╡ │ 2016-05-25 13:30:00.000023 ┆ MSFT ┆ 51.95 ┆ 75 ┆ 51.95 ┆ 51.96 │ │ 2016-05-25 13:30:00.000038 ┆ MSFT ┆ 51.95 ┆ 155 ┆ 51.97 ┆ 51.98 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.77 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.92 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ AAPL ┆ 98.0 ┆ 100 ┆ null ┆ null │ └────────────────────────────┮────────┮────────┮──────────┮───────┮────────┘ r±rŸr s €r3ržzLazyFrame.join_asofös5ø€ôz‰wÑ Ø ØØØØØØØð!ó  ð r4có •—t‰|«S)ujCreate a copy of this DataFrame. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function in which we copy the DataFrame: >>> def agnostic_clone(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.clone().to_native() >>> agnostic_clone(df_pd) a b 0 1 3 1 2 4 >>> agnostic_clone(lf_pl).collect() shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┮─────┘ r¬res €r3r«zLazyFrame.cloneŸsø€ôF‰w‰}‹Ðr4có—|S)a4Lazify the DataFrame (if possible). If a library does not support lazy execution, then this is a no-op. Examples: Construct pandas and Polars objects: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) We define a library agnostic function: >>> def agnostic_lazy(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.lazy().to_native() Note that then, pandas dataframe stay eager, and the Polars LazyFrame stays lazy: >>> agnostic_lazy(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_lazy(lf_pl) rYr1s r3rzLazyFrame.lazyãs €ðBˆ r4có&•—t‰|||¬«S)uHTake every nth row in the DataFrame and return as a new DataFrame. Arguments: n: Gather every *n*-th row. offset: Starting index. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]} >>> df_pd = pd.DataFrame(data) >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function in which gather every 2 rows, starting from a offset of 1: >>> def agnostic_gather_every(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.gather_every(n=2, offset=1).to_native() >>> agnostic_gather_every(df_pd) a b 1 2 6 3 4 8 >>> agnostic_gather_every(lf_pl).collect() shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 2 ┆ 6 │ │ 4 ┆ 8 │ └─────┮─────┘ r­r®r¯s €r3r¯zLazyFrame.gather_everysø€ôP‰wÑ# a°Ð#Ó7Ð7r4rœcó*•—t‰|||||¬«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". 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 narwhals as nw >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": ["x", "y", "z"], ... "b": [1, 3, 5], ... "c": [2, 4, 6], ... } >>> lf_pl = pl.LazyFrame(data) We define a library agnostic function: >>> def agnostic_unpivot(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.unpivot(on=["b", "c"], index="a").sort(["variable", "a"]) ... ).to_native() >>> agnostic_unpivot(lf_pl).collect() shape: (6, 3) ┌─────┬──────────┬───────┐ │ a ┆ variable ┆ value │ │ --- ┆ --- ┆ --- │ │ str ┆ str ┆ i64 │ ╞═════╪══════════╪═══════╡ │ x ┆ b ┆ 1 │ │ y ┆ b ┆ 3 │ │ z ┆ b ┆ 5 │ │ x ┆ c ┆ 2 │ │ y ┆ c ┆ 4 │ │ z ┆ c ┆ 6 │ └─────┮──────────┮───────┘ r»r¿rÀs €r3r¿zLazyFrame.unpivot0s%ø€ô@‰w‰Ø˜šmÈ ðó ð r4)rÇztype[DataFrame[Any]]rÁrÅrÃ)r0z str | slicerÇr )rÇzDataFrame[Any])rÇr&rÊr/rÍrËrÌrÉrÊrÏrÐrÑrËrÒrÍrÔrÕ)r•r×r’r„rÇzLazyGroupBy[Self]rÖrØrÙrÝrÚrÛrÜrß)#rárârãrÏrårÔrór r÷r1rÜrr[rcr]rSrVrergrlrnrqrvrzr€r‹r–r’rŠržr«rr¯r¿rÐrÑs@r3rërëŸ sBø„ñðòóðð &à ð &ð6ð &ð ó &ó  ðò5óð5ó0ó& óP$CõN&7öP*1öX&,ðPôóðõ&(ð&ôóðð8M;Ø3ðM;ØDLðM;à õM;ð^n5à-ðn5ð ðn5ð õ n5õ`+'öZ8öt8ðtBF÷G>ðV*.ð>Pð9>Ø$ñ >Pà&ð>Pð6ð >Pð ð >Pð õ >Pð@w:ØEðw:ØVYðw:à õw:ðtBGñlPØ(ðlPØ:>ðlPà ólPðd-2Ø ñ >Xà ð>Xðð>Xð*ð >Xð ð >Xð õ >XðF&*ØAHð R ð +/Ø+/ØñR àðR ð #ðR ð?ð R ð (ð R ð)ðR ððR ð õR ðp#Ø#ØØ*.Ø+/Ø%)Ø>HñF àðF ðð F ð ð F ð ð F ð(ðF ð)ðF ð #ðF ð<ðF ð õF õP#óJ!öF(8ðX&*ðB ð)-Ø$(Ø!%ñ B ØðB à "ðB ð&ð B ð "ð B ð ð B ð ÷B ñB r4rë)7Ú __future__rÚtypingrrrrrr r r r r rÚnarwhals.dependenciesrrÚnarwhals.schemarÚnarwhals.translaterÚnarwhals.utilsrrrÚiorÚpathlibrÚtypesrÚnumpyÚnpÚpandasÚpdrrÚtyping_extensionsrr”rrrIr Únarwhals.typingr!r"r#r$r%r&r(r*rçrërYr4r3úrsÁðÝ"å ÝÝÝÝÝÝÝÝÝÝå,Ý0Ý"Ý(Ý"Ý2Ý(áÝÝÝ ãÛÛÝ&å)Ý-Ý&Ý-Ý(Ý)Ý(Ý-á  Ô -€Ù \šÔ 9€ ôb'˜‘ôb'ôJ h)  ˜*Ñ%ôh) ôVSt  ˜&Ñ!õt r4