-j'B%SSKJr SSKrSSKrSSKrSSKJrJrJrJ r J r J r J r SSK Jr SSKJrJr SSKJrJrJr SSKJr SSKJrJr SS KJr SS KJr SS KJ r SS K!J"r"J#r#J$r$J%r%J&r&J'r'J(r(J)r)J*r* SS K+J,r, SSK-J.r. SSK/J0r0J1r1 SSK2J3r3J4r4J5r5J6r6J7r7J8r8J9r9J:r:J;r;Jr>J?r?J@r@JArAJBrBJCrCJDrDJErE SSKFJGrGJHrHJIrIJJrJ \"(GaPSSKJKrK SSKLJMrM SSK!JNrNJOrO SSKPrQSSKRrSSSKTrUSSKVJWrWJXrXJYrYJZrZ SSK[J\r\J]r]J^r^ SSK_J`r` SSKaJbrbJcrcJdrdJere SSKfJgrg SSKhJiriJjrjJkrkJlrlJmrmJnrnJoroJprpJqrqJrrrJsrsJtrt SSKuJvrvJwrwJxrx SSKyJzrzJ{r{J|r|J}r}J~r~JrJrJrJrJrJrJrJrJrJrJrJrJr SSKJrJr SSKJr SSKJr SS KJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJr \("S!\\#\\#-\\#-S"9r\("S#5r\("S$5r\("S%5r\("S&S'S"9r\X"S(5r\("S)5r\("S*5r\("S+5r"S,S-\'5r"S.S/\'5r"S0S1\'5r\("S25r\("S3S4S59r\("S6S4S59rS7rS8\S9'\("S:\S"9rS;rS8\S<'S=rS8\S>'"S?S@\'\5r"SASB\'\5r"SCSD\'5r"SESF\'5r"SGSH\'5r"SISJ\\\'5r"SKSL\\\'5r"SMSN\\'5r"SOSP\5r\"SQSR9SSSj5r\"SQSR9SSTj5r\"SQSR9SSUj5r\"SQSR9SSVj5r\"SQSR9SSWj5r"SXSY\,5rSSZjr\GRS[\GRS\\GRS]\GRS^\GRS_\GRS_\GRS`\GRSa\GRSb\GRSc\GRSd0 rSe\Sf'\GRSg\GRSh\GRSi\GRSj0rSk\Sl'\"SmSR9SSnj5r\SSoj5rSSpjrSSqjrSSrjrSSsjrSStjr\*SSuj5r\*SSvj5r\*SSwj5r\*SSxj5r\*SSyj5r\*SSzj5r\*SS{j5rSS|jrSS}jrSS~jrSSjrSSS.SSjjjrSSjrSSjrSSjrSSjrSSjrSSjrSSSjjrSSSjjrSSjrSSjrSSjrSSjrSSjrSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGS SjrSSS.GS SjjrGS SjrGS SjrGS SjrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrG\"5GrS\S'GSSjGr GSSjGr GSSjGr GSSjGr GSSjGr GSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGSSjGrGS SjGrGS!SjGrGS"SjGr"SS5GrGS#GS$SjjGrGS%SjGr"SS5GrGS&SjGrGS'SjGrGS(SjGrSS.GS)SjjGr "SS\%\5Gr!\"SSR9GS*Sj5Gr"GS+SjGr#"SS\\\\'\5Gr$"SS\'\5Gr%"SS5Gr&GS,SjGr'GS-SjGr(\GRRS:waGS.SjGr*OGS.SjGr*GS/SjGr+"SS\5Gr,G\,GRZGr.G\.Gr-G\/"S5Gr0g(0) 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 PluginName _ArrowImpl _CuDFImpl _DaskImpl _DuckDBImpl_EagerAllowedImpl _IbisImpl_LazyAllowedImpl_LazyFrameCollectImpl _ModinImpl _PandasImpl_PandasLikeImpl _PolarsImpl_PySparkConnectImpl _PySparkImpl _SQLFrameImpl DataFrame LazyFrameDTypeSeries)CompliantDataFrameCompliantLazyFrameCompliantSeriesDTypes FileSource IntoSeriesTMultiIndexSelector NestedLiteralNormalizedPathSingleIndexSelectorSizedMultiBoolSelectorSizedMultiIndexSelectorSizeUnitSupportsNativeNamespaceTimeUnit_1DArray _SliceIndex _SliceName _SliceNoneFrameOrSeriesT)bound_T1_T2_T3_FnzCallable[..., Any]PRR1R2c \rSrSr%S\S'Srg)_SupportsVersionstr __version__N__name__ __module__ __qualname____firstlineno____annotations____static_attributes__rڝC:\Users\johnn\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\site-packages\narwhals/_utils.pyrrsrrc"\rSrSrSSSjjrSrg) _SupportsGetNcgNrselfinstanceowners r__get___SupportsGet.__get__scrrr)rrr Any | Nonereturnr)rrrrrrrrrrrsQQrrc(\rSrSr\SSj5rSrg)_StoresColumnscgrrrs rcolumns_StoresColumns.columnss,/rrN)r Sequence[str])rrrrpropertyrrrrrrrs / /rr_T NativeT_coT) covariant CompliantT_coz._FullContext | NamespaceAccessor[_FullContext]r> _IntoContext _IntoContextTz*Callable[Concatenate[_IntoContextT, P], R]_Methodz Callable[Concatenate[_T, P], R2] _Constructorc,\rSrSrSr\SSj5rSrg) _StoresNativezProvides access to a native object. Native objects have types like: >>> from pandas import Series >>> from pyarrow import Table cg)zReturn the native object.Nrrs rnative_StoresNative.native rrN)rr)rrrr__doc__rrrrrrrr  rrc,\rSrSrSr\SSj5rSrg)_StoresCompliantzProvides access to a compliant object. Compliant objects have types like: >>> from narwhals._pandas_like.series import PandasLikeSeries >>> from narwhals._arrow.dataframe import ArrowDataFrame cg)zReturn the compliant object.Nrrs r compliant_StoresCompliant.compliantrrrN)rr)rrrrrrrrrrrrrrrrc(\rSrSr\SSj5rSrg)_StoresBackendVersioncg)z#Version tuple for a native package.Nrrs r_backend_version&_StoresBackendVersion._backend_versionrrrNrtuple[int, ...])rrrrrrrrrrrrs   rrc \rSrSr%S\S'Srg)_StoresVersionVersion_versionrNrrrrrrs ,rrc \rSrSr%S\S'Srg)_StoresImplementationImplementation_implementationrNrrrrrrs ##Irrc\rSrSrSrSrg)_LimitedContextz9Provides 2 attributes. - `_implementation` - `_version` rNrrrrrrrrrrrrrc\rSrSrSrSrg) _FullContextzAProvides 2 attributes. - `_implementation` - `_backend_version` rNrrrrrrrrrc"\rSrSrSrSSjrSrg)ValidateBackendVersionz=Ensure the target `Implementation` is on a supported version.c8URR5ng)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_version0ValidateBackendVersion._validate_backend_versions  1 1 3rrN)rNone)rrrrrrrrrrrrs G4rrc\rSrSr\"5r\"5r\"5r\S Sj5r \S Sj5r \S Sj5r \S Sj5r \S Sj5r Srg)rc[U5$r)_version_namespacers r namespaceVersion.namespace !$''rc[U5$r)_version_dtypesrs rdtypesVersion.dtypes t$$rc[U5$r)_version_dataframers r dataframeVersion.dataframe rrc[U5$r)_version_lazyframers r lazyframeVersion.lazyframerrc[U5$r)_version_seriesrs rseriesVersion.seriesrrrN)rtype[Namespace[Any]])rrx)rtype[DataFrame[Any]])rtype[LazyFrame[Any]])rtype[Series[Any]])rrrrr V1V2MAINrrrrrrrrrrrrsy B B 6D ((%%((((%%rr)maxsizec~U[RLaSSKJn U$U[RLaSSKJn U$SSKJn U$)NrrK)rr narwhals.stable.v1._namespacerLr narwhals.stable.v2._namespacenarwhals._namespace)version NamespaceV1 NamespaceV2rLs rrrs5'**J'**J- rc~U[RLaSSKJn U$U[RLaSSKJn U$SSKJn U$)Nr)r)rr narwhals.stable.v1rr narwhals.stable.v2narwhals)r dtypes_v1 dtypes_v2rs rrr&s4'**:'**: Mrc~U[RLaSSKJn U$U[RLaSSKJn U$SSKJn U$)Nr)ro)rr rror rnarwhals.dataframe)r DataFrameV1 DataFrameV2ros rrr55'**?'**?, rc~U[RLaSSKJn U$U[RLaSSKJn U$SSKJn U$)Nr)rp)rr rrpr rr)r LazyFrameV1 LazyFrameV2rps rrrDr"rc~U[RLaSSKJn U$U[RLaSSKJn U$SSKJn U$)Nrrs)rr rrtr rnarwhals.series)rSeriesV1SeriesV2rts rrrSs2'**9'**9& MrcT\rSrSrSrSrSrSrSrSr Sr S r S r S r S rS rSrS$Sjr\S%Sj5r\S&Sj5r\S'Sj5rS(SjrS)SjrS)SjrS)SjrS)SjrS)SjrS)SjrS)SjrS)SjrS)SjrS)Sjr S)Sjr!S)Sjr"S)S jr#S*S!jr$S"r%g#)+ribz?Implementation of native object (pandas, Polars, PyArrow, ...).pandasmodincudfpyarrowpysparkpolarsdaskduckdbibissqlframezpyspark[connect]unknownc,[UR5$r)rvaluers r__str__Implementation.__str__~s4::rcV[5[R[5[R[ 5[R [5[R[5[R[5[R[5[R[5[R [#5[R$['5[R([+5[R,0 nUR/U[R05$)zvInstantiate 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)clsnative_namespacemappings rfrom_native_namespace$Implementation.from_native_namespaces L.// K-- J++ M>11  ~55 L.//  ."5"5 L.// J++ NN33  !>#A#A  {{+^-C-CDDrcTU"U5$![a [Rs$f=f)zInstantiate Implementation object from a native namespace module. Arguments: backend_name: Name of backend, expressed as string. ) ValueErrorrrG)rH backend_names r from_stringImplementation.from_strings- *|$ $ *!)) ) *s  ''c[U[5(aURU5$[U[5(aU$UR U5$)zInstantiate from native namespace module, string, or Implementation. Arguments: backend: Backend to instantiate Implementation from. ) isinstancerrPrrK)rHbackends r from_backendImplementation.from_backendsR'3'' OOG $ '>22 **73  rcU[RLa Sn[U5eUR5 [R XR 5n[U5$)zCReturn the native namespace module corresponding to Implementation.z:Cannot return native namespace from UNKNOWN Implementation)rrGAssertionErrorr_IMPLEMENTATION_TO_MODULE_NAMErFr7_import_native_namespace)rmsg module_names rto_native_namespace"Implementation.to_native_namespacesK >)) )NC % % 488zzJ ' 44rc&U[RL$)zReturn 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 )rr;rs r is_pandasImplementation.is_pandas~,,,,rcfU[R[R[R1;$)a Return 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 )rr;r<r=rs ris_pandas_likeImplementation.is_pandas_likes(--~/C/C^EXEXYYYrcfU[R[R[R1;$)a Return 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 )rr?rDrErs r is_spark_likeImplementation.is_spark_likes1  " "  # #  * *   rc&U[RL$)zReturn 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 )rr@rs r is_polarsImplementation.is_polarsrbrc&U[RL$)zReturn 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 )rr=rs ris_cudfImplementation.is_cudf~****rc&U[RL$)zReturn 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 )rr<rs ris_modinImplementation.is_modins~++++rc&U[RL$)zReturn 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 )rr?rs r is_pysparkImplementation.is_pyspark~----rc&U[RL$)aReturn 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 )rrErs ris_pyspark_connect!Implementation.is_pyspark_connects~5555rc&U[RL$)zReturn 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 )rr>rs r is_pyarrowImplementation.is_pyarrow,rvrc&U[RL$)zReturn 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 )rrArs ris_daskImplementation.is_dask9rorc&U[RL$)zReturn 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 )rrBrs r is_duckdbImplementation.is_duckdbFrbrc&U[RL$)zReturn 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 )rrCrs ris_ibisImplementation.is_ibisSrorc&U[RL$)zReturn 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 )rrDrs r is_sqlframeImplementation.is_sqlframe`s~....rc[U5$)zReturns backend version.backend_versionrs rrImplementation._backend_versionmrrrNrr)rH type[Self]rIr<rr)rHrrOrrr)rHrrTz!IntoBackend[Backend | PluginName]rr)rr<)rboolr)&rrrrrr;r<r=r>r?r@rArBrCrDrErGr8 classmethodrKrPrUr]r`rdrgrjrmrqrtrxr{r~rrrrrrrrrrbs'I F E DG!G! F D F DH"(O)G!E E+5E EE. * *  "C   5 - Z " - + , . 6 . + - + /%rrcUR5=(d UR5=(a UR5S:$)zJWhether implementation is PySpark (or PySpark Connect) with version < 4.0.)r)rtrxrimplementations ris_pyspark_pre_4rrs9 !!#J~'H'H'J 5  ) ) +f 45r)rr)rr) ) )r)rr)i)rr))rrrz(Mapping[Implementation, tuple[int, ...]] MIN_VERSIONSzdask.dataframez modin.pandasz pyspark.sqlzpyspark.sql.connectzMapping[Implementation, str]rYcSSKJn U"U5$)Nr) import_module) importlibr)r\rs rrZrZs'  %%rc[U[5(d [U5 U[RLagUn[R XR 5n[U5nUR5(aSSK nURnOOUR5(dUR5(aSSK nUnOUR5(aSSKnUnOUn[!U5nU["U=n :aSUSU SU3n [%U 5eU$)N)rrrrzMinimum version of z supported by Narwhals is z , found: )rSrr"rGrYrFr7rZrsqlframe._versionrrtrxr/r~r1 parse_versionrrN) rimplr\rIr4 into_versionr/r1r min_versionr[s rrrs nn 5 5^$/// D044T::FK/ <  ((   d5577  ' L)Gd!33+4#D6)CK=PYZaYbco Nrcn[[U5S:Xa[US5(a US5$U5$)Nrr)listlen _is_iterable)argss rflattenrs1 CIN|DG/D/DQ PP4 PPrcB[U[[45(dU4$U$r)rSrtuple)args rtupleifyrs cD%= ) )v JrcSSKJn [5=nb&[XRUR45(dI[ 5=nbW[XRUR URUR45(aS[U5<S3n[U5e[U[5=(a [U[[U45(+$)Nrrsz(Expected Narwhals class or scalar, got: z`. Hint: Perhaps you - forgot a `nw.from_native` somewhere? - used `pl.col` instead of `nw.col`?) r'rtr)rSror*Exprrpqualified_type_name TypeErrorrrbytes)rrtpdplr[s rrrs&| (Zii=V-W-W| ( sYYr||L M M77J37O6RS3 3 n c8 $ RZc5&=Q-R)RRrc"[U[5$r)rSr)vals r is_iteratorrs c8 $$rc[U[5(aUO URn[R"SSU5n[ SUR S555$)zSimple version parser; split into a tuple of ints for comparison. Arguments: version: Version string, or object with one, to parse. z (\D?dev.*$)c3d# UH&n[[R"SSU55v M( g7f)z\DrN)intresub).0vs r parse_version..s'K4JqRVVE2q)**4Js.0.)rSrrrrrsplit)r version_strs rrrsK(55'7;N;NK&&[9K KK4E4Ec4JK KKrcgrr obj_or_cls cls_or_tuples risinstance_or_issubclassrsrcgrrrs rrr rcgrrrs rrrs"rcgrrrs rrrs+.rcgrrrs rrrs%(rcgrrrs rrrs7:rcgrrrs rrrsrcSSKJn [X5(a [X5$[X5=(d" [U[5=(a [ X5$)Nrrq)narwhals.dtypesrrrStype issubclass)rrrrs rrrsA%*$$*33 j / :t$MJ)Mrc^^SSKJmJm [U4SjU55(d[U4SjU55(agSUVs/sHn[ U5PM sn3n[ U5es snf)Nrrnc3<># UHn[UT5v M g7frrS)ritemros rr$validate_laziness..!s 954:dI & &5c3<># UHn[UT5v M g7frr)rrrps rrr"s :EDJtY ' 'ErzGThe items to concatenate should either all be eager, or all lazy, got: )rrorpallrr)itemsrr[rorps @@rvalidate_lazinessrsc7 95 999 :E ::: SlqTrlqdhUYZ^U_lqTrSs tC C.UssA*c:SSKJn SSKJn S Sjn[ SU5n[ SU5n[ [ USS5U5(a[ [ USS5U5(aU"URRR5 U"URRR5 URURRURRRURRR55$[ [ USS5U5(a[ [ USS5U5(aU"URRR5 U"URRR5 URURRURRRURRR55$[ [ USS5U5(a[ [ USS5U5(aU"URRR5 U"URRR5 URURRURRRURRR55$[ [ USS5U5(a[ [ USS5U5(aU"URRR5 U"URRR5 URURRURRRURRR55$[U5[U5:wa%S [U5S [U53n[U5eU$) aPAlign `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)PandasLikeSeriesrc@UR(d Sn[U5eg)Nz'given index doesn't have a unique index) is_uniquerN)indexr[s r_validate_index*maybe_align_index.._validate_indexJs;CS/ !r_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )rrrr)narwhals._pandas_like.dataframernarwhals._pandas_like.seriesrrrSgetattrrrr_with_compliant _with_nativelocrrrN)lhsrhsrrrlhs_anyrhs_anyr[s rmaybe_align_indexr)si<D=" 5#G5#G+T24G WW&8$?AT U U0077==>0077==>&&  $ $ 1 1((//33G4L4L4S4S4Y4YZ   +T24G WW&94@BR S S0077==>1188>>?&&  $ $ 1 1((//33--44::   ,d35E WW&8$?AT U U1188>>?0077==>&&  % % 2 2))0044,,3399   ,d35E WW&94@BR S S1188>>?1188>>?&&  % % 2 2))0044--44::    7|s7|#Fs7|nTYZ]^eZfYgho Jrc[SU5nUR5n[U5(d[U5(a UR$g)a>Get 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)objobj_any native_objs rmaybe_get_indexrsC45#G""$J ++/DZ/P/P r)rcSSKJn [SU5nUR5nUbUb Sn[U5eU(dUc Sn[U5eUb/[ U5(aUVs/sH os"USS9PM snOU"USS9nOUn[ U5(a9UR URRURU555$[U5(a`SSK J n U(a S n[U5eU "UUURRS 9nUR URRU55$U$s snf) a3Set 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)rrz8Only one of `column_names` or `index` should be providedz3Either `column_names` or `index` should be providedT) pass_through) set_indexz/Cannot set index using column names on a Seriesr)narwhals.translaterrrNrr5rrrrr6narwhals._pandas_like.utilsrr) r column_namesrrdf_anyrr[idxkeysrs rmaybe_set_indexr sDX- % F!!#JE$5Ho EMCo E"";@ @%3Ys .% @5t4  ++%%  # # 0 01E1Ed1K L  Z((9 CCS/ !  00@@ %%f&>&>&K&KJ&WXX M1 As$D<c[SU5nUR5n[U5(aYUR5n[ X#5(aU$UR UR RURSS955$[U5(aYUR5n[ X#5(aU$UR URRURSS955$U$)awReset 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)rrrrIs rmaybe_reset_indexrs85#G""$J ++"779 j ; ;N&&  $ $ 1 1*2H2Hd2H2S T  Z(("779 j ; ;N&&  % % 2 2:3I3It3I3T U   Nrc,[XR5$r)rS RangeIndex)rrIs r_is_range_indexr+s c66 77rcURn[X!5=(aD URS:H=(a. UR[ U5:H=(a UR S:H$)Nrr)rrstartstoprstep)native_frame_or_seriesrIrs rr r /sT # ( (E0  KK1   JJ#e* $  JJ!O rc URR5(dU$URURR UR 5R "U0UD655n[SU5$)aConvert 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)rrdr _compliantrrconvert_dtypesr)rrkwargsresults rmaybe_convert_dtypesr;sgB    , , . .   ##CMMO$B$BD$SF$STF  & ))rcUS;aU$US;aUS- $US;aUS- $US;aUS- $US;aUS - $S U<3n[U5e) 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 rN)szunitr[s r scale_bytesr+dss ~  ""Dy ""G| ""G| ""G| Gx PC S/rcZSSKJn URRRnURnSn[ X15(a@[ UR UR5(aURRSnU$UR UR:XaSnU$UR UR:waSnU$UR5nURnUR5(a9UR5S:a%[SUR 5R S:HnU$UR#5(a![%UR&R(5nU$UR+5(a5SS KJn U"UR05=(a UR0R(nU$) 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-rrrrSdtype Categoricalrdescribe_categoricalr rrrjrrorderingrdrcatorderedr{narwhals._arrow.utilsr1r)rr-rrrrrr1s ris_ordered_categoricalr:ysoF?  % % . . 5 5F((IF)//J f((55!!66|D& M%  $" M! ++ + M!!#$$ >>   5 5 7' A*FLL9BBjPF M  " "&**,,-F M __   ;"6;;/GFKK4G4GF Mrc.Sn[USS9 [XUS9$)Nz}Use `generate_temporary_column_name` instead. `generate_unique_token` is deprecated and it will be removed in future versionsz1.13.0r)n_bytesrprefix)r!generate_temporary_column_name)r=rr>r[s rgenerate_unique_tokenr@s& ?cH5 )'SY ZZrc|SnU[US- 53=oA;aU$US- nUS:aSU<SU3n[U5eM:)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 rrdzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in )rrX)r=rr>countertokenr[s rr?r?sk<G x 'A+ 678 8E HL1  S=*L 3 !% % rcU(d-[[UR5RU55$[U5n[ X0RS9=n(aUeU$)N) available)rsetr intersectioncheck_columns_exist)framesubsetstrictto_droperrors rparse_columns_to_droprOsM C &33F;<<6lG#G}}EEuE Nrc,SSKnUc UR$U$Nr)string whitespace) charactersrRs rparse_str_strip_charsrUs * 26  B BrcZ[U[5=(a [U[5(+$r)rSr r)sequences ris_sequence_but_not_strrXs h ) K*Xs2K.KKrcL[U[5=(a U[S5:H$r)rSslicers r is_slice_noner\s c5 ! 8cU4[&88rc[U5=(a8 [U5S:=(a [US5=(d [U5S:H=(d/ [U5=(d [ U5=(d [ U5$rQ)rXris_single_index_selectorr4r1is_compliant_series_intr[s ris_sized_multi_index_selectorr` sl $C ( Yc(Q,C#;CF#CWSUV ( ! %  ( "# &  ( #3 'rc[U5=(d/ [U5=(d [U5=(d [U5$r)rXr2r/is_compliant_seriesr[s ris_sequence_likercs: $ $ S ! $ c " $ s # rcH[U[5=(a [UR[5=(dk [UR[5=(dJ [UR [[ 45=(a# URSL=(a URSL$r)rSrZrrrrNoneTyper[s ris_slice_indexrf$sr c5 ! 399c" chh $  sxx#x 1 ! T! !D rc"[U[5$r)rSranger[s ris_rangeri0s c5 !!rcZ[U[5=(a [U[5(+$r)rSrrr[s rr^r^4s c3  = 3(=$==rc`[U5=(d [U5=(d [U5$r)r^r`rfr[s ris_index_selectorrl8s+ !%  ( -  # rc[U5=(a( [U5S:=(a [US[5=(d/ [ U5=(d [ U5=(d [ U5$rQ)rXrrSrr3r0is_compliant_series_boolr[s ris_boolean_selectorroBsW ! % U3s8a<+TJs1vt.Us=*$z$%%*sany) predicatess r predicates_contains_list_of_boolrzRs =*= ==rc[[U5=(a) [[U5S5=n=(a [ X!55$r)rrXnextiterrS)rrqfirsts ris_sequence_ofrXs< $ "49d+ +U " u ! rc8[U[[[45$r)rSrrdictr[s ris_nested_literalras cD%. //rc`UcUcUnU$Ub Uc U(+nU$UcUbU$Sn[U5e)Nz,Cannot pass both `strict` and `pass_through`r()rLrpass_through_defaultr[s rvalidate_strict_and_pass_thoughres_ ~,.+     4!z  L4  =orrF) warn_versionrequiredc^^SUU4SjjnU$)a Decorator 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**. c:>^[T5SUUU4Sjj5nU$)Nc>URSS5nURSS5nUbUcT(a Sn[UTS9 UnO;UbUb Sn[U5eUc%Uc"T(aSTRS3n[U5eX!S'T"U0UD6$)NrTrIz`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 ``.)popr!rNr)rkwdsrTrIr[fnrrs rwrapper=deprecate_native_namespace..decorate..wrappershhy$/G#xx(:DA +j .cLI*!-'2EH o%!)go(8 RH o%%Ot$t$ $r)rP.argsrP.kwargsrr)r)rrrrs` rdecorate,deprecate_native_namespace..decorates% r % %  %*r)rCallable[P, R]rrr)rrrs`` rdeprecate_native_namespacerws2 Orc[U[SS9 [U[[S5SS9 US:a Sn[U5eUb)US:a Sn[U5eX:a Sn[ U5eX4$UnX4$)N window_size param_name min_samplesrz+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_typerrrNr9)rrr[s r_validate_rolling_argumentsrs S]; S$t*GQ;o ??CS/ !  $JC', , %  ##"  ##rcUbUb Sn[U5eUbUnOUb[X!-5nOSnUS:aSU3n[U5eXR:aU(d Sn[U5eU$)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. z&cannot specify both `n` and `fraction`rrz.sample size must be a positive integer, found zScannot take a larger sample than the total population when `with_replacement=false`)rNrr9r:)nfractionheightwith_replacementr[sizes r_resolve_sample_sizersy }-6o}  6$% ax>tfE#C(( }-co Krc [R"5RnUR 5R5n[SU55nUS-U::a[U[U55nSSU-S3nU[U5- nUSS US--US US-US---S 3- nUSS U-S 3- nXT- S-nXT- S-XT- S--n UH$n USS U-U S X-[U 5- -S 3- nM& US SU-S 3- nU$S[U5- n SSSS U S--US U S-U S---SSS 3 $![a$ [ [R "SS55nGN;f=f)NCOLUMNSPc38# UHn[U5v M g7fr)r)rlines rr generate_repr..s>3t99u┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorrgetenv expandtabs splitlinesmaxr) header native_reprterminal_width native_linesmax_native_widthlengthoutput header_extra start_extra end_extrardiffs r generate_reprrs7--/77))+668L>>>!~-%s6{3uv~&e,F + Ac\Q./0 PQ@QT`cdTd@d9e8ffijjAcVn%S))0Q6 .148QUV7VV  D #-.tfSI.s#L9KaS1#V,9Krz"Expected unique column names, got:)rrG collectionsrrjoinr8)rrrCrr duplicatesr[s rcheck_column_names_are_uniquers 7|s3w<((''"'.}}@tq!a%dad @ggL9I9I9KLL23%8S!!)As  BBcUc1SkO"[U[5(aU1O [U5nUcS1OF[U[[45(a [U51OUVs1sHo3b [U5OSiM snnX$4$s snf)N>smsnsus)rSrrGr ) time_unit time_zone time_unitstz time_zoness r_parse_time_unit_and_time_zoner s    i % %[ ^     i#x 1 1)n T$rr)_framers rr$passthrough_column_names..fn6s r)rrrrr)rrs` rpassthrough_column_namesr5s Irr _SENTINELc.[X[5[L$r)rr)rattrs r_hasattr_staticr?s #Y /y @@rc[US5$)N__narwhals_dataframe__rr[s ris_compliant_dataframerCs 3 8 99rc[US5$)N__narwhals_lazyframe__rr[s ris_compliant_lazyframerNs 3 8 99rc[US5$)N__narwhals_series__rr[s rrbrbTs 3 5 66rcZ[U5=(a URR5$r)rbr3 is_integerr[s rr_r_Z! s # > (<(<(>>rcZ[U5=(a URR5$r)rbr3 is_booleanr[s rrnrn`rrc@[US5=(a [US5$)Nr _accessorrr[s r_is_namespace_accessorrfs 3 , Rk1RRrcU[R[R[R[R[R 1;$)z.Return True if `impl` allows eager operations.)rr=r<r;r@r>rs ris_eager_allowedrpsA   rcfU[R[R[R1;$)z4Return True if `LazyFrame.collect(impl)` is allowed.)rr;r@r>rs rcan_lazyframe_collectr{s& N))>+@+@.BXBXY YYrcU[R[R[R[R[R [R [R1;$)z1Return True if `DataFrame.lazy(impl)` is allowed.)rrArBrCr@r?rErDrs ris_lazy_allowedrsS && rc[US5$)Nr rr[s rhas_native_namespacer s 3 6 77rc[US5$)N__arrow_c_stream__rr[s rsupports_arrow_c_streamr s 3 4 55rcF^^UU4SjU5n[[XSS95$)a+Remap 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. c3>># UHoT;aUT3OUv M g7frr)rkeyleft_onsuffixs rr(_remap_full_join_keys..s&?G7N3%x3xsF)rL)rzip)rright_onrright_keys_suffixeds` ` r_remap_full_join_keysrs' ?G H%@ AArc[S5(aRURRRS5RnUR R XS9R$S[U5<S3n[U5e)zGuards `ArrowDataFrame.from_arrow` w/ safer imports. Arguments: data: Object which implements `__arrow_c_stream__`. context: Initialized compliant object. r.)contextzB'pyarrow>=14.0.0' is required for `from_arrow` for object of type r) rrrrUr _dataframe from_arrowrrModuleNotFoundError)datarrr[s r_into_arrow_tablersq    ' ' 4 4Y ? I I}}'''9@@@ NObcgOhNkkl mC c ""rcU$)azVisual-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 runstablers & Irc8^[U4SjS55(+$)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,># UH oT;v M g7frr)rxformats rr#_is_naive_format..s:(91;(9s)z%sz%zZrw)r#s`r_is_naive_formatr&s:(9:: ::rcz\rSrSrSrS SS.SSjjjrSSjrSSjrS SS jjrSS jr \ SS j5r S r g)not_implementediaMark some functionality as unsupported. Arguments: alias: optional name used instead of the data model hook [`__set_name__`]. hint: optional explanation of why this is unsupported and what to do instead. When given, it replaces the "please open an issue" pointer, so use it for functionality we deliberately won't implement (see `length_changing_hint`). 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 Nr)hintcXlX lgr)_alias_hint)raliasr)s r__init__not_implemented.__init__ s#(  rcfS[U5RSURSUR3$)N: r)rr _name_owner_namers r__repr__not_implemented.__repr__s14:&&'s4+;+;*T>TU !7!7 7~&C""C$TZZjjArc$URS5$)Nraise)r)rrrs r__call__not_implemented.__call__*s||G$$rc2U"5n[U5"U5$)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#)rHmessagers rr#not_implemented.deprecated/se'"3''r)r+r,r3r2r)r- str | Noner)rrrr)rtype[_T]r8rrr)rz_T | Literal['raise'] | Nonerztype[_T] | Nonerr)rrrrrr)rEr?rrA) rrrrrr.r4r9rrBrr#rrrrr(r(sa$L2 K. PT4=L $%  ( (rr(cJSnU=(d UnU<SU<SU3n[U5e)NzIf you would like to see this functionality in `narwhals`, please open an issue at: https://github.com/narwhals-dev/narwhals/issuesz is not implemented for: z. )NotImplementedError)whatr>r) fallback_msgtailr[s rr=r=<s;  S  >> 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_versionrr, _wrapped_namec@URU5nXlX#lU$)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. )__new__rTr,)rHminimumr)rs rrrequires.backend_versionys"kk#"  rc2SRSU55$)Nrc3&# UHov M g7frr)rds rr,requires._unparse_version..s81#s)rrs r_unparse_versionrequires._unparse_versionsxx8888rcRSUR;aUSUR3UlggNrrU)rr>s r_qualify_accessor_namerequires._qualify_accessor_names/ d(( ($*81T-?-?,@!AD  )rc[U5(a(URUR5 URnOUnUR[ UR 54$r)rrcrrrrr)rrrs r_unwrap_contextrequires._unwrap_contextsM !( + +  ' '(:(: ; **I I))3y/H/H+IIIrc .URU5up#X R:agURUR5nURU5nSURSUSUSU<S3 nUR(aUSUR3n[ U5e)N`z` is only available in 'z>=z', found version r )rfrTr^rUr,rJ)rrrrTrXfoundr[s r_ensure_versionrequires._ensure_versions//9 '' ' ''(9(9:%%g.$$$%%=gYb Qbchbkklm ::EDJJ<(C!#&&rcZ^^TRTl[T5SUU4Sjj5nU$)Nc>>TRU5 T"U/UQ70UD6$r)rl)rrrrrs rr"requires.__call__..wrappers&   *h... .r)rrrrrrrr)rrUr)rrrs`` rrBrequires.__call__s. [[ r /  / rrbNr)r)rrXrrrA)rrrr)r>rGrr)rrrztuple[tuple[int, ...], str])rrrr)r_Method[_IntoContextT, P, R]rrs)rrrrrrrr staticmethodr^rcrfrlrBrrrrrSrS[sm*"! J   99B J ' .  % rrScURbURUR5OSnURbURUR5S-OSnURnX#U4$)Nr)rrrr) str_slicerrrrs rconvert_str_slice_to_int_slicerwsX/8oo.IGMM)// *tE090J7== (1 ,PTD >>D  rc^SU4SjjnU$)zSteal the class-level docstring from parent and attach to child `__init__`. Returns: Decorated constructor. Notes: - Passes static typing (mostly) - Passes at runtime c>URS:Xa0[[T5[5(a[T5UlU$S[ RSUR <ST<3n[U5e)Nr.z`@zL` is only allowed to decorate an `__init__` with a class-level doc. Method: z Parent: )rrrrr inherit_docrr) init_childr[ tp_parents rrinherit_doc..decoratess   * ,DOT1R1R!' !2J  %%&'!..12 m % nr)r{_Constructor[_T, P, R2]rr~r)r|rs` rrzrzs  Orc[U[5(aUO [U5nURS:wa UROSnUSUR3R S5$)Nbuiltinsrr)rSrrrlstrip)rrqmodules rrrsO3%%49B mmz9R]]rFXQr{{m $ + +C 00rrcR[X5(dSRSU55nSU<S[U5<3nU(aZSn[U5n[ U5S:a[U5S3nUUS3nS [ U5-S [ U5--nUS UUS U3n[ U5eg ) a2Validate 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 | c38# UHn[U5v M g7fr)r)rrqs rrensure_type..sL "1"55 rz Expected z, got: z (z(...)=r^rjN)rSrrr<rr) rr valid_typestp_namesr[left_padrassign underlines rrrs@ c ' '::L LL(W-@-E,HI Hs)C3x"},S12%8 z*Q/Fs6{*sSX~>IEF8C59+6Cn (rc6\rSrSrSrSSjrS SjrS SjrSrg) _DeferredIterableizLStore a callable producing an iterable to defer collection until we need it.cXlgr _into_iter)r into_iters rr._DeferredIterable.__init__ s6?rc#@# UR5ShvN gN7frrrs r__iter___DeferredIterable.__iter__s??$$$s cfUR5n[U[5(aU$[U5$r)rrSr)rits rto_tuple_DeferredIterable.to_tuples) __ E**r9b 9rrN)rzCallable[[], Iterable[_T]]rr)rz Iterator[_T])rztuple[_T, ...]) rrrrrr.rrrrrrrrsV@%:rr@cTU(aSRU/UQ75OUn[U5$ra)rr)rnestedr8s rdeep_attrgetterrs%(.388TOFO $DD d rc&[U/UQ76"U5$)z+Perform a nested attribute lookup on `obj`.)r)rname_1rs r deep_getattrrs 6 +F +C 00rc\rSrSrSrg) Complianti"rN)rrrrrrrrrr"srrc,\rSrSrSr\SSj5rSrg)Narwhalsi'apMinimal *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 cgrrrs rrNarwhals._compliant@s36rrN)rzCompliant[NativeT_co])rrrrrrrrrrrrr's066rrc\rSrSrSrSSjr\SSj5r\SSj5r\SSj5r\SSj5r\SSj5r\SS j5r\SS j5r\SS j5r\SS j5r\S S j5r\S!Sj5r\S"Sj5r\S#Sj5r\S$Sj5r\S%Sj5rS&SjrSrg)'_ImplementationiDzDescriptor for matching an opaque `Implementation` on a generic class. Based on [pyright comment](https://github.com/microsoft/pyright/issues/3071#issuecomment-1043978070) cX lgrrr7s rr9_Implementation.__set_name__Js! rcgrrrs rr_Implementation.__get__MTWrcgrrrs rrrOrrcgrrrs rrrQRUrcgrrrs rrrSPSrcgrrrs rrrUsrcgrrrs rrrYrrcgrrrs rrr[s25rcgrrrs rrr_rrcgrrrs rrrasrcgrrrs rrrerrcgrrrs rrrgrrcgrrrs rrris.1rcgrrrs rrrnsKNrcgrrrs rrrprrcgrrrs rrrtsQTrc8UcU$URR$r)rrrs rrrvs'tPX-@-@-P-PPrrN)r type[Any]r8rrr)rzNarwhals[NativePolars]rrrrj)rzNarwhals[NativePandas]rrrrh)rzNarwhals[NativeModin]rrrrg)rzNarwhals[NativeCuDF]rrrr`)rzNarwhals[NativePandasLike]rrrri)rzNarwhals[NativeArrow]rrrr_)rz3Narwhals[NativePolars | NativeArrow | NativePandas]rrrz&_PolarsImpl | _PandasImpl | _ArrowImpl)rzNarwhals[NativeDuckDB]rrrrb)rzNarwhals[NativeSQLFrame]rrrrm)rzNarwhals[NativeDask]rrrra)rzNarwhals[NativeIbis]rrrrd)rz.Narwhals[NativePySpark | NativePySparkConnect]rrrz"_PySparkImpl | _PySparkConnectImpl)rrrztype[Narwhals[Any]]rrA)rzDataFrame[Any] | Series[Any]rrrrc)rzLazyFrame[Any]rrrre)rzNarwhals[Any] | Nonerrrr) rrrrrr9rrrrrrrrDs| "WW WW UU SS 2;> UU 5K5TW5 /55WW 09< SS SS 1F1OR1 +11NN  4 =@   TTQrrcxSSKn[XR5(aURR U5$U$rQ)r.rSRecordBatchReaderTable from_batches)tblpas rto_pyarrow_tablerzs0#++,,xx$$S)) Jrc lUH.nX2;dM X#U:wdMSUSUSUSX#S3 n[U5e g)zSEnsure `separator` does not conflict with backend-native aliases passed via `kwds`.z`separator` and `z` do not match: `separator`=z and `z`=rN)r) separatornative_separatorsrnative_separatorr[s rvalidate_separatorsrs^.  #(>)(K#$4#56(k0@/ADDZC[[\^ C. .rwin32cxSSKJn U"[U[5(aU5$[[ U555$Nr)r})narwhals.typingr}rSrrsourcer}s rnormalize_pathrs-2 63(?(?fWWSfEVWWrcLSSKJn U"[U5R55$r)rr}ras_posixrs rrrs2d6l33566rcN[U[5(aU4U-$[U5$)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 )rSrr)r7n_matchs r extend_boolrs&",E4!8!8E8g JeElJrc"\rSrSrSrSSjrSrg) _NoDefaulti NO_DEFAULTcg)Nz rrs rr4_NoDefault.__repr__srrNr)rrrr no_defaultr4rrrrrrsJrr)rrrr)rrrrx)rrrr )rrrr )rrrr )rrrr)r\rrr<)rrrr)rrrz list[Any])rrrr)rzAny | Iterable[Any]rr)rzIterable[_T] | AnyrzTypeIs[Iterator[_T]])rz#str | ModuleType | _SupportsVersionrr)rrrrHrzTypeIs[type[_T]])r object | typerrHrzTypeIs[_T | type[_T]])rrrtuple[type[_T1], type[_T2]]rzTypeIs[type[_T1 | _T2]])rrrrrz#TypeIs[_T1 | _T2 | type[_T1 | _T2]])rrr&tuple[type[_T1], type[_T2], type[_T3]]rzTypeIs[type[_T1 | _T2 | _T3]])rrrrrz/TypeIs[_T1 | _T2 | _T3 | type[_T1 | _T2 | _T3]])rrrztuple[type, ...]rz TypeIs[Any])rrrrrr)rz Iterable[Any]rr)rrrz-Series[Any] | DataFrame[Any] | LazyFrame[Any]rr)rz-DataFrame[Any] | LazyFrame[Any] | Series[Any]rrr)rrrzstr | list[str] | Nonerz6Series[IntoSeriesT] | list[Series[IntoSeriesT]] | Nonerr)rrrr)rrrIrrzTypeIs[pd.RangeIndex])rzpd.Series[Any] | pd.DataFramerIrrr)rrrrrz bool | strrr)r)rr*rrz int | float)rz Series[Any]rr)nw)r=rrContainer[str]r>rrr)rJrrKz Iterable[str]rLrrz list[str])rTrGrr)rWSequence[_T] | AnyrTypeIs[Sequence[_T]])rrrzTypeIs[_SliceNone])rrrzCTypeIs[SizedMultiIndexSelector[Series[Any] | CompliantSeries[Any]]])rrrz-TypeIs[Sequence[_T] | Series[Any] | _1DArray])rrrzTypeIs[_SliceIndex])rrrz TypeIs[range])rrrzTypeIs[SingleIndexSelector])rrrzTTypeIs[SingleIndexSelector | MultiIndexSelector[Series[Any] | CompliantSeries[Any]]])rrrzBTypeIs[SizedMultiBoolSelector[Series[Any] | CompliantSeries[Any]]])rrrqrHrzTypeIs[list[_T]])ryzCollection[Any]rzTypeIs[Collection[list[bool]]])rrrqrHrr)rrrzTypeIs[NestedLiteral])rL bool | Nonerrrrrr)rrrrrz*Callable[[Callable[P, R]], Callable[P, R]])rrr int | Nonerztuple[int, int]) rrrz float | Nonerrrrrr)rrrrrr)rKCollection[str]rFrrzColumnNotFoundError | None)rrrr)rz$TimeUnit | Iterable[TimeUnit] | Nonerz7str | timezone | Iterable[str | timezone | None] | Nonerz%tuple[Set[TimeUnit], Set[str | None]]) r3rrrrxrz Set[TimeUnit]rzSet[str | None]rr)rJrrr)rJrrrrr)rrrzEvalNames[Any])rrrrrr)rz\CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co] | Anyrz^TypeIs[CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeDataFrameT, ToNarwhalsT_co]])rzJCompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co] | AnyrzLTypeIs[CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co]])rz'CompliantSeries[NativeSeriesT_co] | Anyrz)TypeIs[CompliantSeries[NativeSeriesT_co]])rrrz'TypeIs[NamespaceAccessor[_FullContext]])rrrzTypeIs[_EagerAllowedImpl])rrrzTypeIs[_LazyFrameCollectImpl])rrrzTypeIs[_LazyAllowedImpl])rrrzTypeIs[SupportsNativeNamespace])rrrzTypeIs[ArrowStreamExportable])rrrrrrrzdict[str, str])rrZrrrpa.Table)rrrr)r#rrrrr)rKrr>rr)rrrJ)rOrrPrrr)rvrrrrz"tuple[int | None, int | None, Any])r|zCallable[P, R1]rzr+rr0rr.rtyping_extensionsr?r@rArBnarwhals._compliantrCrDrE!narwhals._compliant.any_namespacerFnarwhals._compliant.typingrGrHrIrJrrLnarwhals._nativerMrNrOrPrQrRrSrTrUrVrWrXnarwhals._translaterYrZr[narwhals._typingr\r]r^r_r`rarbrcrdrerfrgrhrirjrkrlrmrrorprrrr'rtrrurvrwrxryrzr{r|r}r~rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr;r<r=r>r?rEr@rArBrCrDrrYrZrrrrrrrrrrr rrr rr+r:r@r?rOrUrXr\r`rcrfrir^rlrorrrzrrrrrrrrIrrrrrrobjectrrrrrbr_rnrrrrr r rrrr&r(r=rQrSrwrzrrrrrrrrrrplatformrrrrrrrerrrrs " --$*   &:<*# -HHVVC .    ZY(8%&, #3 ?&+ MN %.C %.C %.C %3 4C#A A B B8RxR00  T] \T 2 48 J iJ|< AA< i<  HZ(    x .   H -X- JHJ +^X(*? 42H 4%d%4 1   1   1   1   1  M%ZM%`59*EF""F:6Z : 6 ).M""$9 @ < D 2&&<Q S*% L $,     -5     ""$?"" "  ..-H.(. .  (($J("( (  ::-S:4: :  #3  Y YKYYxF,0SEI S S(S B S  Sl,^8 9 MP   &* &* $&*0:&*&*R*?F:>[ [)[36[[:>)& )&))&36)&)&X #0@DC L9   H  2 "> Y GJ >>#> 0    &&&)-&/&R$$#-$$0  ,69MQ@< .=""3"F"+"*     .; IX   M8 5A: :  :: S:Q: 7 07.7 ? 0?.? ? 0?.? SZ 86B B(7BADBB, # ,;$V(V(t&( #  # #" # #"RRj$1'A61 IK++\ : : 2 1 *4hz6J 7x #7:3Q3Ql ! !'6 !>O !  !<<7X7 K K KK " "   :r