ctjx UddlmZddlZddlZddlZddlmZmZmZm Z m Z m Z m Z ddl mZddlmZmZddlmZmZmZddlmZddlmZmZdd lmZdd lmZdd lm Z dd l!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*dd l+m,Z,ddl-m.Z.ddl/m0Z0m1Z1ddl2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8m9Z9m:Z:m;Z;mZ>m?Z?m@Z@mAZAmBZBmCZCmDZDmEZEddlFmGZGmHZHmIZImJZJe"rddlmKZKddlLmMZMddl!mNZNmOZOddlPZQddlRZSddlTZUddlVmWZWmXZXmYZYmZZZddl[m\Z\m]Z]m^Z^ddl_m`Z`ddlambZbmcZcmdZdmeZeddlfmgZgddlhmiZimjZjmkZkmlZlmmZmmnZnmoZompZpmqZqmrZrmsZsmtZtddlumvZvmwZwmxZxddlymzZzm{Z{m|Z|m}Z}m~Z~mZmZmZmZmZmZmZmZmZmZmZmZddlmZmZddlmZddlmZdd lmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZeZd!ed"<e(d#ee#ee#zee#z$Ze(d%Ze(d&Ze(d'Ze(d(d)$ZeXd*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'ZGdPdQeZGdRdSe,ZĐdydWZejdXejdYejdZejd[ejd\ejd\ejd]ejd^ejd_ejd`ejdai Zdbedc<ejddejdeejdfejdgiZdhedi< edjkdzdoZed{dqZԐd|duZՐd}dwZ֐d~dyZאdd}ZؐddZe*ddZe*ddZe*ddZe*ddZe*ddZe*ddZe*ddZڐddZڐddZېddZܐddZ dddddZސddZߐddZddZddZddZddZ ddd„Z dddÄZddɄZdd̈́ZddτZddфZddӄZddՄZddׄZddلZddۄZdd݄ZddZddZddZddZddZdddddZddZddZddZddZddZdd ZddZddZddZddZeZded<ddZdd!Zdd$Zdd'Zdd(Zdd)Zdd+Z dd.Z dd0Z dd2Z dd4Z dd6Zdd;Zdd@ZddBZddDZGdEdFZddJZGdKdLZddPZddTZddVZddWdd[ZGd\d]e%eZed^kdÐdaZdĐdcZGdddeeeee'eZGdfdge'eZGdhdiZdŐdlZ ej!dmkrdƐdpZ"ndƐdqZ"dǐdvZ#GdwdxeZ$e$j%Z&e&Z%e'dZ(dS() annotationsN)Callable Collection ContainerIterableIteratorMappingSequence)timezone)Enumauto)cache lru_cachewraps) find_spec)getattr_staticgetdoc) attrgetter)Path) token_hex) TYPE_CHECKINGAnyFinalGenericLiteralProtocolTypeVarcastoverload) 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 ShapeError)Set) ModuleType) Concatenate TypeAlias) LiteralString ParamSpecSelfTypeIs)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 _SliceNoner>UnknownBackendNameFrameOrSeriesT)bound_T1_T2_T3_FnzCallable[..., Any]PRR1R2ceZdZUded<dS)_SupportsVersionstr __version__N__name__ __module__ __qualname____annotations__M/var/www/html/CA-Chatbot/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)NrrK)rV1narwhals.stable.v1._namespacerLV2narwhals.stable.v2._namespacenarwhals._namespace)r NamespaceV1 NamespaceV2rLs r namespacezVersion.namespacesd 7:   N N N N N N  7:   N N N N N N 111111rrwcj|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)rn)rrrrnrrnarwhals.dataframe)r DataFrameV1 DataFrameV2rns 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)ro)rrrrorrr)r LazyFrameV1 LazyFrameV2ros r lazyframezVersion.lazyframe,rrtype[Series[Any]]cj|tjurddlm}|S|tjurddlm}|Sddlm}|S)Nrrr)rrrrsrrnarwhals.series)rSeriesV1SeriesV2rss rserieszVersion.series:sa 7:   = = = = = =O 7:   = = = = = =O****** rN)rr)rrw)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__es4: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'IBISr.SQLFRAMEr,PYSPARK_CONNECTgetUNKNOWN)rrmappings rfrom_native_namespacez$Implementation.from_native_namespacehs 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_stringsA *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_dask r?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_ibis:r?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_sqlframeGs~...rrc t|S)zReturns backend version.backend_versionrs rrzImplementation._backend_versionTst$$$rNrr)rrrr<rr)rrr#rrr)rrr'r(rr)rr<)rr3r)$rrrrrrrrrrrrrrrr r classmethodr"r&r+r2r5r8r:r<r>rArCrFrHrJrLrNrPrrrrrrIs"II F E DG!G! F D F DH"(O)G!EEE[E. * * *[ *   [ 5555 - - - - Z Z Z Z    " - - - - + + + + , , , , . . . . 6 6 6 6 . . . . + + + + - - - - + + + + / / / /%%%%%%rrimplementationrr3c|p|o|dkS)zJWhether implementation is PySpark (or PySpark Connect) with version < 4.0.)r)rCrFrrVs ris_pyspark_pre_4rZYsB !!##J~'H'H'J'J 5  ) ) + +f 45r)rX)rr) ) )r\)rrX)i)r[r[))r\r]rz(Mapping[Implementation, tuple[int, ...]] MIN_VERSIONSzdask.dataframez modin.pandasz pyspark.sqlzpyspark.sql.connectzMapping[Implementation, str]r.)maxsizer1rr<c$ddlm}||S)Nr) import_module) importlibri)r1ris rr/r/ws$'''''' = % %%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 r.rrr/rPsqlframe._versionrrCrFrrJr parse_versionrer%) rVimplr1rr  into_versionrrversion min_versionr0s rrSrSs4 nn 5 5%^$$$///y D044T4:FFK/ <<  (    (    (d5577 ( (  ' L))Gd!33+44cDccKccZaccoo Nrargsr list[Any]ctt|dkrt|dr|dn|S)Nr[r)listlen _is_iterable)rrs rflattenrxs6 CIINN|DG/D/DNQ4 P PPrargcDt|ttfs|fS|Sr)r*rutuple)rys rtupleifyr|s$ cD%= ) )v JrAny | Iterable[Any]cddlm}tx}t||j|jfs8t x}Jt||j|j|j|jfr"dt|d}t|t|tot|tt|f S)Nrrrz(Expected Narwhals class or scalar, got: z`. Hint: Perhaps you - forgot a `nw.from_native` somewhere? - used `pl.col` instead of `nw.col`?) rrsr)r*rnr*Exprroqualified_type_name TypeErrorrrbytes)ryrspdplr0s rrwrws&&&&&&|| (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 $ $$rrp#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)rp version_strs rrmrms](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)Nrrp)narwhals.dtypesrqr*r issubclass)rrrqs rrrsi%%%%%%*e$$4*l333 j, / / :t$$MJ )M)Mritems Iterable[Any]rcddlmmtfd|Dstfd|DrdSdd|D}t |)Nrrmc38K|]}t|VdSrr*)ritemrns rrz$validate_laziness..s- 9 94:dI & & 9 9 9 9 9 9rc38K|]}t|VdSrr)rrros 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)rrnroallr)rr0rnros @@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_index1s' ";CS// ! " "r_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )rrrr)narwhals._pandas_like.dataframernarwhals._pandas_like.seriesrrr*getattrrrr_with_compliant _with_nativelocrrvr%)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_indexrlsR45#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 SeriesrY)narwhals.translaterrr%rwr5rrrrr6narwhals._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) rrr5__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    NrrTypeIs[pd.RangeIndex]c,t||jSr)r* RangeIndex)rrs r_is_range_indexrs c+6 7 77rnative_frame_or_seriespd.Series[Any] | pd.DataFramec|j}t||o-|jdko"|jt |ko |jdkS)Nrr[)rrstartstoprvstep)rrrs rrrsS # (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)rVr8r _compliantrrconvert_dtypesr)rrrrresults rmaybe_convert_dtypesr"swB   , , . .   ##$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_bytesr Ks ~  """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.seriesrrrrr*dtype Categoricalrdescribe_categoricalr rrVr<rrorderingr8r3catorderedrHnarwhals._arrow.utilsrr)rrrrrrrnrs ris_ordered_categoricalr`sqF?>>>>>  % . 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)rrr!)r!generate_temporary_column_name)rrr!r0s 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-)rrr!countertokenr0s rr$r$s<G &8 'A+ 6 688 8E H HL1  S==333)033 !%% % &rframesubset Iterable[str]strict list[str]c|s4tt|j|St|}t ||jx}r||S)N) available)rusetr intersectioncheck_columns_exist)r*r+r-to_droperrors rparse_columns_to_dropr6sc =C &&33F;;<<<6llG#Gu}EEEEu NrsequenceSequence[_T] | AnyTypeIs[Sequence[_T]]cXt|tot|t Sr)r*r r)r7s ris_sequence_but_not_strr;s$ h ) ) K*Xs2K2K.KKrTypeIs[_SliceNone]cRt|to|tdkSr)r*slicers r is_slice_noner@s" c5 ! ! 8cU4[[&88rCTypeIs[SizedMultiIndexSelector[Series[Any] | CompliantSeries[Any]]]ct|o:t|dkrt|dpt|dkp,t|pt |pt |SNr)r;rvis_single_index_selectorr4r1is_compliant_series_intr?s ris_sized_multi_index_selectorrFs $C ( ( Yc((Q,C#;CF#C#CWSUV ( ! % %  ( "# & &  ( #3 ' 'r-TypeIs[Sequence[_T] | Series[Any] | _1DArray]czt|p,t|pt|pt|Sr)r;r2r/is_compliant_seriesr?s ris_sequence_likerJsF $$ $ S ! ! $ c " " $ s # # rTypeIs[_SliceIndex]ct|toft|jtpLt|jtp2t|jtt fo|jduo|jduSr)r*r>rrrrNoneTyper?s ris_slice_indexrNst c5 ! ! 39c"" ch $ $  sx#x 1 1 ! T! !D r TypeIs[range]c,t|tSr)r*ranger?s ris_rangerRs c5 ! !!rTypeIs[SingleIndexSelector]crtt|tot|t Sr)r3r*rr?s rrDrDs,  3$$BZT-B-B)B C CCrTTypeIs[SingleIndexSelector | MultiIndexSelector[Series[Any] | CompliantSeries[Any]]]c\t|pt|pt|Sr)rDrFrNr?s ris_index_selectorrWs4 !%%  ( - -  #  rBTypeIs[SizedMultiBoolSelector[Series[Any] | CompliantSeries[Any]]]ct|r.t|dkrt|dtp,t |pt |pt |SrC)r;rvr*r3r3r0is_compliant_series_boolr?s ris_boolean_selectorr[#sh ! % % U3s88a<+TJs1vt.6s,==$z$%%======rany)r`s r predicates_contains_list_of_boolrh3s! ==*=== = ==rctt|o.tt|dx}ot ||Sr)r3r;nextiterr*)rr\firsts ris_sequence_ofrm9sN $$ "499d++ +U " ub ! !  rTypeIs[NestedLiteral]cFt|tttfSr)r*rur{dictr?s ris_nested_literalrqBs cD%. / //r bool | Nonerpass_through_defaultcP|||}n||| }n||nd}t||S)Nz,Cannot pass both `strict` and `pass_through`r )r-rrsr0s rvalidate_strict_and_pass_thoughruFsM ~,.+   4!z L4 <oo rrF) warn_versionrequiredrvrw*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) NrrP.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. r#z0Can't pass both `native_namespace` and `backend`z `backend` must be specified in `z`.)popr!r%r)rrr~r'rr0rzrwrvs rwrapperz=deprecate_native_namespace..decorate..wrapperfshhy$//G#xx(:DAA +Jj .cLIIII*!-'2EH oo%!)go(oHHHH oo%%DO2t$t$$ $r)rrr}r~rrr)r)rzrrwrvs` rdecoratez,deprecate_native_namespace..decorateesC r % % % % % % %  %*r)rzr{rr{r)rvrwrs`` rdeprecate_native_namespacerXs.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%r9)rrr0s r_validate_rolling_argumentsrs S];;;; S$t**GGGGQ;oo ???CS// !  $ $JC',, , %"  ##rnfraction float | Noneheightwith_replacementc||d}t|||}n|t||z}nd}|dkrd|}t|||kr|sd}t||S)aResolve the concrete number of rows to draw for `DataFrame.sample`/`Series.sample`. At most one of `n` or `fraction` may be set; if neither is given a single row is sampled. `fraction` is interpreted relative to `height` and truncated towards zero. Raises: ValueError: If both `n` and `fraction` are specified. InvalidOperationError: If the resolved size is negative. ShapeError: If the resolved size exceeds `height` and `with_replacement` is False. Nz&cannot specify both `n` and `fraction`r[rz.sample size must be a positive integer, found zScannot take a larger sample than the total population when `with_replacement=false`)r%rr9r:)rrrrr0sizes r_resolve_sample_sizers }-6oo}  6H$%% axxEtEE#C((( f}}-}coo Krheader 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)rv)rlines rrz generate_repr..s(>>3t99>>>>>>ru┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorrgetenv expandtabs splitlinesmaxrv) 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:)rvr1 collectionsrrjoinr8)rrr( 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*rr1r )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 !!rrrqrrwr Set[TimeUnit]rSet[str | None]cjt||jo|j|vo|j|vp d|vo|jduS)N*)r*Datetimerr)rrrrs 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 rrzz$passthrough_column_names..fns r)rrrrr)rrzs` 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__rr?s ris_compliant_dataframer$s 3 8 9 99rJCompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co] | AnyLTypeIs[CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co]]c"t|dS)N__narwhals_lazyframe__rr?s ris_compliant_lazyframer/s 3 8 9 99r'CompliantSeries[NativeSeriesT_co] | Any)TypeIs[CompliantSeries[NativeSeriesT_co]]c"t|dS)N__narwhals_series__rr?s rrIrI5s 3 5 6 66rcRt|o|jSr)rIr is_integerr?s rrErE;% s # # > (<(<(>(>>rcRt|o|jSr)rIr is_booleanr?s rrZrZArr'TypeIs[NamespaceAccessor[_FullContext]]cBt|dot|dS)Nr _accessorrr?s r_is_namespace_accessorrGs# 3 , , Rk1R1RRrrnTypeIs[_EagerAllowedImpl]cx|tjtjtjtjtjhvS)z.Return True if `impl` allows eager operations.)rrrrrrrns ris_eager_allowedrQs2   rTypeIs[_LazyFrameCollectImpl]cL|tjtjtjhvS)z4Return True if `LazyFrame.collect(impl)` is allowed.)rrrrrs rcan_lazyframe_collectr \s N)>+@.BXY YYrTypeIs[_LazyAllowedImpl]c|tjtjtjtjtjtjtjhvS)z1Return True if `DataFrame.lazy(impl)` is allowed.)rrrrrrrrrs ris_lazy_allowedr as> & rTypeIs[SupportsNativeNamespace]c"t|dS)Nrrr?s rhas_native_namespacerns 3 6 7 77rTypeIs[ArrowStreamExportable]c"t|dS)N__arrow_c_stream__rr?s rsupports_arrow_c_streamrrs 3 4 5 55rleft_onright_onsuffixdict[str, str]cbfd|D}tt||dS)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;C7NN3rF)r-)rpzip)rrrright_keys_suffixeds` ` r_remap_full_join_keysrvsR ?G H1%@@@ A AArdatarZcontextpa.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_arrowrrModuleNotFoundError)rrrr0s r_into_arrow_tabler%swA   ' 4 4Y ? ? I}''b'99@@ mObcgOhOh m m mC c " ""rrzc|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)rzs 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%zZrf)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: >>> 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)rr0s 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)rr7r3r8rrr:s 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 reprr7_raise_not_implemented_errorr8)rrrrVwhos rrznot_implemented.__get__sd  K!+TUU !7 7 7~&&CC"C$TZ555trrrr~c,|dS)Nraise)r)rrrr~s r__call__znot_implemented.__call__s||G$$$rmessager?rAcF|}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#)rrGrs rr#znot_implemented.deprecated s'cee"z'""3'''rr)r0r1rrrT)rrr:rrr)rr>rr?rr)rrrr~rrr)rGr?rrA) rrrrr4r9r=rrFrUr#rrrr/r/s!!F((((( KKKK.... PT$%%%%  ( ( ([ ( ( (rr/whatrCNotImplementedErrorc0|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)rJ)rIrCr0s rrBrBs:  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_namerhintminimumrrAcL||}||_||_|S)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. )__new__rNrO)rrRrQrs rrSzrequires.backend_version@s)kk#"  rrSc@dd|DS)Nrc3K|]}|VdSrr)rds rrz,requires._unparse_version..Os$8811888888r)rrRs r_unparse_versionzrequires._unparse_versionMs#xx88888888rr!rGrc>d|jvr|d|j|_dSdSNr)rP)rr!s r_qualify_accessor_namezrequires._qualify_accessor_nameQs7 d( ( ($*!A!AT-?!A!AD    ) (rrrtuple[tuple[int, ...], str]ct|r"||j|j}n|}|jt |jfSr)rr[rrrrr)rrrs r_unwrap_contextzrequires._unwrap_contextVsQ !( + + !  ' '(: ; ; ; *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 )r^rNrXrPrOrJ)rrrpr'rRfoundr0s r_ensure_versionzrequires._ensure_version^s//99 d' ' ' F''(9::%%g..m$$mmgmmmmchmmm : )((DJ((C!#&&&rrz_Method[_IntoContextT, P, R]cZj_td fd }|S) Nrrrrr}r~rrrcF||g|Ri|Sr)rc)rrrr~rzrs rrz"requires.__call__..wrapperns7   * * *2h...... .r)rrrrr}r~rrr)rrPr)rrzrs`` rrFzrequires.__call__isJ [ r / / / / / /  / rN)r)rQrrRrrrA)rSrrr)r!rGrr)rrrr\)rrrr)rzrdrrd) rrrrrrUrS staticmethodrXr[r^rcrFrrrrMrM"s*"!!!JJJ     [ 999\9BBBB JJJJ ' ' ' '      rrM str_slicer"tuple[int | None, int | None, Any]c|j||jnd}|j||jdznd}|j}|||fS)Nr[)rrrr)rhrrrrs rconvert_str_slice_to_int_slicerkws\/8o.IGMM)/ * * *tE090J7== ( (1 , ,PTD >D 4 r tp_parentCallable[P, R1].decorates  * , ,DOOT1R1R ,!' !2!2J   %% % %!. % %  % % nnr)rprqrrqr)rlrs` rrsrss(       Orobject | type[Any]ct|tr|nt|}|jdkr|jnd}|d|jdS)Nbuiltinsrr)r*rrrlstrip)rr\modules 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)rr\s rrzensure_type..s+LL"1"55LLLLLLrz Expected z, got: z (z(...)=r^raN)r*rrrArvr) rrrytp_namesr0left_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 rr4z_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)rrrrr4rrrrrrrsZVV@@@@%%%%::::::rr@nestedattrgetter[Any]cZ|rd|g|Rn|}t|SrZ)rr)rrr:s 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._compliants363rN)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) rrzr:rrrc||_dSr)rr<s rr=z_Implementation.__set_name__s ! rrNarwhals[NativePolars]rricdSrrrs rrz_Implementation.__get__TWTWrNarwhals[NativePandas]rgcdSrrrs rrz_Implementation.__get__rrNarwhals[NativeModin]rfcdSrrrs rrz_Implementation.__get__RURUrNarwhals[NativeCuDF]r_cdSrrrs rrz_Implementation.__get__PSPSrNarwhals[NativePandasLike]rhcdSrrrs rrz_Implementation.__get__s #rNarwhals[NativeArrow]r^cdSrrrs rrz_Implementation.__get__ rr3Narwhals[NativePolars | NativeArrow | NativePandas]&_PolarsImpl | _PandasImpl | _ArrowImplcdSrrrs rrz_Implementation.__get__"s 25rNarwhals[NativeDuckDB]racdSrrrs rrz_Implementation.__get__&rrNarwhals[NativeSQLFrame]rlcdSrrrs rrz_Implementation.__get__(s rNarwhals[NativeDask]r`cdSrrrs rrz_Implementation.__get__,rrNarwhals[NativeIbis]rccdSrrrs rrz_Implementation.__get__.rr.Narwhals[NativePySpark | NativePySparkConnect]"_PySparkImpl | _PySparkConnectImplcdSrrrs rrz_Implementation.__get__0s .1Srtype[Narwhals[Any]]rAcdSrrrs rrz_Implementation.__get__5sKN3rDataFrame[Any] | Series[Any]rbcdSrrrs rrz_Implementation.__get__7rrLazyFrame[Any]rdcdSrrrs rrz_Implementation.__get__;sQTQTrNarwhals[Any] | Nonec"||n |jjSr)rrrs rrz_Implementation.__get__=s'ttX-@-PPrN)rrzr:rrr)rrrrrri)rrrrrrg)rrrrrrf)rrrrrr_)rrrrrrh)rrrrrr^)rrrrrr)rrrrrra)rrrrrrl)rrrrrr`)rrrrrrc)rrrrrr)rrrrrrA)rrrrrrb)rrrrrrd)rrrrrr)rrrrr=rrrrrrr s """"WWWXW WWWXW UUUXU SSSXS XUUUXU 555X5WWWXW XSSSXS SSSXS 111X1NNNXN    X TTTXTQQQQQQrrtblpa.Table | pa.RecordBatchReaderclddl}t||jr|j|S|SrC)rr*RecordBatchReaderTable from_batches)rpas rto_pyarrow_tablerAs>#r+,,*x$$S))) Jrwin32sourcerxcht|tr|ntt|Sr)r*rrrs rnormalize_pathrKs)#FC00Gvvc$v,,6G6GGrcDt|Sr)ras_posixrs rrrTsF||$$&&&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*r3r{)rrs r extend_boolrXs+",E4!8!8 JE8g  eEllJrceZdZdZddZdS) _NoDefault NO_DEFAULTrrcdS)Nz rrs rr9z_NoDefault.__repr__hs~rNrT)rrr no_defaultr9rrrrrcs/Jrr)rVrrr3)r1rrr<)rVrrr)rrrrrs)ryrrr)ryr}rr3)rrrr)rprrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr)rrrrrr3)rrrr)rrrrrr)rrrrr)rrrrrrrr)rrrr)rrrrrr)rrrrrr3)rrrrr3rrrr)rrrrrr)rrrr3)r)rrrr r!rrr)r*rr+r,r-r3rr.)r7r8rr9)rrrr<)rrrrA)rr8rrG)rrrrK)rrrrO)rrrrS)rrrrU)rrrrX)rrr\rrr])r`rarrb)rrr\rrr9)rrrrn)r-rrrrrrsr3rr3)rvrrwr3rrx)rrrrrr) rrrrrrrr3rr)rrrrrr)r+rr0rrr)rrrr)rrrrrr) rrqrrwrrrrrr3)r*rrr)r*rrr rr)rrrr)rrrrrr3)rrrr)rrrr)rrrr)rrrr)rnrrr)rnrrr)rnrrr )rrrr )rrrr)rrrrrrrr)rrZrrrr )rzrrr)r(rrr3)rIrrCrrrJ)rhrrrrri)rlrmrrn)rrtrr)rrryrzrrrr)rrrrrr)rrrrrrrr)rrrr )rrxrr)rrrrrr() __future__rrrsyscollections.abcrrrrrr r datetimer enumr r functoolsrrrimportlib.utilrinspectrroperatorrpathlibrsecretsrtypingrrrrrrrrrnarwhals._enumr narwhals._exceptionsr!narwhals._typing_compatr"r#narwhals.dependenciesr$r%r&r'r(r)r*r+r,r-r.r/r0r1r2r3r4r5r6narwhals.exceptionsr7r8r9r:r;typesr<r=r>rrrrrrtyping_extensionsr?r@rArBnarwhals._compliantrCrDrE!narwhals._compliant.any_namespacerFnarwhals._compliant.typingrGrHrIrJrrLnarwhals._nativerMrNrOrPrQrRrSrTrUrVrWrXnarwhals._translaterYrZr[narwhals._typingr\r]r^r_r`rarbrcrdrerfrgrhrirjrkrlrrnrorrqrrsnarwhals.typingrtrurvrwrxryrzr{r|r}r~rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrZrrrrrrrrrrrrer.r/rSrxr|rwrrmrrrrrrrrrr rr%r$r6r;r@rFrJrNrRrDrWr[r_rhrmrqrurrrrr3rrrrrrobjectrrrrrIrErZrrr r rrrr%r'r-r/rBrMrkrsrrrrrrrrrplatformrrrrrrrMrrrrs""""""" ----------$$$$$$********                      &%%%%%::::::<<<<<<<<*d0######      --------HHHHHHHHHHHHVVVVVVVVVVCCCCCC .-----                            ZYYYYYYYYY&87777777%%%%%%&&&&&&*%(''''W #3 ?&+ MN '%..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,,,,^8888    &*&*&*&*R*????F:>[[[[[:>)&)&)&)&)&XLLLL9999        """"DDDDJJJJ >>>> 0000&&&&&&&R$$$$0@<""""""""*    MMMM688 AAAA:::::::: 7777 ???? ???? SSSSZZZZ    88886666BBBB, # # # # ,;;;;$R(R(R(R(R(R(R(R(j####RRRRRRRRj61111 IK++++++\ : : : : : : : : 2 1111 *4hz6J 77777x #777:3Q3Q3Q3Q3Q3Q3Q3Ql<7HHHHH''''KKKK "   4::r