}iG UddlmZddlZddlZddlZddlmZmZmZm Z m Z m Z ddl m Z ddlmZmZddlmZmZmZmZddlmZddlmZmZdd lmZdd lmZdd lm Z dd l!m"Z"dd l#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.ddl/m0Z0ddl1m2Z2ddl3m4Z4m5Z5ddl6m7Z7m8Z8m9Z9m:Z:m;Z;mZ>m?Z?m@Z@mAZAmBZBmCZCmDZDmEZEmFZFmGZGmHZHmIZIddlJmKZKmLZLmMZMe$rddlmNZNddlOmPZPddlQZRddlSZTddlUZVddlWmXZXmYZYmZZZm[Z[m\Z\m]Z]ddl^m_Z_m`Z`maZaddlbmcZcddldmeZemfZfmgZgmhZhddlimjZjddlkmlZlmmZmmnZnmoZompZpmqZqmrZrmsZsmtZtmuZumvZvmwZwddlxmyZymzZzm{Z{ddl|m}Z}m~Z~mZmZmZmZmZmZmZmZmZmZmZmZmZmZmZddlmZmZddlmZddlmZdd lmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZeZd!ed"<e+d#e,ee%ee%ee%f$Ze+d%Ze+d&Ze+d'Ze+d(d)$ZeZd*Ze+d+Ze+d,Ze+d-ZGd.d/e*ZGd0d1e*ZGd2d3e*Ze+d4Ze+d5d67Ze+d8d67Zd9Zd!ed:<e+d;e$ZdZd!ed?<Gd@dAe*eZGdBdCe*eZGdDdEe*ZGdFdGe*ZGdHdIe*ZGdJdKeee*ZGdLdMeee*ZGdNdOee*ZGdPdQeZGdRdSe0ZǐdxdWZejdXejdYejdZejd[ejd\ejd\ejd]ejd^ejd_ejd`ejdai Zdbedc<ejddejdeejdfejdgiZdhedi< edjkdydoZedzdqZאd{duZؐd|dwZِd}dyZڐd~d}ZېddZe.ddZe.ddZe.ddZe.ddZe.ddZe.ddZe.ddZݐddZݐddZސddZߐddZ dddddZddZe$reed6Zn"ddlZejdkreed6ZnddZddZddZddZddZddZ dddDŽZ dddȄZdd΄Zdd҄ZddԄZddքZdd؄ZddڄZdd܄ZddބZddZddZddZddZddZddZddZdddddZddZddZddZddZdd ZddZddZddZddZeZded<ddZdd Z dd#Z dd&Z dd'Z dd(Z dd*Zdd-Zdd/Zdd1Zdd3Zdd5Zdd:Zdd?ZddAZddCZGdDdEZddIZGdJdKZddOZddSZddUZddVddZZGd[d\e(eZed]kdd`Z dÐdbZ!Gdcddeeee*eZ"Gdedfe*eZ#GdgdhZ$dĐdkZ%ej&dlkrdŐdoZ'ndŐdpZ'dƐduZ(GdvdweZ)e)j*Z*e+dZ,dS() annotationsN) Collection ContainerIterableIteratorMappingSequence)timezone)Enumauto)cache lru_cachepartialwraps) find_spec)getattr_staticgetdoc)chain) attrgetter)Path) token_hex) TYPE_CHECKINGAnyCallableFinalGenericLiteralProtocolTypeVarUnioncastoverload) NoAutoEnum)issue_deprecation_warning) assert_never deprecated)get_cudfget_dask_dataframe get_duckdbget_ibis get_modin get_pandas get_polars get_pyarrowget_pyspark_connectget_pyspark_sql get_sqlframeis_narwhals_seriesis_narwhals_series_boolis_narwhals_series_intis_numpy_array_1dis_numpy_array_1d_boolis_numpy_array_1d_intis_pandas_like_dataframeis_pandas_like_series)ColumnNotFoundErrorDuplicateErrorInvalidOperationError)Set) ModuleType) Concatenate LiteralString ParamSpecSelf TypeAliasTypeIs)CompliantExprTCompliantSeriesTNativeSeriesT_co)NamespaceAccessor)Accessor EvalNamesNativeDataFrameTNativeLazyFrameT Namespace) NativeArrow NativeCuDF NativeDask NativeDuckDB NativeIbis NativeModin NativePandasNativePandasLike NativePolars NativePySparkNativePySparkConnectNativeSQLFrame)ArrowStreamExportableIntoArrowTableToNarwhalsT_co)Backend IntoBackend _ArrowImpl _CuDFImpl _DaskImpl _DuckDBImpl_EagerAllowedImpl _IbisImpl_LazyAllowedImpl_LazyFrameCollectImpl _ModinImpl _PandasImpl_PandasLikeImpl _PolarsImpl_PySparkConnectImpl _PySparkImpl _SQLFrameImpl DataFrame LazyFrameDTypeSeries)CompliantDataFrameCompliantLazyFrameCompliantSeriesDTypes FileSource IntoSeriesTMultiIndexSelector NestedLiteralSingleIndexSelectorSizedMultiBoolSelectorSizedMultiIndexSelectorSizeUnitSupportsNativeNamespaceTimeUnit_1DArray _SliceIndex _SliceName _SliceNonerCUnknownBackendNameFrameOrSeriesT)bound_T1_T2_T3_FnzCallable[..., Any]PRR1R2ceZdZUded<dS)_SupportsVersionstr __version__N__name__ __module__ __qualname____annotations__C/home/jrussi/.local/lib/python3.11/site-packages/narwhals/_utils.pyrrsrrceZdZdd dZdS) _SupportsGetNinstancerowner Any | NonereturncdSNrselfrrs r__get__z_SupportsGet.__get__srr)rrrrrr)rrrrrrrrrsQQQQQQQrrc&eZdZeddZdS)_StoresColumnsr Sequence[str]cdSrrrs rcolumnsz_StoresColumns.columnss,/CrN)rr)rrrpropertyrrrrrrs& /// ///rr_T NativeT_coT) covariant CompliantT_coz._FullContext | NamespaceAccessor[_FullContext] _IntoContext _IntoContextTz*Callable[Concatenate[_IntoContextT, P], R]_Methodz Callable[Concatenate[_T, P], R2] _Constructorc*eZdZdZeddZdS) _StoresNativezProvides access to a native object. Native objects have types like: >>> from pandas import Series >>> from pyarrow import Table rrcdS)zReturn the native object.Nrrs rnativez_StoresNative.native  rN)rr)rrr__doc__rrrrrrr>   X   rrc*eZdZdZeddZdS)_StoresCompliantzProvides access to a compliant object. Compliant objects have types like: >>> from narwhals._pandas_like.series import PandasLikeSeries >>> from narwhals._arrow.dataframe import ArrowDataFrame rrcdS)zReturn the compliant object.Nrrs r compliantz_StoresCompliant.compliantrrN)rr)rrrrrrrrrrrrrrc&eZdZeddZdS)_StoresBackendVersionrtuple[int, ...]cdS)z#Version tuple for a native package.Nrrs r_backend_versionz&_StoresBackendVersion._backend_versionrrNrr)rrrrrrrrrrs2    X   rrceZdZUded<dS)_StoresVersionVersion_versionNrrrrrrs,,rrceZdZUded<dS)_StoresImplementationImplementation_implementationNrrrrrrs####IIrrceZdZdZdS)_LimitedContextzEProvides 2 attributes. - `_implementation` - `_version` NrrrrrrrrrrrceZdZdZdS) _FullContextzMProvides 2 attributes. - `_implementation` - `_backend_version` NrrrrrrrrrceZdZdZddZdS)ValidateBackendVersionz=Ensure the target `Implementation` is on a supported version.rNonec8|j}dS)zRaise if installed version below `nw._utils.MIN_VERSIONS`. **Only use this when moving between backends.** Otherwise, the validation will have taken place already. N)rr)r_s r_validate_backend_versionz0ValidateBackendVersion._validate_backend_versions  1 1 3 3rN)rr)rrrrrrrrrrs.GG444444rrceZdZeZeZeZed dZeddZ eddZ edd Z edd Z d S)rrtype[Namespace[Any]]cj|tjurddlm}|S|tjurddlm}|Sddlm}|S)NrrM)rV1narwhals.stable.v1._namespacerNV2narwhals.stable.v2._namespacenarwhals._namespace)r NamespaceV1 NamespaceV2rNs r namespacezVersion.namespacesd 7:   N N N N N N  7:   N N N N N N 111111rrycj|tjurddlm}|S|tjurddlm}|Sddlm}|S)Nr)dtypes)rrnarwhals.stable.v1rrnarwhals.stable.v2narwhals)r dtypes_v1 dtypes_v2rs rrzVersion.dtypes sc 7:   > > > > > >  7:   > > > > > > ###### rtype[DataFrame[Any]]cj|tjurddlm}|S|tjurddlm}|Sddlm}|S)Nr)rp)rrrrprrnarwhals.dataframe)r DataFrameV1 DataFrameV2rps r dataframezVersion.dataframed 7:   C C C C C C  7:   C C C C C C 000000rtype[LazyFrame[Any]]cj|tjurddlm}|S|tjurddlm}|Sddlm}|S)Nr)rq)rrrrqrrr)r LazyFrameV1 LazyFrameV2rqs r lazyframezVersion.lazyframe(rrtype[Series[Any]]cj|tjurddlm}|S|tjurddlm}|Sddlm}|S)Nrrt)rrrrurrnarwhals.series)rSeriesV1SeriesV2rus rserieszVersion.series6sa 7:   = = = = = =O 7:   = = = = = =O****** rN)rr)rry)rr)rr)rr) rrrr rrMAINrrrrrrrrrrrs B B 466D    X    X    X    X    X   rrc"eZdZdZdZ dZ dZ dZ dZ dZ dZ d Z d Z d Z d Z d Z d-dZed.dZed/dZed0dZd1dZd2dZd2dZd2dZd2d Zd2d!Zd2d"Zd2d#Zd2d$Zd2d%Zd2d&Zd2d'Z d2d(Z!d2d)Z"d3d+Z#d,S)4rz?Implementation of native object (pandas, Polars, PyArrow, ...).pandasmodincudfpyarrowpysparkpolarsdaskduckdbibissqlframezpyspark[connect]unknownrrc*t|jSr)rvaluers r__str__zImplementation.__str__as4:rcls type[Self]native_namespacer>cVttjttjt tjttjttj ttj ttjttjt#tjt'tjt+tji }||tjS)zInstantiate Implementation object from a native namespace module. Arguments: native_namespace: Native namespace. )r,rPANDASr+MODINr'CUDFr.PYARROWr0PYSPARKr-POLARSr(DASKr)DUCKDBr*IBISr1SQLFRAMEr/PYSPARK_CONNECTgetUNKNOWN)rrmappings rfrom_native_namespacez$Implementation.from_native_namespaceds LL./ KK- JJ+ MM>1   ~5 LL./  ."5 LL./ JJ+ NNN3  ! !>#A  {{+^-CDDDr backend_namecR ||S#t$rtjcYSwxYw)zInstantiate Implementation object from a native namespace module. Arguments: backend_name: Name of backend, expressed as string. ) ValueErrorrr")rr%s r from_stringzImplementation.from_string|sA *3|$$ $ * * *!) ) ) ) *s &&backend)IntoBackend[Backend] | UnknownBackendNamect|tr||n+t|tr|n||S)zInstantiate from native namespace module, string, or Implementation. Arguments: backend: Backend to instantiate Implementation from. ) isinstancerr(rr$)rr)s r from_backendzImplementation.from_backendsU'3'' 4COOG $ $ $'>224**733  rc|tjurd}t||t||j}t|S)zCReturn the native namespace module corresponding to Implementation.z:Cannot return native namespace from UNKNOWN Implementation)rr"AssertionErrorr_IMPLEMENTATION_TO_MODULE_NAMEr!r_import_native_namespace)rmsg module_names rto_native_namespacez"Implementation.to_native_namespacesZ >) ) )NC %% % 488tzJJ ' 444rboolc|tjuS)a7Return whether implementation is pandas. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pandas() True )rrrs r is_pandaszImplementation.is_pandas~,,,rcL|tjtjtjhvS)aLReturn whether implementation is pandas, Modin, or cuDF. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pandas_like() True )rrrrrs ris_pandas_likezImplementation.is_pandas_likes-~/C^EXYYYrcL|tjtjtjhvS)aIReturn whether implementation is pyspark or sqlframe. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_spark_like() False )rrrr rs r is_spark_likezImplementation.is_spark_likes(  "  #  *   rc|tjuS)a7Return whether implementation is Polars. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_polars() True )rrrs r is_polarszImplementation.is_polarsr8rc|tjuS)a4Return whether implementation is cuDF. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_cudf() False )rrrs ris_cudfzImplementation.is_cudf~***rc|tjuS)a6Return whether implementation is Modin. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_modin() False )rrrs ris_modinzImplementation.is_modins~+++rc|tjuS)a:Return whether implementation is PySpark. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyspark() False )rrrs r is_pysparkzImplementation.is_pyspark~---rc|tjuS)aBReturn whether implementation is PySpark. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyspark_connect() False )rr rs ris_pyspark_connectz!Implementation.is_pyspark_connects~555rc|tjuS)a:Return whether implementation is PyArrow. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyarrow() False )rrrs r is_pyarrowzImplementation.is_pyarrowrFrc|tjuS)a4Return whether implementation is Dask. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_dask() False )rrrs ris_daskzImplementation.is_daskrArc|tjuS)a8Return whether implementation is DuckDB. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_duckdb() False )rrrs r is_duckdbzImplementation.is_duckdb)r8rc|tjuS)a4Return whether implementation is Ibis. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_ibis() False )rrrs ris_ibiszImplementation.is_ibis6rArc|tjuS)a<Return whether implementation is SQLFrame. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_sqlframe() False )rrrs r is_sqlframezImplementation.is_sqlframeCs~...rrc t|S)zReturns backend version.backend_versionrs rrzImplementation._backend_versionPst$$$rNrr)rrrr>rr)rrr%rrr)rrr)r*rr)rr>)rr5r)$rrrrrrrrrrrrrrr r"r classmethodr$r(r-r4r7r:r<r>r@rCrErHrJrLrNrPrRrrrrrrEs"II F E DG!G! F D F DH"(O)G!EEE[E. * * *[ *   [ 5555 - - - - Z Z Z Z    " - - - - + + + + , , , , . . . . 6 6 6 6 . . . . + + + + - - - - + + + + / / / /%%%%%%rrimplementationrr5c|p|o|dkS)zJWhether implementation is PySpark (or PySpark Connect) with version < 4.0.)r)rErHrrXs ris_pyspark_pre_4r\UsB !!##J~'H'H'J'J 5  ) ) + +f 45r)r])r) ) )r^)rrZ)ir_)r]r]))r^rz(Mapping[Implementation, tuple[int, ...]] MIN_VERSIONSzdask.dataframez modin.pandasz pyspark.sqlzpyspark.sql.connectzMapping[Implementation, str]r0)maxsizer3rr>c$ddlm}||S)Nr) import_module) importlibrl)r3rls rr1r1ss$'''''' = % %%rrc t|tst||tjurdS|}t||j}t|}|r ddl }|j }nL| s| rddl }|}n|rddl}|}n|}t!|}|t"|x} krd|d| d|} t%| |S)N)rrrrzMinimum version of z supported by Narwhals is z , found: )r,rr%r"r0r!rr1rRsqlframe._versionrrErHrrLr  parse_versionrhr') rXimplr3rr  into_versionrr version min_versionr2s rrUrU}s4 nn 5 5%^$$$///y D044T4:FFK/ <<  (    (    (d5577 ( (  ' L))Gd!33+44cDccKccZaccoo Nrargsr list[Any]ctt|dkrt|dr|dn|S)Nr]r)listlen _is_iterable)rus rflattenr{s6 CIINN|DG/D/DNQ4 P PPrargcDt|ttfs|fS|Sr)r,rxtuple)r|s rtupleifyrs$ cD%= ) )v JrAny | Iterable[Any]cddlm}tx}t||j|jfs8t x}Jt||j|j|j|jfr"dt|d}t|t|tot|tt|f S)Nrrtz(Expected Narwhals class or scalar, got: z`. Hint: Perhaps you - forgot a `nw.from_native` somewhere? - used `pl.col` instead of `nw.col`?) rrur,r,rpr-Exprrqqualified_type_name TypeErrorrrbytes)r|rupdplr2s rrzrzs&&&&&&|| (Zbi=V-W-W(|| ( sRYr|L M M )  37J37O7O 3 3 3 nn c8 $ $ RZc5&=Q-R-R)RRrvalIterable[_T] | AnyTypeIs[Iterator[_T]]c,t|tSr)r,r)rs r is_iteratorrs c8 $ $$rrs#str | ModuleType | _SupportsVersionct|tr|n|j}tjdd|}t d|dDS)zSimple version parser; split into a tuple of ints for comparison. Arguments: version: Version string, or object with one, to parse. z (\D?dev.*$)c3\K|]'}ttjdd|V(dS)z\DrN)intresub).0vs r z parse_version..s8KKqRVE2q))**KKKKKKr.)r,rrrrr~split)rs version_strs rrprps](55N''7;NK&[99K KKK4E4Ec4J4JKKK K KKr obj_or_clstype cls_or_tupletype[_T]TypeIs[type[_T]]cdSrrrrs risinstance_or_issubclassrs sr object | typeTypeIs[_T | type[_T]]cdSrrrs rrr  Crtuple[type[_T1], type[_T2]]TypeIs[type[_T1 | _T2]]cdSrrrs rrrs "cr#TypeIs[_T1 | _T2 | type[_T1 | _T2]]cdSrrrs rrrs +.#r&tuple[type[_T1], type[_T2], type[_T3]]TypeIs[type[_T1 | _T2 | _T3]]cdSrrrs rrrs %(Cr/TypeIs[_T1 | _T2 | _T3 | type[_T1 | _T2 | _T3]]cdSrrrs rrrs 7:crtuple[type, ...] TypeIs[Any]cdSrrrs rrrs #rcddlm}t||rt||St||p$t|tot ||S)Nrrr)narwhals.dtypesrsr,r issubclass)rrrss rrrsi%%%%%%*e$$4*l333 j, / / :t$$MJ )M)Mritems Iterable[Any]rcddlmmtfd|Dstfd|DrdSdd|D}t |)Nrroc38K|]}t|VdSrr,)ritemrps rrz$validate_laziness..s- 9 94:dI & & 9 9 9 9 9 9rc38K|]}t|VdSrr)rrrqs rrz$validate_laziness..s- : :DJtY ' ' : : : : : :rzGThe items to concatenate should either all be eager, or all lazy, got: c,g|]}t|Sr)r)rrs r z%validate_laziness..s#TrTrTrdhUYZ^U_U_TrTrTrr)rrprqallr)rr2rprqs @@rvalidate_lazinessrs77777777 9 9 9 95 9 9 999 : : : :E : : :::  tTrTrlqTrTrTr t tC C..rlhsrhs-Series[Any] | DataFrame[Any] | LazyFrame[Any]c ddlm}ddlm}dd}t d|}t d|}t t |d d |rt t |d d |r||jjj ||jjj | |j |jjj |jjj St t |d d |rt t |d d |r||jjj ||j jj | |j |jjj |j jj St t |d d |rt t |d d |r||j jj ||jjj | |j |j jj |jjj St t |d d |rt t |d d |r||j jj ||j jj | |j |j jj |j jj St|t|kr1d t|d t|}t||S)aAlign `lhs` to the Index of `rhs`, if they're both pandas-like. Arguments: lhs: Dataframe or Series. rhs: Dataframe or Series to align with. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this only checks that `lhs` and `rhs` are the same length. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2]}, index=[3, 4]) >>> s_pd = pd.Series([6, 7], index=[4, 3]) >>> df = nw.from_native(df_pd) >>> s = nw.from_native(s_pd, series_only=True) >>> nw.to_native(nw.maybe_align_index(df, s)) a 4 2 3 1 r)PandasLikeDataFrame)PandasLikeSeriesindexrrrc6|jsd}t|dS)Nz'given index doesn't have a unique index) is_uniquer')rr2s r_validate_indexz*maybe_align_index.._validate_index-s' ";CS// ! " "r_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )rrrr)narwhals._pandas_like.dataframernarwhals._pandas_like.seriesrr!r,getattrrrr_with_compliant _with_nativelocrryr')rrrrrlhs_anyrhs_anyr2s rmaybe_align_indexr s<DCCCCC======"""" 5#G5#G+T224G  WW&8$??AT U U   07=>>>07=>>>&&  $ 1 1(/3G4L4S4YZ     +T224G  WW&94@@BR S S   07=>>>18>???&&  $ 1 1(/3-4:     ,d335E  WW&8$??AT U U   18>???07=>>>&&  % 2 2)04,39     ,d335E  WW&94@@BR S S   18>???18>???&&  % 2 2)04-4:      7||s7||##hs7||hhZ]^eZfZfhhoo Jrobj-DataFrame[Any] | LazyFrame[Any] | Series[Any]rctd|}|}t|st|r|jSdS)aGet the index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: Dataframe or Series. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this returns `None`. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df = nw.from_native(df_pd) >>> nw.maybe_get_index(df) RangeIndex(start=0, stop=2, step=1) >>> series_pd = pd.Series([1, 2]) >>> series = nw.from_native(series_pd, series_only=True) >>> nw.maybe_get_index(series) RangeIndex(start=0, stop=2, step=1) rN)r! to_nativer8r9r)robj_any native_objs rmaybe_get_indexrhsR45#G""$$J ++ /DZ/P/P  4r)r column_namesstr | list[str] | Noner6Series[IntoSeriesT] | list[Series[IntoSeriesT]] | Nonecddlmtd|}|}||d}t||s|d}t||+t |rfd|Dn |d }n|}t |r@||j| |St|r^dd l m }|rd }t|||||j j }||j |S|S) aSet the index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: object for which maybe set the index (can be either a Narwhals `DataFrame` or `Series`). column_names: name or list of names of the columns to set as index. For dataframes, only one of `column_names` and `index` can be specified but not both. If `column_names` is passed and `df` is a Series, then a `ValueError` is raised. index: series or list of series to set as index. Raises: ValueError: If one of the following conditions happens - none of `column_names` and `index` are provided - both `column_names` and `index` are provided - `column_names` is provided and `df` is a Series Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this is a no-op. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df = nw.from_native(df_pd) >>> nw.to_native(nw.maybe_set_index(df, "b")) # doctest: +NORMALIZE_WHITESPACE a b 4 1 5 2 r)rrNz8Only one of `column_names` or `index` should be providedz3Either `column_names` or `index` should be providedc*g|]}|dS)T pass_throughr)ridxrs rrz#maybe_set_index..s( @ @ @3YYs . . . @ @ @rTr) set_indexz/Cannot set index using column names on a Seriesr[)narwhals.translaterr!r'rzr8rrrrr9narwhals._pandas_like.utilsrr) rrrdf_anyrr2keysrrs @rmaybe_set_indexrsX-,,,,, %  F!!##JE$5Hoo EMCoo E"" 5 @ @ @ @% @ @ @ @5t444   ++ %%  # 0 01E1Ed1K1K L L   Z(( Y999999  "CCS// !Y  0@   %%f&>&K&KJ&W&WXXX Mrc&td|}|}t|rg|}t ||r|S||j|dSt|rg|}t ||r|S||j |dS|S)aReset the index to the default integer index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: Dataframe or Series. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already resets the index for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this is a no-op. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}, index=([6, 7])) >>> df = nw.from_native(df_pd) >>> nw.to_native(nw.maybe_reset_index(df)) a b 0 1 4 1 2 5 >>> series_pd = pd.Series([1, 2]) >>> series = nw.from_native(series_pd, series_only=True) >>> nw.maybe_get_index(series) RangeIndex(start=0, stop=2, step=1) rT)drop) r!rr8__native_namespace___has_default_indexrrr reset_indexr9r)rrrrs rmaybe_reset_indexrs85#G""$$J ++ "7799 j*: ; ; N&&  $ 1 1*2H2Hd2H2S2S T T   Z(( "7799 j*: ; ; N&&  % 2 2:3I3It3I3T3T U U    Nr)strict)r^rb iterablesIterable[tuple[Any, ...]]cNt|dkr t|Sddfd }dfd }t|}tt ||}t t t|tt|gR|S)Nr`Frrc3KddS)NTr) first_stoppedsr first_tailzzip_strict..first_tails $ rc3Ksd}t|tjD]}d}t|dS)Nz$zip_strict: first iterable is longerz%zip_strict: first iterable is shorter)r'r from_iterable)r2rrrests rzip_tailzzip_strict..zip_tail&sU$*@C$S//),T22AAC$S//)r)rr)ryzipiterrnextrxmap)rrr iterables_itfirstrrs @@r zip_strictrs9~~!!I&!M              ??L$|,,jjll;;ED,//00DU*T***HHJJ77 7rrTypeIs[pd.RangeIndex]c,t||jSr)r, RangeIndex)rrs r_is_range_indexr6s c+6 7 77rnative_frame_or_seriespd.Series[Any] | pd.DataFramec|j}t||o-|jdko"|jt |ko |jdkS)Nrr])rrstartstoprystep)rrrs rrr:sS # (E/00  K1   J#e** $  J!O rkwargs bool | strc |js|S||j|j|i|}td|S)a-Convert columns or series to the best possible dtypes using dtypes supporting ``pd.NA``, if df is pandas-like. Arguments: obj: DataFrame or Series. *args: Additional arguments which gets passed through. **kwargs: Additional arguments which gets passed through. Notes: For non-pandas-like inputs, this is a no-op. Also, `args` and `kwargs` just get passed down to the underlying library as-is. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> import numpy as np >>> df_pd = pd.DataFrame( ... { ... "a": pd.Series([1, 2, 3], dtype=np.dtype("int32")), ... "b": pd.Series([True, False, np.nan], dtype=np.dtype("O")), ... } ... ) >>> df = nw.from_native(df_pd) >>> nw.to_native( ... nw.maybe_convert_dtypes(df) ... ).dtypes # doctest: +NORMALIZE_WHITESPACE a Int32 b boolean dtype: object r)rXr:r _compliantrrconvert_dtypesr!)rrur results rmaybe_convert_dtypesrFswB   , , . .   ##$BCMMOO$BD$SF$S$STTF  & ) ))rszrunitr int | floatc~|dvr|S|dvr|dz S|dvr|dz S|dvr|dz S|dvr|d z Sd |}t|) zScale size in bytes to other size units (eg: "kb", "mb", "gb", "tb"). Arguments: sz: original size in bytes unit: size unit to convert into >br>kb kilobytesi>mb megabytesi>gb gigabytesi@>tb terabyteslz9`unit` must be one of {'b', 'kb', 'mb', 'gb', 'tb'}, got r')rrr2s r scale_bytesr"os ~  """Dy """G| """G| """G| P P PC S//rr Series[Any]cddlm}|jjj}|j}d}t ||r-t |j|jr|jj d}n|j|j krd}n|j|jkrd}n| }|j }| r7|dkrtd|jjdk}nd|rt%|jj}n6|r"dd lm}||jo |jj}|S) aReturn whether indices of categories are semantically meaningful. This is a convenience function to accessing what would otherwise be the `is_ordered` property from the DataFrame Interchange Protocol, see https://data-apis.org/dataframe-protocol/latest/API.html. - For Polars: - Enums are always ordered. - Categoricals are ordered if `dtype.ordering == "physical"`. - For pandas-like APIs: - Categoricals are ordered if `dtype.cat.ordered == True`. - For PyArrow table: - Categoricals are ordered if `dtype.type.ordered == True`. Arguments: series: Input Series. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = ["x", "y"] >>> >>> s_pd = nw.from_native( ... pd.Series(data, dtype=pd.CategoricalDtype(ordered=True)), series_only=True ... ) >>> nw.is_ordered_categorical(s_pd) True >>> s_pl = nw.from_native( ... pl.Series(data, dtype=pl.Categorical()), series_only=True ... ) >>> nw.is_ordered_categorical(s_pl) False r)InterchangeSeriesF is_orderedT)r] zpl.Categoricalphysical) is_dictionary)narwhals._interchange.seriesr%rrrr,dtype Categoricalrdescribe_categoricalr rrXr>rr!orderingr:r5catorderedrJnarwhals._arrow.utilsr)r)rr%rrrrrqr)s ris_ordered_categoricalr2sqF?>>>>>  % . 5F(IF).//HJ f(55H!6|D  $ $ + + +!!##$ >>   H 5 5 7 7' A A*FL99BjPFF  " " H&*,--FF __   H ; ; ; ; ; ;"]6;//GFK4GF Mrnwn_bytesrContainer[str]prefixcLd}t|dt|||S)Nz}Use `generate_temporary_column_name` instead. `generate_unique_token` is deprecated and it will be removed in future versionsz1.13.0r)r4rr6)r$generate_temporary_column_name)r4rr6r2s rgenerate_unique_tokenr:s7 ?cH5555 )'7SY Z Z ZZrcd} |t|dz x}|vr|S|dz }|dkrd|d|}t|?)aGenerates a unique column name that is not present in the given list of columns. It relies on [python secrets token_hex](https://docs.python.org/3/library/secrets.html#secrets.token_hex) function to return a string nbytes random bytes. Arguments: n_bytes: The number of bytes to generate for the token. columns: The list of columns to check for uniqueness. prefix: prefix with which the temporary column name should start with. Returns: A unique token that is not present in the given list of columns. Raises: AssertionError: If a unique token cannot be generated after 100 attempts. Examples: >>> import narwhals as nw >>> columns = ["abc", "xyz"] >>> nw.generate_temporary_column_name(n_bytes=8, columns=columns) not in columns True >>> temp_name = nw.generate_temporary_column_name( ... n_bytes=8, columns=columns, prefix="foo" ... ) >>> temp_name not in columns and temp_name.startswith("foo") True rTr]dzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in )rr/)r4rr6countertokenr2s rr9r9s<G &8 'A+ 6 688 8E H HL1  S==333)033 !%% % &rframesubset Iterable[str]r list[str]c|s4tt|j|St|}t ||jx}r||S)N) available)rxsetr intersectioncheck_columns_exist)r?r@rto_droperrors rparse_columns_to_droprJsc =C &&33F;;<<<6llG#Gu}EEEEu NrsequenceSequence[_T] | AnyTypeIs[Sequence[_T]]cXt|tot|t Sr)r,r r)rKs ris_sequence_but_not_strrOs$ h ) ) K*Xs2K2K.KKrTypeIs[_SliceNone]cRt|to|tdkSr)r,slicers r is_slice_nonerT s" c5 ! ! 8cU4[[&88rCTypeIs[SizedMultiIndexSelector[Series[Any] | CompliantSeries[Any]]]ct|o:t|dkrt|dpt|dkp,t|pt |pt |SNr)rOryis_single_index_selectorr7r4is_compliant_series_intrSs ris_sized_multi_index_selectorrZs $C ( ( Yc((Q,C#;CF#C#CWSUV ( ! % %  ( "# & &  ( #3 ' 'r-TypeIs[Sequence[_T] | Series[Any] | _1DArray]czt|p,t|pt|pt|Sr)rOr5r2is_compliant_seriesrSs ris_sequence_liker^sF $$ $ S ! ! $ c " " $ s # # rTypeIs[_SliceIndex]ct|toft|jtpLt|jtp2t|jtt fo|jduo|jduSr)r,rRr rr r NoneTyperSs ris_slice_indexrb)st c5 ! ! 39c"" ch $ $  sx#x 1 1 ! T! !D r TypeIs[range]c,t|tSr)r,rangerSs ris_rangerf5s c5 ! !!rTypeIs[SingleIndexSelector]crtt|tot|t Sr)r5r,rrSs rrXrX9s,  3$$BZT-B-B)B C CCrTTypeIs[SingleIndexSelector | MultiIndexSelector[Series[Any] | CompliantSeries[Any]]]c\t|pt|pt|Sr)rXrZrbrSs ris_index_selectorrk=s4 !%%  ( - -  #  rBTypeIs[SizedMultiBoolSelector[Series[Any] | CompliantSeries[Any]]]ct|r.t|dkrt|dtp,t |pt |pt |SrW)rOryr,r5r6r3is_compliant_series_boolrSs ris_boolean_selectorroGsh ! % % U3s88a<+TJs1vt.Zs,==$z$%%======rany)rts r predicates_contains_list_of_boolr|Ws! ==*=== = ==rctt|o.tt|dx}ot ||Sr)r5rOrrr,)rrprs ris_sequence_ofr~]sN $$ "499d++ +U " ub ! !  rTypeIs[NestedLiteral]cFt|tttfSr)r,rxr~dictrSs ris_nested_literalrfs cD%. / //r bool | Nonerpass_through_defaultcP|||}n||| }n||nd}t||S)Nz,Cannot pass both `strict` and `pass_through`r!)rrrr2s rvalidate_strict_and_pass_thoughrjsM ~,.+   4!z L4 <oo rrF) warn_versionrequiredrr*Callable[[Callable[P, R]], Callable[P, R]]cdfd }|S)a8Decorator to transition from `native_namespace` to `backend` argument. Arguments: warn_version: Emit a deprecation warning from this version. required: Raise when both `native_namespace`, `backend` are `None`. Returns: Wrapped function, with `native_namespace` **removed**. fnCallable[P, R]rcDtdfd }|S) NruP.argskwdsP.kwargsrrc|dd}|dd}||rd}t||}n5||d}t|||rdjd}t|||d<|i|S)Nr)rz`native_namespace` is deprecated, please use `backend` instead. Note: `native_namespace` will remain available in `narwhals.stable.v1`. See https://narwhals-dev.github.io/narwhals/backcompat/ for more information. r8z0Can't pass both `native_namespace` and `backend`z `backend` must be specified in `z`.)popr$r'r)rurr)rr2rrrs rwrapperz=deprecate_native_namespace..decorate..wrappershhy$//G#xx(:DAA +Jj .cLIIII*!-'2EH oo%!)go(oHHHH oo%%DO2t$t$$ $r)rurrrrr)r)rrrrs` rdecoratez,deprecate_native_namespace..decoratesC r % % % % % % %  %*r)rrrrr)rrrs`` rdeprecate_native_namespacer|s.2 Or window_size min_samples int | Nonetuple[int, int]ct|tdt|ttdd|dkrd}t||/|dkrd}t|||krd}t |n|}||fS)Nr param_namerr]z+window_size must be greater or equal than 1z+min_samples must be greater or equal than 1z6`min_samples` must be less or equal than `window_size`) ensure_typerrr'r<)rrr2s r_validate_rolling_argumentsrs S];;;; S$t**GGGGQ;oo ???CS// !  $ $JC',, , %"  ##rheader native_reprc  tjj}n2#t$r%t tjdd}YnwxYw|}td|D}|dz|krt|t|}dd|zd}|t|z }|dd |dzz|d |dz|dzzzd z }|dd |zd z }||z dz}||z dz||z dzz} |D](} |dd |z| d | |zt| z zd z })|d d|zd z }|Sdt|z } dddd | dzz|d | dz| dzzzddd S)NCOLUMNSPc34K|]}t|VdSr)ry)rlines rrz generate_repr..s(>>3t99>>>>>>rr`u┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorrgetenv expandtabs splitlinesmaxry) rrterminal_width native_linesmax_native_widthlengthoutput header_extra start_extra end_extrardiffs r generate_reprrsE7-//7 777RYy"55667))++6688L>>>>>>>!~--%s6{{33,uv~,,,F + jc\Q./jj PQ@QT`cdTd@d9ejjjj)cVn)))) 00Q6 ..14AQ8QUV7VV   k kD j#-jtjSIHXz1check_column_names_are_unique..s#@@@tq!!a%%a%%%rrc3.K|]\}}d|d|dVdS)z - 'z' z timesNrrs rrz0check_column_names_are_unique..s:LLA,a,,1,,,LLLLLLrz"Expected unique column names, got:)ryrE collectionsrrjoinr;)rrr= duplicatesr2s rcheck_column_names_are_uniquers 7||s3w<<((((''''''''""@@w}}@@@ ggLL9I9I9K9KLLLLL8388S!!!)(r time_unit$TimeUnit | Iterable[TimeUnit] | None time_zone7str | timezone | Iterable[str | timezone | None] | None%tuple[Set[TimeUnit], Set[str | None]]c|hdn&t|tr|hnt|}|dhn7t|ttfrt|hn d|D}||fS)N>smsnsusc4h|]}|t|ndSr)r)rtzs r z1_parse_time_unit_and_time_zone..s& F F Fbc"gggT F F Fr)r,rrEr )rr time_units time_zoness r_parse_time_unit_and_time_zoners    i % %i[[ ^^     i#x 1 1Gc)nn   F FI F F F  z !!rr+rsrryr Set[TimeUnit]rSet[str | None]cjt||jo|j|vo|j|vp d|vo|jduS)N*)r,Datetimerr)r+rrrs r%dtype_matches_time_unit_and_time_zonersR 5&/** _ *  Oz ) Cz!AeoT&A rrc|jSrr)r?s rget_column_namesrs =rnamesc*fd|jDS)Ncg|]}|v| Srr)rcol_namers rrz(exclude_column_names..s# L L Lhe6K6KH6K6K6Krr)r?rs `rexclude_column_namesrs L L L LU] L L LLrEvalNames[Any]cdfd }|S)N_framerrrcSrr)rrs rrz$passthrough_column_names..fns r)rrrrr)rrs` rpassthrough_column_namesrs( Irr _SENTINELattrc<t||ttuSr)rr)rrs r_hasattr_staticr$s #tY / /y @@r\CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co] | Any^TypeIs[CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co]]c"t|dS)N__narwhals_dataframe__rrSs ris_compliant_dataframer(s 3 8 9 99rJCompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co] | AnyLTypeIs[CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co]]c"t|dS)N__narwhals_lazyframe__rrSs ris_compliant_lazyframer3s 3 8 9 99r'CompliantSeries[NativeSeriesT_co] | Any)TypeIs[CompliantSeries[NativeSeriesT_co]]c"t|dS)N__narwhals_series__rrSs rr]r]9s 3 5 6 66rcRt|o|jSr)r]r+ is_integerrSs rrYrY?% s # # > (<(<(>(>>rcRt|o|jSr)r]r+ is_booleanrSs rrnrnErr'TypeIs[NamespaceAccessor[_FullContext]]cBt|dot|dS)Nr _accessorrrSs r_is_namespace_accessorr Ks# 3 , , Rk1R1RRrrqTypeIs[_EagerAllowedImpl]cx|tjtjtjtjtjhvS)z.Return True if `impl` allows eager operations.)rrrrrrrqs ris_eager_allowedrUs2   rTypeIs[_LazyFrameCollectImpl]cL|tjtjtjhvS)z4Return True if `LazyFrame.collect(impl)` is allowed.)rrrrr s rcan_lazyframe_collectr`s N)>+@.BXY YYrTypeIs[_LazyAllowedImpl]c|tjtjtjtjtjtjtjhvS)z1Return True if `DataFrame.lazy(impl)` is allowed.)rrrrrrr rr s ris_lazy_allowedres> & rTypeIs[SupportsNativeNamespace]c"t|dS)NrrrSs rhas_native_namespacerrs 3 6 7 77rTypeIs[ArrowStreamExportable]c"t|dS)N__arrow_c_stream__rrSs rsupports_arrow_c_streamrvs 3 4 5 55rleft_onright_onsuffixdict[str, str]c^fd|D}tt||S)aORemap join keys to avoid collisions. If left keys collide with the right keys, append the suffix. If there's no collision, let the right keys be. Arguments: left_on: Left keys. right_on: Right keys. suffix: Suffix to append to right keys. Returns: A map of old to new right keys. c30K|]}|vr|n|VdSrr)rkeyrrs rrz(_remap_full_join_keys..sL8;C7NN3r)rr)rrrright_keys_suffixeds` ` r_remap_full_join_keysr$zsM ?G H122 3 33rdatar\contextpa.TablectdrE|jjdj}|j||jSdt|d}t|)zGuards `ArrowDataFrame.from_arrow` w/ safer imports. Arguments: data: Object which implements `__arrow_c_stream__`. context: Initialized compliant object. r)r&zB'pyarrow>=14.0.0' is required for `from_arrow` for object of type r) rrrr-r _dataframe from_arrowrrModuleNotFoundError)r%r&rr2s r_into_arrow_tabler,swA   ' 4 4Y ? ? I}''b'99@@ mObcgOhOh m m mC c " ""rrc|S)aVisual-only marker for unstable functionality. Arguments: fn: Function to decorate. Returns: Decorated function (unchanged). Examples: >>> @unstable ... def a_work_in_progress_feature(*args): ... return args >>> >>> a_work_in_progress_feature.__name__ 'a_work_in_progress_feature' >>> a_work_in_progress_feature(1, 2, 3) (1, 2, 3) r)rs runstabler.s & Irformatc<tfddD S)aDetermines if a datetime format string is 'naive', i.e., does not include timezone information. A format is considered naive if it does not contain any of the following - '%s': Unix timestamp - '%z': UTC offset - 'Z' : UTC timezone designator Arguments: format: The datetime format string to check. Returns: bool: True if the format is naive (does not include timezone info), False otherwise. c3 K|]}|vV dSrr)rxr/s rrz#_is_naive_format..s'::11;::::::r)z%sz%zZrz)r/s`r_is_naive_formatr4s,::::(9::::: ::rcXeZdZdZdddZdd Zdd Z dddZddZe d dZ dS)!not_implementedaMark some functionality as unsupported. Arguments: alias: optional name used instead of the data model hook [`__set_name__`]. Returns: An exception-raising [descriptor]. Notes: - Attribute/method name *doesn't* need to be declared twice - Allows different behavior when looked up on the class vs instance - Allows us to use `isinstance(...)` instead of monkeypatching an attribute to the function Examples: >>> class Thing: ... def totally_ready(self) -> str: ... return "I'm ready!" ... ... not_ready_yet = not_implemented() >>> >>> thing = Thing() >>> thing.totally_ready() "I'm ready!" >>> thing.not_ready_yet() Traceback (most recent call last): ... NotImplementedError: 'not_ready_yet' is not implemented for: 'Thing'. ... >>> isinstance(Thing.not_ready_yet, not_implemented) True [`__set_name__`]: https://docs.python.org/3/reference/datamodel.html#object.__set_name__ [descriptor]: https://docs.python.org/3/howto/descriptor.html Nalias str | Nonerrc||_dSr)_alias)rr7s r__init__znot_implemented.__init__s#( rrcPdt|jd|jd|jS)N: r)rr _name_owner_namers r__repr__znot_implemented.__repr__s.J4::&JJ4+;JJdjJJJrrrnamec:|j|_|jp||_dSr)rr>r:r?rrrAs r __set_name__znot_implemented.__set_name__s %+- rr_T | Literal['raise'] | Nonetype[_T] | Nonerc||St|dtj}|tjurt|}n|j}t |j|dS)Nr)rrr"reprr>_raise_not_implemented_errorr?)rrrrXwhos rrznot_implemented.__get__sd  K!+TUU !7 7 7~&&CC"C$TZ555trrurc,|dS)Nraise)r)rrurs r__call__znot_implemented.__call__ s||G$$$rmessager@rBcF|}t||S)zAlt constructor, wraps with `@deprecated`. Arguments: message: **Static-only** deprecation message, emitted in an IDE. [descriptor]: https://docs.python.org/3/howto/descriptor.html )r&)rrNrs rr&znot_implemented.deprecateds'cee"z'""3'''rr)r7r8rrrV)rrrArrr)rrErrFrr)rurrrrr)rNr@rrB) rrrrr;r@rDrrMrWr&rrrr6r6s!!F((((( KKKK.... PT$%%%%  ( ( ([ ( ( (rr6whatrJNotImplementedErrorc0|d|d}t|)Nz is not implemented for: z. If you would like to see this functionality in `narwhals`, please open an issue at: https://github.com/narwhals-dev/narwhals/issues)rQ)rPrJr2s rrIrIs:  S SC S S S c " ""rceZdZUdZded<ded<ded< eddd ZeddZddZ d dZ d!dZ d"dZ dS)#requiresaMethod decorator for raising under certain constraints. Attributes: _min_version: Minimum backend version. _hint: Optional suggested alternative. Examples: >>> class SomeBackend: ... _implementation = Implementation.PYARROW ... _backend_version = 20, 0, 0 ... ... @requires.backend_version((9000, 0, 0)) ... def really_complex_feature(self) -> str: ... return "hello" >>> backend = SomeBackend() >>> backend.really_complex_feature() Traceback (most recent call last): ... NotImplementedError: `really_complex_feature` is only available in 'pyarrow>=9000.0.0', found version '20.0.0'. r _min_versionr_hint _wrapped_namerhintminimumrrBcL||}||_||_|S)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. )__new__rUrV)rrYrXrs rrUzrequires.backend_versionDs)kk#"  rrUc@dd|DS)Nrc3K|]}|VdSrr)rds rrz,requires._unparse_version..Ss$8811888888r)rrTs r_unparse_versionzrequires._unparse_versionQs#xx88888888rr6rIrc>d|jvr|d|j|_dSdSNr)rW)rr6s r_qualify_accessor_namezrequires._qualify_accessor_nameUs7 d( ( ($*!A!AT-?!A!AD    ) (rrrtuple[tuple[int, ...], str]ct|r"||j|j}n|}|jt |jfSr)r rbr rrrr)rrrs r_unwrap_contextzrequires._unwrap_contextZsQ !( + + !  ' '(: ; ; ; *II I)3y/H+I+IIIrc ||\}}||jkrdS||j}||}d|jd|d|d|d }|jr |d|j}t |)N`z` is only available in 'z>=z', found version r )rerUr_rWrVrQ)rrrsr)rYfoundr2s r_ensure_versionzrequires._ensure_versionbs//99 d' ' ' F''(9::%%g..m$$mmgmmmmchmmm : )((DJ((C!#&&&rr_Method[_IntoContextT, P, R]cZj_td fd }|S) NrrrurrrrrcF||g|Ri|Sr)rj)rrurrrs rrz"requires.__call__..wrapperrs7   * * *2h...... .r)rrrurrrrr)rrWr)rrrs`` rrMzrequires.__call__msJ [ r / / / / / /  / rN)r)rXrrYrrrB)rUrrr)r6rIrr)rrrrc)rrrr)rrkrrk) rrrrrrWrU staticmethodr_rbrerjrMrrrrTrT&s*"!!!JJJ     [ 999\9BBBB JJJJ ' ' ' '      rrT str_slicer"tuple[int | None, int | None, Any]c|j||jnd}|j||jdznd}|j}|||fS)Nr])r rr r )rorr r r s rconvert_str_slice_to_int_slicerr{s\/8o.IGMM)/ * * *tE090J7== ( (1 , ,PTD >D 4 r tp_parentCallable[P, R1].decorates  * , ,DOOT1R1R ,!' !2!2J   %% % %!. % %  % % nnr)rwrxrrxr)rsrs` rrzrzs(       Orobject | type[Any]ct|tr|nt|}|jdkr|jnd}|d|jdS)Nbuiltinsrr)r,rrrlstrip)rrpmodules rrrs[3%% 4499B mz99R]]rF $ $r{ $ $ + +C 0 00rr valid_types type[Any]rct||sdd|D}d|dt|}|rnd}t|}t |dkrt|d}||d}d t |zd t |zz}|d ||d |}t |d S) aValidate that an object is an instance of one or more specified types. Parameters: obj: The object to validate. *valid_types: One or more valid types that `obj` is expected to match. param_name: The name of the parameter being validated. Used to improve error message clarity. Raises: TypeError: If `obj` is not an instance of any of the provided `valid_types`. Examples: >>> ensure_type(42, int, float) >>> ensure_type("hello", str) >>> ensure_type("hello", int, param_name="test") Traceback (most recent call last): ... TypeError: Expected 'int', got: 'str' test='hello' ^^^^^^^ >>> import polars as pl >>> import pandas as pd >>> df = pl.DataFrame([[1], [2], [3], [4], [5]], schema=[*"abcde"]) >>> ensure_type(df, pd.DataFrame, param_name="df") Traceback (most recent call last): ... TypeError: Expected 'pandas.DataFrame', got: 'polars.dataframe.frame.DataFrame' df=polars.dataframe.frame.DataFrame(...) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ z | c34K|]}t|VdSr)r)rrps rrzensure_type..s+LL"1"55LLLLLLrz Expected z, got: z (z(...)=r^rhN)r,rrrHryr) rrrtp_namesr2left_padrassign underlines rrrs@ c; ' ' ::LL LLLLLI(II-@-E-EII  7Hs))C3xx"}},S11888 /*///Fs6{{*sSXX~>I66F6C66966Cnn  rc*eZdZdZd dZd dZdd Zd S)_DeferredIterablezLStore a callable producing an iterable to defer collection until we need it. into_iterCallable[[], Iterable[_T]]rrc||_dSr _into_iter)rrs rr;z_DeferredIterable.__init__s 6?r Iterator[_T]c#>K|Ed{VdSrrrs r__iter__z_DeferredIterable.__iter__s.??$$$$$$$$$$$rtuple[_T, ...]cv|}t|tr|nt|Sr)rr,r~)rits rto_tuplez_DeferredIterable.to_tuples0 __  E**9rrb 9rN)rrrr)rr)rr)rrrrr;rrrrrrrsZVV@@@@%%%%::::::rr@nestedattrgetter[Any]cZ|rd|g|Rn|}t|Sra)rr)rrrAs rdeep_attrgetterrs3(. 8388TOFOO $ $ $DD d  rname_1c.t|g|R|S)z+Perform a nested attribute lookup on `obj`.)r)rrrs r deep_getattrrs" +?6 +F + + +C 0 00rceZdZdS) CompliantN)rrrrrrrrs3rrc*eZdZdZeddZdS)NarwhalsaMinimal *Narwhals-level* protocol. Provides access to a compliant object: obj: Narwhals[NativeT_co]] compliant: Compliant[NativeT_co] = obj._compliant Which itself exposes: implementation: Implementation = compliant.implementation native: NativeT_co = compliant.native This interface is used for revealing which `Implementation` member is associated with **either**: - One or more [nominal] native type(s) - One or more [structural] type(s) - where the true native type(s) are [assignable to] *at least* one of them These relationships are defined in the `@overload`s of `_Implementation.__get__(...)`. [nominal]: https://typing.python.org/en/latest/spec/glossary.html#term-nominal [structural]: https://typing.python.org/en/latest/spec/glossary.html#term-structural [assignable to]: https://typing.python.org/en/latest/spec/glossary.html#term-assignable rCompliant[NativeT_co]cdSrrrs rrzNarwhals._compliant s363rN)rr)rrrrrrrrrrrs20666X666rrceZdZdZd;dZeddZed?dZed@dZedAdZedBdZedCd"ZedDd%ZedEd(ZedFd+ZedGd.ZedHd1ZedId4ZedJd7ZdKd9Zd:S)L_ImplementationzDescriptor for matching an opaque `Implementation` on a generic class. Based on [pyright comment](https://github.com/microsoft/pyright/issues/3071#issuecomment-1043978070) rrrArrrc||_dSr)rrCs rrDz_Implementation.__set_name__s ! rrNarwhals[NativePolars]rrkcdSrrrs rrz_Implementation.__get__TWTWrNarwhals[NativePandas]ricdSrrrs rrz_Implementation.__get__rrNarwhals[NativeModin]rhcdSrrrs rrz_Implementation.__get__RURUrNarwhals[NativeCuDF]racdSrrrs rrz_Implementation.__get__PSPSrNarwhals[NativePandasLike]rjcdSrrrs rrz_Implementation.__get__ s #rNarwhals[NativeArrow]r`cdSrrrs rrz_Implementation.__get__$rr3Narwhals[NativePolars | NativeArrow | NativePandas]&_PolarsImpl | _PandasImpl | _ArrowImplcdSrrrs rrz_Implementation.__get__&s 25rNarwhals[NativeDuckDB]rccdSrrrs rrz_Implementation.__get__*rrNarwhals[NativeSQLFrame]rncdSrrrs rrz_Implementation.__get__,s rNarwhals[NativeDask]rbcdSrrrs rrz_Implementation.__get__0rrNarwhals[NativeIbis]recdSrrrs rrz_Implementation.__get__2rr.Narwhals[NativePySpark | NativePySparkConnect]"_PySparkImpl | _PySparkConnectImplcdSrrrs rrz_Implementation.__get__4s .1Srtype[Narwhals[Any]]rBcdSrrrs rrz_Implementation.__get__9sKN3rDataFrame[Any] | Series[Any]rdcdSrrrs rrz_Implementation.__get__;rrLazyFrame[Any]rfcdSrrrs rrz_Implementation.__get__?sQTQTrNarwhals[Any] | Nonec"||n |jjSr)rrrs rrz_Implementation.__get__As'ttX-@-PPrN)rrrArrr)rrrrrrk)rrrrrri)rrrrrrh)rrrrrra)rrrrrrj)rrrrrr`)rrrrrr)rrrrrrc)rrrrrrn)rrrrrrb)rrrrrre)rrrrrr)rrrrrrB)rrrrrrd)rrrrrrf)rrrrrr)rrrrrDr"rrrrrrs """"WWWXW WWWXW UUUXU SSSXS XUUUXU 555X5WWWXW XSSSXS SSSXS 111X1NNNXN    X TTTXTQQQQQQrrtblpa.Table | pa.RecordBatchReaderclddl}t||jr|j|S|SrW)rr,RecordBatchReaderTable from_batches)rpas rto_pyarrow_tablerEs>#r+,,*x$$S))) Jrwin32sourcerzcht|tr|ntt|Sr)r,rrrs rnormalize_pathrOs)#FC00Gvvc$v,,6G6GGrcDt|Sr)ras_posixrs rrrXsF||$$&&&rrbool | Iterable[bool]n_matchSequence[bool]cVt|tr|f|znt|S)zEnsure the given bool or sequence of bools is the correct length. Stolen from https://github.com/pola-rs/polars/blob/b8bfb07a4a37a8d449d6d1841e345817431142df/py-polars/polars/_utils/various.py#L580-L594 )r,r5r~)rrs r extend_boolr\s+",E4!8!8 JE8g  eEllJrceZdZdZddZdS) _NoDefault NO_DEFAULTrrcdS)Nz rrs rr@z_NoDefault.__repr__ls~rNrV)rrr no_defaultr@rrrrrgs/Jrr)rXrrr5)r3rrr>)rXrrr)rurrrv)r|rrr)r|rrr5)rrrr)rsrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr5)rrrr)rrrrrr)rrrrr)rrrrrrrr)rrrr)rrrr)rrrrrr)rrrrrr5)rrrur5r rrr)rrrrrr)rr#rr5)r3)r4rrr5r6rrr)r?rr@rArr5rrB)rKrLrrM)rrrrP)rrrrU)rrLrr[)rrrr_)rrrrc)rrrrg)rrrri)rrrrl)rrrprrrq)rtrurrv)rrrprrrM)rrrr)rrrrrr5rr5)rrrr5rr)rrrrrr)rrrrrr)r@rrDrrr)rrrr)rrrrrr) r+rsrryrrrrrr5)r?rrr)r?rrr5rr)rrrr)rrrrrr5)rrrr)rrrr)rrrr)rrrr)rqrrr )rqrrr)rqrrr)rrrr)rrrr)rrrrrrrr)r%r\r&rrr')rrrr)r/rrr5)rPrrJrrrQ)rorrrrrp)rsrtrru)rr{rr)rrrrrrrr)rrrrrr)rrrrrrrr)rrrr')rrzrr)rrrrrr(- __future__rrrsyscollections.abcrrrrrr datetimer enumr r functoolsr rrrimportlib.utilrinspectrr itertoolsroperatorrpathlibrsecretsrtypingrrrrrrrrr r!r"narwhals._enumr#narwhals._exceptionsr$narwhals._typing_compatr%r&narwhals.dependenciesr'r(r)r*r+r,r-r.r/r0r1r2r3r4r5r6r7r8r9narwhals.exceptionsr:r;r<r=typesr>rrr rrrtyping_extensionsr?r@rArBrCrDnarwhals._compliantrErFrG!narwhals._compliant.any_namespacerHnarwhals._compliant.typingrIrJrKrLrrNnarwhals._nativerOrPrQrRrSrTrUrVrWrXrYrZnarwhals._translater[r\r]narwhals._typingr^r_r`rarbrcrdrerfrgrhrirjrkrlrmrnrrprqrrsrrunarwhals.typingrvrwrxryrzr{r|r}r~rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr\rrrrrr rrrrrrhr0r1rUr{rrzrrprrrrrrrr version_inforrrr"r2r:r9rJrOrTrZr^rbrfrXrkrorsr|r~rrrrrrGrrrrrrobjectrrrrr]rYrnr rrrrrr$r,r.r4r6rIrTrrrzrrrrrrrrrplatformrrrrrrarrrrs*""""""" XXXXXXXXXXXXXXXX666666666666$$$$$$********                          &%%%%%::::::<<<<<<<<*[ZZZZZZZZZj0######      WVVVVVVVVVCCCCCC .-----                            ZYYYYYYYYY&87777777%%%%%%&&&&&&*%(''''WininfSk&Q RN '%..C '%..C '%..C '%3 4 4 4C #A A B B8RRRRRxRRR00000000  WT]] W\T 2 2 2 4888 J JJJJ|<<< AAAAA< <<<<      HZ(          x .         H   -----X--- JJJJJHJJJ +^X(*? 4 4 4 4 42H 4 4 4IIIIIdIIIXM%M%M%M%M%ZM%M%M%`55559)EF"F:6Z :    ).M"$9 @ D 2&&&&<QQQQ SSSS*%%%% L L L L          """ "  ... .  ((( (  ::: :    YYYYxF,0SEI SSSSSSl,,,,^%8T***JJJJJ 7""WS...  8 8 8 8<8888    &*&*&*&*R*????F:>[[[[[:>)&)&)&)&)&XLLLL9999        """"DDDDJJJJ >>>> 0000&&&&&&&R$$$$0<""""""""*    MMMM688 AAAA:::::::: 7777 ???? ???? SSSSZZZZ    888866664444, # # # # ,;;;;$R(R(R(R(R(R(R(R(j####RRRRRRRRj61111 IK++++++\ : : : : : : : : 2 1111 *4hz6J 77777x #777:3Q3Q3Q3Q3Q3Q3Q3Ql<7HHHHH''''KKKK "  4::r