o h@sN UddlmZddlZddlZddlmZddlmZddlmZddl m Z ddl m Z ddl mZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddl m!Z!ddl m"Z"ddl m#Z#ddl m$Z$ddl m%Z%ddl m&Z&ddl m'Z'ddl m(Z(ddl m)Z)dd l m*Z*dd!l m+Z+dd"l m,Z,dd#l m-Z-dd$l m.Z.dd%l m/Z/dd&l m0Z0dd'l m1Z1dd(l m2Z2dd)l m3Z3dd*l m4Z4dd+l m5Z5dd,l m6Z6dd-l m7Z7dd.l8m9Z9dd/l8m:Z:dd0l8m;Z;erdd1lZ?ddl@ZAddlBZCdd3lDmEZEdd4lDmFZFdd5lDmGZGdd6lDmHZHdd7lDmIZIdd8lDmJZJdd9lKmLZLdd:lKmMZMdd;lKmNZNddlKmQZQdd?lKmRZRdd@lSmTZTddAlUmVZVddBlUmWZWddClXmYZYddDlXmZZZddEl[m\Z\ddFl[m]Z]ddGl^m_Z_ddHl`maZaddIlbmcZcddJlbmdZdddKlbmeZeddLlbmfZfddMlbmgZgddNlbmhZhddOlbmiZiddPlbmjZjddQlbmkZkddRlbmlZlddSlbmmZmddTlbmnZnddUlbmoZoddVlbmpZpddWlbmqZqddXlbmrZredYee]ee\eeaefdZZsed[Zted\Zued]Zved^Zwed_d`dZZxeGdaZyedbZzGdcddddeZ{GdedfdfeZ|GdgdhdheZ}GdidjdjeZ~GdkdldleZGdmdndne~eeZGdodpdpe}eeZGdqdrdreZedsdtduZedvdtduZedwdpdZZdxZdyedz<Gd{d|d|eeZGd}d~d~eeZGdddeZGdddeZejdejdejdejdejdejdejdejdejdejdi Zded<dddZdddZdddZdddZdddZdddZdddZdddZdddZdddZedddZedddZedddZedddZedddZedddZedddZdddZddd҄ZdddׄZdddۄZ dddܜdddZdddZdddZdddZdddZdddZdddZdddZdddZdÐddZdĐd d ZdŐddZdƐddZdǐddZdȐddZdɐddZdʐddZdːd!d"Zd̐d%d&Zd͐d'd(Zdΐd+d,Zdϐd1d2Zd3d4d5dАd9d:Zdѐd?d@ZdҐdCdDZdӐdGdHZdԐdIdJZdՐdPdQZd֐dYdZZdאd\d]Zdؐd`daZÐdِdcddZĐdڐdfdgZŐdېdjdkZƐdܐdndoZǐdݐdrdsZȐdސdvdwZɐdߐdydzZʐdd|d}ZːdddZ̐dddZ͐dddZΐdddZϐdddZerddlZejҐdkrddlmZnddlDmZndddZGdddZԐdddZGdddZ֐dddZdS() annotationsN)timezone)Enum)autowraps) find_spec)getattr_static) token_hex) TYPE_CHECKING)Any)Callable) Container)Iterable)Literal)Protocol)Sequence)TypeVar)Union)cast)overload)warn)get_cudf)get_dask)get_dask_dataframe) get_duckdb)get_ibis) get_modin) get_numpy) get_pandas) get_polars) get_pyarrow) get_pyspark)get_pyspark_sql) get_sqlframe)is_cudf_series)is_modin_series)is_narwhals_series)is_numpy_array_1d)is_pandas_dataframe)is_pandas_like_dataframe)is_pandas_like_series)is_pandas_series)is_polars_series)is_pyarrow_chunked_array)ColumnNotFoundError)DuplicateError)InvalidOperationError) ModuleType) AbstractSet) Concatenate) LiteralString) ParamSpec)Self) TypeAlias)TypeIs) CompliantExpr)CompliantExprT)CompliantFrameT)CompliantSeriesOrNativeExprT_co)CompliantSeriesT)NativeFrameT_co)NativeSeriesT_co) EvalNames)EagerAllowedImplementation Namespace)ArrowStreamExportable)IntoArrowTable DataFrame LazyFrameDTypeSeries)CompliantDataFrame)CompliantLazyFrame)CompliantSeries) DataFrameLike)DTypes) IntoSeriesT)MultiIndexSelector)SingleIndexSelector)SizedMultiIndexSelector)SizeUnit)SupportsNativeNamespace)TimeUnit)_1DArray) _SliceIndex) _SliceName) _SliceNoneFrameOrSeriesT)bound_T_T1_T2_T3_FnzCallable[..., Any]PRc@eZdZUded<dS)_SupportsVersionstr __version__N__name__ __module__ __qualname____annotations__rqrqB/var/www/vscode/kcb/lib/python3.10/site-packages/narwhals/utils.pyrins ric@seZdZd d ddZdS) _SupportsGetNinstancer owner Any | NonereturncCdSNrq)selfrtrurqrqrr__get__rsz_SupportsGet.__get__ry)rtr rurvrwr )rmrnror{rqrqrqrrrsqsrsc@rh)_StoresImplementationImplementation_implementationNrlrqrqrqrrr|t r|c@rh)_StoresBackendVersiontuple[int, ...]_backend_versionNrlrqrqrqrrrxrrc@rh)_StoresVersionVersion_versionNrlrqrqrqrrr|rrc@eZdZdZdS)_LimitedContextzRProvides 2 attributes. - `_backend_version` - `_version` Nrmrnro__doc__rqrqrqrrrrc@r) _FullContextznProvides 3 attributes. - `_implementation` - `_backend_version` - `_version` Nrrqrqrqrrrrrc@seZdZedddZdS)_StoresColumnsrw Sequence[str]cCrxryrqrzrqrqrrcolumnsz_StoresColumns.columnsN)rwr)rmrnropropertyrrqrqrqrrrsr NativeT_coT) covariant CompliantT_co _ContextTz&Callable[Concatenate[_ContextT, P], R]r8_Methodc@eZdZdZedddZdS) _StoresNativezProvides access to a native object. Native objects have types like: >>> from pandas import Series >>> from pyarrow import Table rwrcCdS)zReturn the native object.Nrqrrqrqrrnativez_StoresNative.nativeN)rwr)rmrnrorrrrqrqrqrrrrc@r)_StoresCompliantzProvides access to a compliant object. Compliant objects have types like: >>> from narwhals._pandas_like.series import PandasLikeSeries >>> from narwhals._arrow.dataframe import ArrowDataFrame rwrcCr)zReturn the compliant object.Nrqrrqrqrr compliantrz_StoresCompliant.compliantN)rwr)rmrnrorrrrqrqrqrrrrrc@seZdZeZeZdS)rN)rmrnrorV1MAINrqrqrqrrrs rc@s,eZdZdZeZ eZ eZ eZ eZ eZ eZ eZ eZ eZ eZ ed3ddZed4d d Zed5ddZd6ddZd7ddZd7ddZd7ddZd7ddZd7ddZd7ddZd7d d!Zd7d"d#Zd7d$d%Zd7d&d'Zd7d(d)Zd7d*d+Z e!d8d-d.Z"d9d0d1Z#d2S):r}z?Implementation of native object (pandas, Polars, PyArrow, ...).cls type[Self]native_namespacer2rwcCsbttjttjttjttjt tj t tj t tjttjttjttji }||tjS)zInstantiate Implementation object from a native namespace module. Arguments: native_namespace: Native namespace. Returns: Implementation. )rr}PANDASrMODINrCUDFr!PYARROWr#PYSPARKr POLARSrDASKrDUCKDBrIBISr$SQLFRAMEgetUNKNOWN)rrmappingrqrqrrfrom_native_namespaces  z$Implementation.from_native_namespace backend_namerjc Cs<tjtjtjtjtjtjtjtjtj tj d }| |tj S)zInstantiate Implementation object from a native namespace module. Arguments: backend_name: Name of backend, expressed as string. Returns: Implementation. ) pandasmodincudfpyarrowpysparkpolarsdaskduckdbibissqlframe) r}rrrrrrrrrrrr)rrrrqrqrr from_strings  zImplementation.from_stringbackend!str | Implementation | ModuleTypecCs,t|tr ||St|tr|S||S)zInstantiate from native namespace module, string, or Implementation. Arguments: backend: Backend to instantiate Implementation from. Returns: Implementation. ) isinstancerjrr}r)rrrqrqrr from_backend s zImplementation.from_backendc Cs|tjur ddl}|S|tjurddl}|jS|tjur"ddl}|S|tjur-ddl}|S|tj ur9ddl }|j S|tj urDddl }|S|tjurPddl}|jS|tjur[ddl}|S|tjurfddl} | Sd} t| )zyReturn the native namespace module corresponding to Implementation. Returns: Native module. rNzNot supported Implementation)r}rrr modin.pandasrrrrr pyspark.sqlsqlrrrdask.dataframe dataframerrrrAssertionError) rzpdrrparplrrrmsgrqrqrrto_native_namespace s:         z"Implementation.to_native_namespaceboolcC |tjuS)a^Return whether implementation is pandas. Returns: Boolean. 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 )r}rrrqrqrr is_pandasP zImplementation.is_pandascCs|tjtjtjhvS)asReturn whether implementation is pandas, Modin, or cuDF. Returns: Boolean. 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 )r}rrrrrqrqrris_pandas_like`s zImplementation.is_pandas_likecCs|tjtjhvS)apReturn whether implementation is pyspark or sqlframe. Returns: Boolean. 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 )r}rrrrqrqrr is_spark_liketszImplementation.is_spark_likecCr)a^Return whether implementation is Polars. Returns: Boolean. 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 )r}rrrqrqrr is_polarsrzImplementation.is_polarscCr)a[Return whether implementation is cuDF. Returns: Boolean. 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 )r}rrrqrqrris_cudfrzImplementation.is_cudfcCr)a]Return whether implementation is Modin. Returns: Boolean. 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 )r}rrrqrqrris_modinrzImplementation.is_modincCr)aaReturn whether implementation is PySpark. Returns: Boolean. 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 )r}rrrqrqrr is_pysparkrzImplementation.is_pysparkcCr)aaReturn whether implementation is PyArrow. Returns: Boolean. 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 )r}rrrqrqrr is_pyarrowrzImplementation.is_pyarrowcCr)a[Return whether implementation is Dask. Returns: Boolean. 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 )r}rrrqrqrris_daskrzImplementation.is_daskcCr)a_Return whether implementation is DuckDB. Returns: Boolean. 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 )r}rrrqrqrr is_duckdbrzImplementation.is_duckdbcCr)a[Return whether implementation is Ibis. Returns: Boolean. 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 )r}rrrqrqrris_ibisrzImplementation.is_ibiscCr)acReturn whether implementation is SQLFrame. Returns: Boolean. 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 )r}rrrqrqrr is_sqlframerzImplementation.is_sqlframer5cCsHtjdtjdtjdtjdtjdtjdtjdtjdtj d tj d i }||S) zHFriendly name for errors. Returns: String. PandasPolarsDaskIbisModincuDFPyArrowPySparkDuckDBSQLFrame) r}rrrrrrrrrr)rzrrqrqrr_aliass zImplementation._aliasrcCsn|}|tjtjtjhvr|}t |S|tjur t}t |S|tjur,t}t |Sddl}|j}t |SNr) rr}rrrr"rsqlframe._versionr parse_version)rzr into_versionrrqrqrrr)s"  zImplementation._backend_versionN)rrrr2rwr})rrrrjrwr})rrrrrwr})rwr2)rwr)rwr5)rwr)$rmrnrorrrrrrrrrrrrr classmethodrrrrrrrrrrrrrrrrrrrrqrqrqrrr}s\     0            r})r) ) )r)rr)i))rrz%dict[Implementation, tuple[int, ...]] MIN_VERSIONSimplementationbackend_versionrrwNonecCs2|t|}krd|d|d|}t|dS)NzMinimum version of z supported by Narwhals is z , found: )r ValueError)rr min_versionrrqrqrrvalidate_backend_versionKsrversionrScCsF|tjur ddlm}|S|tjurddlm}|Sd|}t|)Nr)dtypesCongratulations, you have entered unreachable code. Please report an issue at https://github.com/narwhals-dev/narwhals/issues. Version: )rrnarwhalsrrnarwhals.stable.v1r)rr v1_dtypesrrqrqrrimport_dtypes_moduleSs    robjVersion | _StoresVersioncCs<t|tr|St|dr|jSdtdt|j}t|)Nrz Expected z but got )rr_hasattr_staticrtyperm TypeError)rrrqrqrr _into_versiones  r type[Namespace[Any]]cCsNt|}|tjurddlm}|S|tjurddlm}|Sd|}t|)NrrCr)r rrnarwhals._namespacerDrnarwhals.stable.v1._namespacer)rrDrrqrqrrimport_namespacens    rtextrjprefixcCs||r |t|dS|Sry) startswithlen)rrrqrqrr remove_prefixs rsuffixcCs ||r|dt| S|Sry)endswithr)rrrqrqrr remove_suffixs rargsr list[Any]cCs*tt|dkrt|dr|dS|S)Nrr)listr _is_iterable)rrqrqrrflattens*rargcCst|ttfs |fS|Sry)rrtuple)rrqrqrrtupleifysrAny | Iterable[Any]rcCsddlm}t|st|rdt|d}t|t}dur:t||j|j|j |j fr:dt|d}t|t|t oGt|t t |f S)NrrMz(Expected Narwhals class or scalar, got: z2. Perhaps you forgot a `nw.from_native` somewhere?z`. Hint: Perhaps you - forgot a `nw.from_native` somewhere? - used `pl.col` instead of `nw.col`?)narwhals.seriesrNr)r,r r r rExprrHrJrrjbytes)rrNrrrqrqrrrs r#str | ModuleType | _SupportsVersioncCs:t|tr|n|j}tdd|}tdd|dDS)zSimple version parser; split into a tuple of ints for comparison. Arguments: version: Version string, or object with one, to parse. Returns: Parsed version number. z (\D?dev.*$)css"|] }ttdd|VqdS)z\Dr%N)intresub).0vrqrqrr s z parse_version...)rrjrkr'r(rsplit)r version_strrqrqrrrs r obj_or_clsr  cls_or_tupletype[_T]TypeIs[type[_T]]cCrxryrqr/r0rqrqrrisinstance_or_issubclassrr4 object | typeTypeIs[_T | type[_T]]cCrxryrqr3rqrqrrr4rtuple[type[_T1], type[_T2]]TypeIs[type[_T1 | _T2]]cCrxryrqr3rqrqrrr4r#TypeIs[_T1 | _T2 | type[_T1 | _T2]]cCrxryrqr3rqrqrrr4r&tuple[type[_T1], type[_T2], type[_T3]]TypeIs[type[_T1 | _T2 | _T3]]cCrxryrqr3rqrqrrr4r/TypeIs[_T1 | _T2 | _T3 | type[_T1 | _T2 | _T3]]cCrxryrqr3rqrqrrr4rtuple[type, ...] TypeIs[Any]cCrxryrqr3rqrqrrr4rcCs>ddlm}t||rt||St||pt|tot||S)NrrK)narwhals.dtypesrLrr  issubclass)r/r0rLrqrqrrr4s    items Iterable[Any]csdddlmddlmtfdd|Ds"tfdd|Dr$dSddd |D}t|) NrrGrIc3|]}t|VqdSryrr)itemrGrqrrr+z$validate_laziness..c3rCryrDrErIrqrrr+rGzGThe items to concatenate should either all be eager, or all lazy, got: cSsg|]}t|qSrq)r rErqrqrr sz%validate_laziness..)narwhals.dataframerHrJallr )rArrq)rHrJrrvalidate_lazinesss  rKlhsrhs-Series[Any] | DataFrame[Any] | LazyFrame[Any]cCsddlm}ddlm}ddd }td|}td|}tt|d d |rLtt|d d |rL||jjj ||jjj | |j |jjj |jjj Stt|d d |r}tt|d d |r}||jjj ||j jj | |j |jjj |j jj Stt|d d |rtt|d d |r||j jj ||jjj | |j |j jj |jjj Stt|d d |rtt|d d |r||j jj ||j jj | |j |j jj |j jj St|t|krd t|dt|}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. Returns: Same type as input. 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)PandasLikeSeriesindexr rwrcSs|js d}t|dS)Nz'given index doesn't have a unique index) is_uniquer)rQrrqrqrr_validate_index sz*maybe_align_index.._validate_index_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )rQr rwr)narwhals._pandas_like.dataframerOnarwhals._pandas_like.seriesrPrrgetattrrTrrQ_with_compliant _with_nativelocrUrr)rLrMrOrPrSlhs_anyrhs_anyrrqrqrrmaybe_align_indexs~ !        r^-DataFrame[Any] | LazyFrame[Any] | Series[Any]rvcCs,td|}|}t|st|r|jSdS)aGet the index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: Dataframe or Series. Returns: Same type as input. 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) r N)r to_nativer*r+rQ)robj_any native_objrqrqrrmaybe_get_index[s rc)rQ column_namesstr | list[str] | NonerQ6Series[IntoSeriesT] | list[Series[IntoSeriesT]] | Nonecsddlmtd|}|}|dur|durd}t||s)|dur)d}t||durAt|r:fdd|Dn|d d }n|}t|rS||j| |St |rzdd l m }|red }t|||||j j |j jd }||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. Returns: Same type as input. Raises: ValueError: If one of the following condition 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 rr`r Nz8Only one of `column_names` or `index` should be providedz3Either `column_names` or `index` should be providedcsg|]}|ddqS)T pass_throughrq)r)idxrgrqrrrHz#maybe_set_index..Trh) set_indexz/Cannot set index using column names on a Series)rr)narwhals.translater`rrrr*rYrTrZrlr+narwhals._pandas_like.utilsrUr~r)rrdrQdf_anyrbrkeysrlrqrgrrmaybe_set_indexs@ /    rqcCstd|}|}t|r%|}t||r|S||j|jddSt |rA|}t||r4|S||j |jddS|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. Returns: Same type as input. 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) r T)drop) rr`r*__native_namespace___has_default_indexrYrTrZ reset_indexr+rU)rrarbrrqrqrrmaybe_reset_indexs"   rvrTypeIs[pd.RangeIndex]cCs t||jSry)r RangeIndex)rrrqrqrr_is_range_index s rynative_frame_or_seriespd.Series[Any] | pd.DataFramecCs2|j}t||o|jdko|jt|ko|jdkS)Nrr)rQrystartstoprstep)rzrrQrqrqrrrts  rtkwargs bool | strcOsbtd|}|}t|r||j|j|i|St|r/||j|j|i|S|S)aWConvert 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. Returns: Same type as input. 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 ) rr`r*rYrTrZconvert_dtypesr+rU)rrrrarbrqrqrrmaybe_convert_dtypess $rszr&unitrX int | floatcCs^|dvr|S|dvr|dS|dvr|dS|dvr|dS|dvr&|d 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 Returns: Integer or float. >br#>kb kilobytesi>mb megabytesi>gb gigabytesi@>tb terabyteslz9`unit` must be one of {'b', 'kb', 'mb', 'gb', 'tb'}, got )r)rrrrqrqrr scale_bytesRs  rseries Series[Any]cCsddlm}t|jj}t|j|r|j|jkr|jjj dS|j|j kr'dS|j|jkr/dS| }t |r=|jj dkSt|rGt|jjSt|rO|jjSt|rW|jjSt|rjddlm}||joi|jjSdS)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. Returns: Whether the Series is an ordered categorical. 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="physical")) 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) True r)InterchangeSeries is_orderedTFphysical) is_dictionary)narwhals._interchange.seriesrrrUrrdtype Categoricalrdescribe_categoricalrr`r-orderingr,rcatorderedr&r%r.narwhals._arrow.utilsrr )rrr native_seriesrrqrqrris_ordered_categoricalks. *        rn_bytesrrcCsd}t|ddt||dS)Nz}Use `generate_temporary_column_name` instead. `generate_unique_token` is deprecated and it will be removed in future versions1.13.0r)rr)issue_deprecation_warninggenerate_temporary_column_name)rrrrqrqrrgenerate_unique_tokens  rcCsDd} t|}||vr |S|d7}|dkr!d|d|}t|q)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. 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 rTrdzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in )r r)rrcountertokenrrqrqrrrsrcompliant_frame Iterable[str]strict list[str]csT|jt|}|rfdd|D}|rtj|d|Sttt|}|S)Ncg|]}|vr|qSrqrq)r)xcolsrqrrrHrkz)parse_columns_to_drop..)missing_columnsavailable_columns)rrr/'from_missing_and_available_column_namesset intersection)rrrto_droprrqrrrparse_columns_to_dropsrsequenceSequence[_T] | AnyTypeIs[Sequence[_T]]cCst|to t|t Sry)rrrj)rrqrqrris_sequence_but_not_strrTypeIs[_SliceNone]cCst|to |tdkSry)rslicerrqrqrr is_slice_nonerr$TypeIs[SizedMultiIndexSelector[Any]]cCsft}t|ot|dkrt|dtpt|dkp2t|o%||j|jp2t |s.t |o2|j Sr) rrrrr&r( issubdtyperintegerr'is_compliant_series is_integer)rnprqrqrris_sized_multi_index_selectors$r-TypeIs[Sequence[_T] | Series[Any] | _1DArray]cCs t|pt|pt|pt|Sry)rr(r'rrrqrqrris_sequence_like srTypeIs[_SliceIndex]cCsBt|to t|jtp t|jtp t|jto |jduo |jduSry)rrr|r&r}r~rrqrqrris_slice_indexs   r TypeIs[range]cCs t|tSry)rrangerrqrqrris_range rTypeIs[SingleIndexSelector]cCstt|to t|t Sry)rrr&rrqrqrris_single_index_selector#sr5TypeIs[SingleIndexSelector | MultiIndexSelector[Any]]cCst|p t|p t|Sry)rrrrrqrqrris_index_selector's rtpTypeIs[list[_T]]cCs tt|to|ot|d|Sr)rrr)rrrqrqrr is_list_of/s rcCsddl}ddlm}ddl}t||jj}|}d}z-|rE||}| |s7t |j dd}r?| dr?|j }|d7}nW~|S|s W~|S~w)zFind the first place in the stack that is not inside narwhals. Returns: Stacklevel. Taken from: https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51 rN)Path co_qualnamezsingledispatch.r) inspectpathlibrrrj__file__parent currentframegetfilerrXf_codef_back)rrnwpkg_dirframenfnamequalnamerqrqrrfind_stacklevel4s0     rmessagercCst|ttddS)zIssue a deprecation warning. Arguments: message: The message associated with the warning. _version: Narwhals version when the warning was introduced. Just used for internal bookkeeping. )rcategory stacklevelN)rDeprecationWarningr)rrrqrqrrr^sr bool | Noneripass_through_defaultemit_deprecation_warningcCsh|dur |dur |}|S|dur#|dur#|rd}t|dd| }|S|dur.|dur. |Sd}t|)Nz`strict` in `from_native` is deprecated, please use `pass_through` instead. Note: `strict` will remain available in `narwhals.stable.v1`. See https://narwhals-dev.github.io/narwhals/backcompat/ for more information. rrz,Cannot pass both `strict` and `pass_through`)rr)rrirrrrqrqrrvalidate_strict_and_pass_thoughis rr%F) warn_versionrequiredrr*Callable[[Callable[P, R]], Callable[P, R]]csdfdd }|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]rwcstd fdd }|S) NrP.argskwdsP.kwargsrwrgcs|dd}|dd}|dur!|dur!rd}t|d|}n#|dur/|dur/d}t||durD|durDrDdjd}t|||d<|i|S)Nrrz`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. rz0Can't pass both `native_namespace` and `backend`z `backend` must be specified in `z`.)poprrrm)rrrrr)rrrrqrrwrappers   z=deprecate_native_namespace..decorate..wrapper)rrrrrwrgr)rrrrrrrdecoratesz,deprecate_native_namespace..decorateN)rrrwrrq)rrrrqrrrdeprecate_native_namespaces r window_size min_samples int | Nonetuple[int, int]cCs|dkr d}t|t|ts|jj}d|d}t||durL|dkr+d}t|t|ts>|jj}d|d}t|||krHd}t|||fS|}||fS)Nrz+window_size must be greater or equal than 1zargument 'window_size': 'z,' object cannot be interpreted as an integerz+min_samples must be greater or equal than 1zargument 'min_samples': 'z6`min_samples` must be less or equal than `window_size`)rrr& __class__rmr r1)rrr_typerqrqrr_validate_rolling_argumentss.    rheader native_reprc Cs|ztj}Wntyttdd}Ynw|}tdd|D}|d|krt|t|}dd|d}|t|}|d d |d|d |d|dd 7}|d d |d 7}||d}||d||d} |D]} |d d || d | |t| d 7}qw|d d|d7}|Sdt|} dddd | d|d | d| dddd S)NCOLUMNSPcss|]}t|VqdSry)r)r)linerqrqrrr+sz generate_repr..u┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorr&getenv splitlinesmaxr) rrterminal_width native_linesmax_native_widthlengthoutput header_extra start_extra end_extrar diffrqrqrr generate_reprs<   0 .  rsubsetSequence[str] | NonecCs>|durt||}rdt|d|}t|dSdS)Nz Column(s) z not found in )r differencesortedr/)rrmissingrrqrqrrcheck_column_existssr$cCsltt|}t||kr4ddlm}||}dd|D}ddd|D}d|}t|dS) Nr)CountercSsi|] \}}|dkr||qSrrqr)kr*rqrqrr sz1check_column_names_are_unique..r%css&|]\}}d|d|dVqdS)z - 'z' z timesNrqr&rqrqrrr+s$z0check_column_names_are_unique..z"Expected unique column names, got:)rr collectionsr%rAjoinr0)rlen_unique_columnsr%r duplicatesrrqrqrrcheck_column_names_are_uniques    r- time_unit$TimeUnit | Iterable[TimeUnit] | None time_zone7str | timezone | Iterable[str | timezone | None] | None%tuple[Set[TimeUnit], Set[str | None]]cCsd|durhdn t|tr|hnt|}|durdhnt|ttfr't|hndd|D}||fS)N>smsnsuscSs h|] }|dur t|ndqSry)rj)r)tzrqrqrr s z1_parse_time_unit_and_time_zone..)rrjrr)r.r0 time_units time_zonesrqrqrr_parse_time_unit_and_time_zones   r;rrLrr9 Set[TimeUnit]r:Set[str | None]cCs2t||jo|j|vo|j|vpd|vo|jduS)N*)rDatetimer.r0)rrr9r:rqrqrr%dtype_matches_time_unit_and_time_zones  r@rcCs|jSryr)rrqrqrrget_column_names"srBnamesContainer[str]csfdd|jDS)Ncrrqrq)r)col_namerCrqrrrH'rkz(exclude_column_names..rA)rrCrqrFrrexclude_column_names&srGEvalNames[Any]csdfdd }|S)N_framer rwrcsSryrq)rIrFrqrrr+rz$passthrough_column_names..fn)rIr rwrrq)rCrrqrFrrpassthrough_column_names*srJattrcCst}t||||uSry)objectr )rrKsentinelrqrqrrr1srKCompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeFrameT_co] | AnyMTypeIs[CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeFrameT_co]]cC t|dS)N__narwhals_dataframe__rrrqrqrris_compliant_dataframe6 rS9CompliantLazyFrame[CompliantExprT, NativeFrameT_co] | Any;TypeIs[CompliantLazyFrame[CompliantExprT, NativeFrameT_co]]cCrP)N__narwhals_lazyframe__rRrrqrqrris_compliant_lazyframe<rTrX'CompliantSeries[NativeSeriesT_co] | Any)TypeIs[CompliantSeries[NativeSeriesT_co]]cCrP)N__narwhals_series__rRrrqrqrrrBrTrECompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co] | AnyGTypeIs[CompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co]]cCrP)N__narwhals_expr__hasattrrrqrqrris_compliant_exprHrTra"TypeIs[EagerAllowedImplementation]cCs|tjtjtjtjtjhvSry)r}rrrrrrrqrqrris_eager_allowedNsrcTypeIs[SupportsNativeNamespace]cCrP)Nrsr_rrqrqrrhas_native_namespaceXrreTypeIs[DataFrameLike]cCrP)N __dataframe__r_rrqrqrr_supports_dataframe_interchange\rrhTypeIs[ArrowStreamExportable]cCrP)N__arrow_c_stream__rRrrqrqrrsupports_arrow_c_stream`rrkleft_onright_ondict[str, str]cs"fdd|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. c3s(|]}|vr|n|VqdSryrq)r)keyrlrrqrrr+ts z(_remap_full_join_keys..)dictzip)rlrmrright_keys_suffixedrqrprr_remap_full_join_keysds rtdatarFcontextpa.TablecCs^tdr"ddl}ddlm}|j}|t||d}|jj||djSdt |j d}t |) zGuards `ArrowDataFrame.from_arrow` w/ safer imports. Arguments: data: Object which implements `__arrow_c_stream__`. context: Initialized compliant object. Returns: A PyArrow Table. rrN)ArrowNamespace)rr)rvz@PyArrow>=14.0.0 is required for `from_arrow` for object of type r,) rrnarwhals._arrow.namespacerxrr _dataframe from_arrowrr rmModuleNotFoundError)rurvrrxrr5rrqrqrr_into_arrow_tablezs  r}rcC|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) rqrrqrqrrunstablesr)r  deprecatedCallable[[_Fn], _Fn]cCsddd}|S)NfuncrerwcSr~ryrq)rrqrqrrrrzdeprecated..wrapper)rrerwrerq)rrrqrqrrrs rc@sVeZdZdZd d!ddZd"d d Zd#ddZ d d$ddZd%ddZe d&ddZ 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 | NonerwrcCs ||_dSry)r)rzrrqrqrr__init__rTznot_implemented.__init__rjcCs dt|jd|jd|jS)N: r,)r rm _name_owner_namerrqrqrr__repr__s znot_implemented.__repr__rur1namecCs|j|_|jp||_dSry)rmrrr)rzrurrqrqrr __set_name__sznot_implemented.__set_name__rt_T | Literal['raise'] | Nonetype[_T] | Noner cCs&|dur|St|d|j}t|j|)Nr~)rXr_not_implemented_errorr)rzrtruwhorqrqrrr{s znot_implemented.__get__rrcOs |dS)Nraise)r{)rzrrrqrqrr__call__rTznot_implemented.__call__rr5r7cCs|}t||S)aAlt constructor, wraps with `@deprecated`. Arguments: message: **Static-only** deprecation message, emitted in an IDE. Returns: An exception-raising [descriptor]. [descriptor]: https://docs.python.org/3/howto/descriptor.html r)rrrrqrqrrrs znot_implemented.deprecatedry)rrrwr)rwrj)rur1rrjrwr)rtrrurrwr )rr rr rwr )rr5rwr7) rmrnrorrrrr{rrrrqrqrqrrrs $   rwhatrNotImplementedErrorcCs|d|d}t|S)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)r)rrrrqrqrrrsrc@sTeZdZUdZded<ded<eddd d ZedddZdddZ dddZ 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_versionrj_hintr%hintminimumrwr7cCs||}||_||_|S)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. Returns: An exception-raising decorator. )__new__rr)rrrrrqrqrrr3s zrequires.backend_versionrcCsddd|DS)Nr,css|]}|VqdSryrq)r)drqrqrrr+Esz,requires._unparse_version..)r*)rrqrqrr_unparse_versionCszrequires._unparse_versionrtrrc Csr|j|jkrdS|j}|jj}||j}||j}d|d|d|d|d }|jr5|d|j}t|)N`z` is only available in z>=z, found version r, )rr _wrapped_namer~rrrr)rzrtmethodrrfoundrrqrqrr_ensure_versionGs   zrequires._ensure_versionr_Method[_ContextT, P, R]cs$j_td fd d }|S) Nrtrrrrrrwrgcs ||g|Ri|Sry)r)rtrrrrzrqrrrVs z"requires.__call__..wrapper)rtrrrrrrwrg)rmrr)rzrrrqrrrrSszrequires.__call__N)r%)rrjrrrwr7)rrrwrj)rtrrwr)rrrwr) rmrnrorrprr staticmethodrrrrqrqrqrrrs    r str_slicer]"tuple[int | None, int | None, Any]cCsH|jdur ||jnd}|jdur||jdnd}|j}|||fS)Nr)r|rQr}r~)rrr|r}r~rqrqrrconvert_str_slice_to_int_slice_s r)rr}rrrwr)rrrwrS)rrrwr)rrrwr )rrjrrjrwrj)rrjrrjrwrj)rr rwr)rr rwr )rr rwr)rr$rwr)r/r r0r1rwr2)r/r5r0r1rwr6)r/r r0r7rwr8)r/r5r0r7rwr9)r/r r0r:rwr;)r/r5r0r:rwr<)r/r r0r=rwr>)r/r r0r rwr)rArBrwr)rLr_rMrNrwr_)rr_rwrvry)rr_rdrerQrfrwr_)rr_rwr_)rr rr rwrw)rzr{rr rwr)rr_rrrrrwr_)rr&rrXrwr)rrrwr)rr&rrrwrj)rr rrrrrwr)rrrwr)rr rwr)rr rwr)rrrwr)rr rwr)rr rwr)rr rwr)rr rwr)rr rr1rwr)rwr&)rrjrrjrwr) rrrirrrrrrwr)rrjrrrwr)rr&rrrwr)rrjrrjrwrj)rrrr rwr)rrrwr)r.r/r0r1rwr2) rrLrrSr9r<r:r=rwr)rrrwr)rrrCrDrwr)rCrrwrH)rr rKrjrwr)rrNrwrO)rrUrwrV)rrYrwrZ)rr\rwr])rr}rwrb)rr rwrd)rr rwrf)rr rwri)rlrrmrrrjrwrn)rurFrvrrwrw)rrerwre)rrjrwr)rrjrrjrwr)rr]rrrwr) __future__rrr'datetimerenumrr functoolsrimportlib.utilrrr secretsr typingr r r rrrrrrrrrwarningsrnarwhals.dependenciesrrrrrrrrr r!r"r#r$r%r&r'r(r)r*r+r,r-r.narwhals.exceptionsr/r0r1typesr2r3Setrrrrtyping_extensionsr4r5r6r7r8r9narwhals._compliantr:r;r<r=r>r?r@narwhals._compliant.typingrAr rBrDnarwhals._translaterErFrIrHrJr?rLr!rNnarwhals.typingrOrPrQrRrSrTrUrVrWrXrYrZr[r\r]r^r_rarbrcrdrerfrgrirsr|rrrrrrrrrrprrrr}rrrrrrrrrrrrrr rrrrrrrr4rKr^rcrqrvryrtrrrrrrrrrrrrrrrrrrrrrr$r-r;r@rBrGrJrrSrXrrarcrerhrkrtr}rsys version_inforrrrrrqrqrqrrs                                                                                                      _& [ 2  5 H % * )$   T F