hh( UddlmZddlZddlZddlZddlmZmZmZm Z m Z m Z ddl m Z ddlmZmZddlmZmZmZmZddlmZddlmZmZdd lmZdd lmZdd lm 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,dd l-m.Z.ddl/m0Z0ddl1m2Z2m3Z3ddl4m5Z5m6Z6m7Z7m8Z8m9Z9m:Z:m;Z;mZ>m?Z?m@Z@mAZAmBZBmCZCmDZDmEZEddlFmGZGmHZHmIZIe"rddlmJZJddlKmLZLddlMZNddlOZPddlQZRddlSmTZTmUZUmVZVmWZWmXZXmYZYddlZm[Z[m\Z\m]Z]m^Z^m_Z_m`Z`ddlambZbddlcmdZdmeZemfZfmgZgddlhmiZiddljmkZkmlZlmmZmmnZnmoZompZpmqZqmrZrmsZsmtZtmuZumvZvddlwmxZxmyZymzZzddl{m|Z|m}Z}m~Z~mZmZmZmZmZmZmZmZmZmZmZmZmZmZddlmZmZddlmZddlmZddlmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZeZd ed!<e)d"e*ee#ee#ee#f#Ze)d$Ze)d%Ze)d&Ze)d'd(#ZeVd)Ze)d*Ze)d+Ze)d,ZGd-d.e(ZGd/d0e(ZGd1d2e(Ze)d3Ze)d4d56Ze)d7d56Zd8Zd ed9<e)d:e#Zd;Zd ed<<d=Zd ed><Gd?d@e(eZGdAdBe(eZGdCdDe(ZGdEdFe(ZGdGdHe(ZGdIdJeee(ZGdKdLeee(ZGdMdNee(ZGdOdPeZGdQdRe.ZejdSejdTejdUejdVejdWejdWejdXejdYejdZejd[ejd\i Zd]ed^<ejd_ejd`ejdaejdbiZdcedd< edefdpdkZedqdnZӐdrdrZԐdsdtZՐdtdwZ֐dud{Zאdvd~Ze,dwdZe,dxdZe,dydZe,dzdZe,d{dZe,d|dZe,d}dZِd~dZِddZڐddZېddZ dddddZݐddZe"reed5Zn"ddlZejdkreed5ZnddZddZddZddZddZddZ dddńZ dddƄZdd̄ZddЄZdd҄ZddԄZddքZdd؄ZddڄZdd܄ZddބZddZddZddZddZdddddZddZddZddZddZddZdd ZddZddZddZeZded<ddZddZddZdd Zdd!Zdd$Zdd&Zdd)Z dd+Z dd-Z dd/Z dd1Z dd6Zdd;Zdd=Zdd?ZGd@dAZddEZGdFdGZddKZddOZddQZddRddVZGdWdXe&eZedYfdd\Zdd^ZGd_d`eeee(eZGdadbe(eZGdcddZddgZddjZ ddoZ!dS() annotationsN) Collection ContainerIterableIteratorMappingSequence)timezone)Enumauto)cache lru_cachepartialwraps) find_spec)getattr_staticgetdoc)chain) attrgetter) 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_intis_numpy_array_1dis_numpy_array_1d_intis_pandas_like_dataframeis_pandas_like_series)ColumnNotFoundErrorDuplicateErrorInvalidOperationError)Set) ModuleType) Concatenate LiteralString ParamSpecSelf TypeAliasTypeIs) CompliantExprCompliantExprTCompliantFrameTCompliantSeriesOrNativeExprT_coCompliantSeriesTNativeSeriesT_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 IntoSeriesTMultiIndexSelectorSingleIndexSelectorSizedMultiIndexSelectorSizeUnitSupportsNativeNamespaceTimeUnit_1DArray _SliceIndex _SliceName _SliceNoner@UnknownBackendNameFrameOrSeriesT)bound_T1_T2_T3_FnzCallable[..., Any]PRR1R2ceZdZUded<dS)_SupportsVersionstr __version__N__name__ __module__ __qualname____annotations__F/var/www/histauto/venv/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.dtypessc 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.series8sa 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__cs4: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-PYARROWr/PYSPARKr,POLARSr'DASKr(DUCKDBr)IBISr0SQLFRAMEr.PYSPARK_CONNECTgetUNKNOWN)rrmappings rfrom_native_namespacez$Implementation.from_native_namespacefs 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_NAMErr_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 )rrrrrs 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_polarsr6rc|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 )rrrs 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_pyarrowrDrc|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_daskr?rc|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+r6rc|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_ibis8r?rc|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_sqlframeEs~...rrc t|S)zReturns backend version.backend_versionrs rrzImplementation._backend_versionRst$$$rNrr)rrrr;rr)rrr#rrr)rrr'r(rr)rr;)rr3r)$rrrrrrrrrrrrrrrr r classmethodr"r&r+r2r5r8r:r<r>rArCrFrHrJrLrNrPrrrrrrGs"II F E DG!G! F D F DH"(O)G!EEE[E. * * *[ *   [ 5555 - - - - Z Z Z Z    " - - - - + + + + , , , , . . . . 6 6 6 6 . . . . + + + + - - - - + + + + / / / /%%%%%%rr)rV)r) ) )rW)r)irX)rVrV))rWrz(Mapping[Implementation, tuple[int, ...]] MIN_VERSIONSzdask.dataframez modin.pandasz pyspark.sqlzpyspark.sql.connectzMapping[Implementation, str]r.)maxsizer1rrr;c$ddlm}||S)Nr) import_module) importlibrf)r1rfs rr/r/ns$'''''' = % %%rimplementationrc 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 r.rrr/rPsqlframe._versionrrCrFrrJr parse_versionrbr%) rhimplr1rr  into_versionrrversion min_versionr0s rrSrSxs4 nn 5 5%^$$$///y D044T4:FFK/ <<  (    (    (d5577 ( (  ' L))Gd!33+44cDccKccZaccoo Nrargsr list[Any]ctt|dkrt|dr|dn|S)NrVr)listlen _is_iterable)rps rflattenrvs6 CIINN|DG/D/DNQ4 P PPrargcDt|ttfs|fS|Sr)r*rstuple)rws rtupleifyrzs$ cD%= ) )v JrAny | Iterable[Any]r3cddlm}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)rwrupdplr0s rrurus&&&&&&|| (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 $ $$rrn#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*rrrrrysplit)rn version_strs rrkrks](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)rr0rprqs @@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%)rr0s 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_nativelocrrtr%)rrrrrlhs_anyrhs_anyr0s rmaybe_align_indexrs<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_nativer5r6r)robj_any native_objs rmaybe_get_indexrcsR45#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 Series)rh)narwhals.translaterr r%rur5rrrrr6narwhals._pandas_like.utilsrr) rrrdf_anyrr0keysrrs @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 rr5__native_namespace___has_default_indexrrr reset_indexr6r)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)rWr[ iterablesIterable[tuple[Any, ...]]cNt|dkr t|Sddfd }dfd }t|}tt ||}t t t|tt|gR|S)NrYFrrc3KddS)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)r0rrrests rzip_tailzzip_strict..zip_tail!sU$*@C$S//),T22AAC$S//)r)rr)rtzipiterrnextrsmap)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_indexr1s c+6 7 77rnative_frame_or_seriespd.Series[Any] | pd.DataFramec|j}t||o-|jdko"|jt |ko |jdkS)NrrV)rrstartstoprtstep)rrrs rrr5sS # (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)rhr8r _compliantrrconvert_dtypesr )rrprresults rmaybe_convert_dtypesrAswB   , , . .   ##$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%)rrr0s r scale_bytesrjs ~  """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 = pd.Series(data, dtype=pd.CategoricalDtype(ordered=True)) >>> s_pl = pl.Series(data, dtype=pl.Categorical(ordering="lexical")) Let's define a library-agnostic function: >>> @nw.narwhalify ... def func(s): ... return nw.is_ordered_categorical(s) Then, we can pass any supported library to `func`: >>> func(s_pd) True >>> func(s_pl) False r)InterchangeSeriesF is_orderedT)rV zpl.Categoricalphysical) is_dictionary)narwhals._interchange.seriesr rrrr*dtype Categoricalrdescribe_categoricalr rrhr<rr orderingr8r3catorderedrHnarwhals._arrow.utilsr$r)rr rrr rrlr$s ris_ordered_categoricalr-sqN?>>>>>  % . 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)r/rr1)r#generate_temporary_column_name)r/rr1r0s rgenerate_unique_tokenr5s7 ?cH5555 )'7SY Z Z ZZrcd} |t|dz }||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 rTrVdzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in )rr-)r/rr1countertokenr0s rr4r4s<G &39Wq[1133   L1  S==333)033 !%% % &rframesubset Iterable[str]r list[str]c|s4tt|j|St|}t ||jx}r||S)N) available)rssetr intersectioncheck_columns_exist)r:r;rto_droperrors rparse_columns_to_droprEsc =C &&33F;;<<<6llG#Gu}EEEEu NrsequenceSequence[_T] | AnyTypeIs[Sequence[_T]]cXt|tot|t Sr)r*r r)rFs ris_sequence_but_not_strrJs$ h ) ) K*Xs2K2K.KKrTypeIs[_SliceNone]cRt|to|tdkSr)r*slicers r is_slice_nonerO s" c5 ! ! 8cU4[[&88rCTypeIs[SizedMultiIndexSelector[Series[Any] | CompliantSeries[Any]]]ct|o@t|dkrt|dtpt|dkp,t |pt |pt |SNr)rJrtr*rr4r2is_compliant_series_intrNs ris_sized_multi_index_selectorrTs $C ( ( Pc((Q,::c!fc#:#:NCA  ( ! % %  ( "# & &  ( #3 ' 'r-TypeIs[Sequence[_T] | Series[Any] | _1DArray]czt|p,t|pt|pt|Sr)rJr3r1is_compliant_seriesrNs ris_sequence_likerXsF $$ $ S ! ! $ c " " $ s # # rTypeIs[_SliceIndex]ct|to_t|jtpEt|jtp+t|jto|jduo|jduSr)r*rMrrrrrNs ris_slice_indexr[)sj c5 ! ! 39c"" R ch $ $ R sx % % P#)t*; PD@Pr TypeIs[range]c,t|tSr)r*rangerNs ris_ranger_1s c5 ! !!rTypeIs[SingleIndexSelector]crtt|tot|t Sr)r3r*rrNs ris_single_index_selectorrb5s,  3$$BZT-B-B)B C CCrTTypeIs[SingleIndexSelector | MultiIndexSelector[Series[Any] | CompliantSeries[Any]]]c\t|pt|pt|Sr)rbrTr[rNs ris_index_selectorre9s4 !%%  ( - -  #  rtpTypeIs[list[_T]]cvtt|to|ot|d|SrR)r3r*rs)rrfs r is_list_ofriCs2  3%%H#H*SVR2H2H I IIr predicatesCollection[Any]TypeIs[Collection[list[bool]]]c4td|DS)Nc3@K|]}t|tVdSr)rir3)rpreds rrz3predicates_contains_list_of_bool..Ks,==$z$%%======rany)rjs r predicates_contains_list_of_boolrrHs! ==*=== = ==rctt|o.tt|dx}ot ||Sr)r3rJrrr*)rrfrs ris_sequence_ofrtNsN $$ "499d++ +U " ub ! !  r bool | Nonerpass_through_defaultcP|||}n||| }n||nd}t||S)Nz,Cannot pass both `strict` and `pass_through`r)rrrvr0s rvalidate_strict_and_pass_thoughrxWsM ~,.+   4!z L4 <oo rrF) warn_versionrequiredryrz*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) NrpP.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. r3z0Can't pass both `native_namespace` and `backend`z `backend` must be specified in `z`.)popr#r%r)rprr'rr0r}rzrys rwrapperz=deprecate_native_namespace..decorate..wrapperwshhy$//G#xx(:DAA +Jj .cLIIII*!-'2EH oo%!)go(oHHHH oo%%DO2t$t$$ $r)rprrrrr)r)r}rrzrys` rdecoratez,deprecate_native_namespace..decoratevsC r % % % % % % %  %*r)r}r~rr~r)ryrzrs`` rdeprecate_native_namespaceris.2 Or window_size min_samples int | Nonetuple[int, int]ct|tdt|ttdd|dkrd}t||/|dkrd}t|||krd}t |n|}||fS)Nr param_namerrVz+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%r9)rrr0s 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)rt)rlines rrz generate_repr..s(>>3t99>>>>>>rrYu┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorrgetenv expandtabs splitlinesmaxrt) 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:)rtr@ collectionsrrjoinr8)rrr8 duplicatesr0s 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*rr@r )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 rr}z$passthrough_column_names..fns r)rrrrr)rr}s` rpassthrough_column_namesrs( Irr _SENTINELattrc<t||ttuSr)rr)rrs r_hasattr_staticrs #tY / /y @@r\CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co] | Any^TypeIs[CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co]]c"t|dS)N__narwhals_dataframe__rrNs ris_compliant_dataframers 3 8 9 99rJCompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co] | AnyLTypeIs[CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co]]c"t|dS)N__narwhals_lazyframe__rrNs ris_compliant_lazyframer s 3 8 9 99r'CompliantSeries[NativeSeriesT_co] | Any)TypeIs[CompliantSeries[NativeSeriesT_co]]c"t|dS)N__narwhals_series__rrNs rrWrW&s 3 5 6 66rcRt|o|jSr)rWr& is_integerrNs rrSrS,s% s # # > (<(<(>(>>rECompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co] | AnyGTypeIs[CompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co]]c"t|dS)N__narwhals_expr__)hasattrrNs ris_compliant_exprr2s 3+ , ,,r'TypeIs[NamespaceAccessor[_FullContext]]cBt|dot|dS)Nr _accessorrrNs r_is_namespace_accessorr8s# 3 , , Rk1R1RRrrlTypeIs[_EagerAllowedImpl]cx|tjtjtjtjtjhvS)z.Return True if `impl` allows eager operations.)rrrrrrrls ris_eager_allowedrBs2   rTypeIs[_LazyFrameCollectImpl]cL|tjtjtjhvS)z4Return True if `LazyFrame.collect(impl)` is allowed.)rrrrrs rcan_lazyframe_collectrMs N)>+@.BXY YYrTypeIs[_LazyAllowedImpl]c|tjtjtjtjtjtjtjhvS)z1Return True if `DataFrame.lazy(impl)` is allowed.)rrrrrrrrrs ris_lazy_allowedr Rs> & rTypeIs[SupportsNativeNamespace]c"t|dS)NrrrNs rhas_native_namespacer _s 3 6 7 77rTypeIs[ArrowStreamExportable]c"t|dS)N__arrow_c_stream__rrNs rsupports_arrow_c_streamrcs 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..wsL8;C7NN3r)dictr)rrrright_keys_suffixeds` ` r_remap_full_join_keysrgsM ?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)rzB'pyarrow>=14.0.0' is required for `from_arrow` for object of type r) rrrr+r _dataframe from_arrowrr~ModuleNotFoundError)rrrr0s r_into_arrow_tabler"}swA   ' 4 4Y ? ? I}''b'99@@ mObcgOhOh m m mC c " ""rr}c|S)aVisual-only marker for unstable functionality. Arguments: fn: Function to decorate. Returns: Decorated function (unchanged). Examples: >>> from narwhals._utils import unstable >>> @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)r}s 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%zZrp)r%s`r_is_naive_formatr*s,::::(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: >>> from narwhals._utils import not_implemented >>> 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)rr-s 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)rr4r0r5rrr7s r __set_name__znot_implemented.__set_name__s %+- rr_T | Literal['raise'] | Nonetype[_T] | Nonercd||St|d|j}t|j|dS)Nr)rr4_raise_not_implemented_errorr5)rrrwhos rrznot_implemented.__get__s?  Kh 143CDD$TZ555trrprc,|dS)Nraise)r)rrprs r__call__znot_implemented.__call__s||G$$$rmessager=r?cF|}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%)rrCrs rr%znot_implemented.deprecateds'cee"z'""3'''rr)r-r.rrrT)rrr7rrr)rr;rr<rr)rprrrrr)rCr=rr?) rrrrr1r6r:rrBrUr%rrrr,r,s""H((((( KKKK.... PT     %%%%  ( ( ([ ( ( (rr,whatr?NotImplementedErrorc0|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)rF)rEr?r0s rr>r>s:  S SC S S S c " ""rceZdZUdZded<ded<ded< eddd ZeddZddZ d dZ d!dZ d"dZ dS)#requiresa#Method decorator for raising under certain constraints. Attributes: _min_version: Minimum backend version. _hint: Optional suggested alternative. Examples: >>> from narwhals._utils import requires, Implementation >>> 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_namerhintminimumrr?cL||}||_||_|S)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. )__new__rJrK)rrNrMrs rrSzrequires.backend_version0s)kk#"  rrSc@dd|DS)Nrc3K|]}|VdSrr)rds rrz,requires._unparse_version..?s$8811888888r)rrRs r_unparse_versionzrequires._unparse_version=s#xx88888888rr1rIrc>d|jvr|d|j|_dSdSNr)rL)rr1s r_qualify_accessor_namezrequires._qualify_accessor_nameAs7 d( ( ($*!A!AT-?!A!AD    ) (rrrtuple[tuple[int, ...], str]ct|r"||j|j}n|}|jt |jfSr)rrWrrrrr)rrrs r_unwrap_contextzrequires._unwrap_contextFsQ !( + + !  ' '(: ; ; ; *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 )rZrJrTrLrKrF)rrrnr'rNfoundr0s r_ensure_versionzrequires._ensure_versionNs//99 d' ' ' F''(9::%%g..m$$mmgmmmmchmmm : )((DJ((C!#&&&rr}_Method[_IntoContextT, P, R]cZj_td fd }|S) NrrrprrrrrcF||g|Ri|Sr)r_)rrprr}rs rrz"requires.__call__..wrapper^s7   * * *2h...... .r)rrrprrrrr)rrLr)rr}rs`` rrBzrequires.__call__YsJ [ r / / / / / /  / rN)r)rMrrNrrr?)rSrrr)r1rIrr)rrrrX)rrrr)r}r`rr`) rrrrrrUrS staticmethodrTrWrZr_rBrrrrIrIs,"!!!JJJ     [ 999\9BBBB JJJJ ' ' ' '      rrI str_slicer"tuple[int | None, int | None, Any]c|j||jnd}|j||jdznd}|j}|||fS)NrV)rrrr)rdrrrrs rconvert_str_slice_to_int_slicerggs\/8o.IGMM)/ * * *tE090J7== ( (1 , ,PTD >D 4 r tp_parentCallable[P, R1].decorate}s  * , ,DOOT1R1R ,!' !2!2J   %% % %!. % %  % % nnr)rlrmrrmr)rhrs` rrorops(       Orobject | type[Any]ct|tr|nt|}|jdkr|jnd}|d|jdS)Nbuiltinsrr)r*rrrlstrip)rrfmodules rr~r~s[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: >>> from narwhals._utils import ensure_type >>> 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.core.frame.DataFrame', got: 'polars.dataframe.frame.DataFrame' df=polars.dataframe.frame.DataFrame(...) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ z | c34K|]}t|VdSr)r~)rrfs rrzensure_type..s+LL"1"55LLLLLLrz Expected z, got: z (z(...)=r^r]N)r*rr~reprrtr) rrrutp_namesr0left_padrassign underlines rrrsB 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 rr1z_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*ry)rits rto_tuplez_DeferredIterable.to_tuples0 __  E**9rrb 9rN)rrrr)rr)rr)rrrrr1rrrrrrrsZVV@@@@%%%%::::::rr@nestedattrgetter[Any]cZ|rd|g|Rn|}t|SrV)rr)rrr7s 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 rr zNarwhals._compliants363rN)rr)rrrrrr rrrrrs20666X666rrceZdZdZd;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) rrvr7rrrc||_dSr)rr9s rr:z_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__rrNarwhals[NativeIbis]recdSrrrs rrz_Implementation.__get__rr.Narwhals[NativePySpark | NativePySparkConnect]"_PySparkImpl | _PySparkConnectImplcdSrrrs rrz_Implementation.__get__!s .1Srtype[Narwhals[Any]]r?cdSrrrs rrz_Implementation.__get__&sKN3rDataFrame[Any] | Series[Any]rdcdSrrrs rrz_Implementation.__get__(rrLazyFrame[Any]rfcdSrrrs rrz_Implementation.__get__,sQTQTrNarwhals[Any] | Nonec"||n |jjSr)r rrs rrz_Implementation.__get__.s'ttX-@-PPrN)rrvr7rrr)rrrrrrk)rrrrrri)rrrrrrh)rrrrrra)rrrrrrj)rrrrrr`)rrrrrr)rrrrrrc)rrrrrrn)rrrrrrb)rrrrrre)rrrrrr)rrrrrr?)rrrrrrd)rrrrrrf)rrrrrr)rrrrr:r!rrrrrrs """"WWWXW WWWXW UUUXU SSSXS XUUUXU 555X5WWWXW XSSSXS SSSXS 111X1NNNXN    X TTTXTQQQQQQrrtblpa.Table | pa.RecordBatchReaderclddl}t||jr|j|S|SrR)rr*RecordBatchReaderTable from_batches)rpas rto_pyarrow_tabler2s>#r+,,*x$$S))) Jrsourcerzclt|tr|Sddlm}t||S)Nr)Path)r*rpathlibr)rrs rnormalize_pathr:sA&#  ttF||  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*r3ry)rrs r extend_boolrBs+",E4!8!8 JE8g  eEllJr)r1rrr;)rhrrr)rprrrq)rwrrr)rwr{rr3)rrrr)rnrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr3)rrrr)rrrrrr)rrrrr)rrrrrrrr)rrrr)rrrr)rrrrrr)rrrrrr3)rrrpr3rr rr)rrrrrr)rrrr3)r.)r/rrr0r1rrr)r:rr;r<rr3rr=)rFrGrrH)rrrrK)rrrrP)rrGrrU)rrrrY)rrrr\)rrrr`)rrrrc)rrrfrrrg)rjrkrrl)rrrfrrrH)rrurrurvr3rr3)ryrrzr3rr{)rrrrrr)rrrrrr)r;rr?rrr)rrrr)rrrrrr) r&rsrryrrrrrr3)r:rrr)r:rrr0rr)rrrr)rrrrrr3)rrrr)rrrr)rrrr)rrrr)rrrr)rlrrr)rlrrr)rlrrr)rrrr )rrrr )rrrrrrrr)rr\rrrr)r}rrr)r%rrr3)rErr?rrrF)rdrrrrre)rhrirrj)rrprr)rrrurvrrrr)rrrrrr)rrrrrrrr)rrrr)rrzrr)rrrrrr(" __future__rrrsyscollections.abcrrrrrr datetimer enumr r functoolsr rrrimportlib.utilrinspectrr itertoolsroperatorrsecretsrtypingrrrrrrrrrr r!narwhals._enumr"narwhals._exceptionsr#narwhals._typing_compatr$r%narwhals.dependenciesr&r'r(r)r*r+r,r-r.r/r0r1r2r3r4r5r6narwhals.exceptionsr7r8r9r:typesr;rrrrrrtyping_extensionsr<r=r>r?r@rAnarwhals._compliantrBrCrDrErFrG!narwhals._compliant.any_namespacerHnarwhals._compliant.typingrIrJrKrLrrNnarwhals._nativerOrPrQrRrSrTrUrVrWrXrYrZnarwhals._translater[r\r]narwhals._typingr^r_r`rarbrcrdrerfrgrhrirjrkrlrmrnrrprqrrsrrunarwhals.typingrvrwrxryrzr{r|r}r~rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrbr.r/rSrvrzrurrkrrrrrrrr version_inforrrrr-r5r4rErJrOrTrXr[r_rbrerirrrtrxrrrrBrrrrrrobjectrrrrrWrSrrrrr r rrr"r$r*r,r>rIrgror~rrrrrrrrrrrrrrs""""""" XXXXXXXXXXXXXXXX666666666666$$$$$$********                          &%%%%%::::::<<<<<<<<&[ZZZZZZZZZo0######      DCCCCC .-----                            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%b9)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*CCCCN:>[[[[[:>*&*&*&*&*&ZLLLL9999    """"DDDDJJJJ >>>> &&&&&&&R$$$$0<""""""""*    MMMM688 AAAA:::::::: 7777 ???? ---- SSSSZZZZ    888866664444, # # # # .;;;;$O(O(O(O(O(O(O(O(d####SSSSSSSSl61111 IK,,,,,,^ : : : : : : : : 2 1111 *4hz6J 77777x #777:3Q3Q3Q3Q3Q3Q3Q3QlKKKKKKr