U )3g:Y@s0ddlmZddlZddlmZddlmZddlmZddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZdd lmZdd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z ddlm!Z!ddl"m#Z#e rddl$m%Z%ddl&Z'ddl(m)Z)ddl(m*Z*dd l+m,Z,dd!l-m.Z.e d"Z/Gd#d$d$eZ0d%d%d%d&d'd(Z1d%d%d%d)d*d+Z2d,d-d.d/d0Z3d,d,d1d2d3Z4d4d5d1d6d7Z5d8d9d:d;d<Z6d,d,d5d=d>d?Z7d@dAdBdCdDZ8d"dEd"dFdGdHZ9d"dIdJdKdLZ:d"dMd"dNdOdPZ;d"d"dJdQdRZd[d5d\d]d^Z?d_d`d%dadbdcZ@d_d`d%dadddeZAd,dfd5d`dgdhdiZBd,djdkdldmZCd_dndodpZDd%d%dAdqdrdsZEdtdtd5d5d5dudvdwZFdS)x) annotationsN)Enum)auto) token_hex) TYPE_CHECKING)Any)Iterable)Sequence)TypeVar)cast)warn)ColumnNotFoundError)get_cudf)get_dask_dataframe) get_modin) get_pandas) get_polars) get_pyarrow)is_cudf_series)is_modin_series)is_pandas_dataframe)is_pandas_like_dataframe)is_pandas_like_series)is_pandas_series)is_polars_series)is_pyarrow_chunked_array) to_native) ModuleType)Self) TypeGuard) BaseFrameSeriesTc@s\eZdZeZeZeZeZeZeZ eZ e ddddddZ ddddd Z d S) Implementationz type[Self]r)clsnative_namespacereturnc CsBttjttjttjttjt tj t tj i}| |tjS)zAInstantiate Implementation object from a native namespace module.)rr$PANDASrMODINrCUDFrPYARROWrPOLARSrDASKgetUNKNOWN)r%r&mappingr12/tmp/pip-unpacked-wheel-hfsjijke/narwhals/utils.pyfrom_native_namespace7sz$Implementation.from_native_namespacer)selfr'c Cs<tjttjttjttjttj t tj t i}||S)zCReturn the native namespace module corresponding to Implementation.) r$r(rr)rr*rr+rr,rr-r)r4r0r1r1r2to_native_namespaceFsz"Implementation.to_native_namespaceN)__name__ __module__ __qualname__rr(r)r*r+r,r-r/ classmethodr3r5r1r1r1r2r$-sr$str)textprefixr'cCs||r|t|dS|SN) startswithlen)r;r<r1r1r2 remove_prefixSs r@)r;suffixr'cCs ||r|dt| S|Sr=)endswithr?)r;rAr1r1r2 remove_suffixYs rCrz list[Any])argsr'cCs,|sgSt|dkr(t|dr(|dS|S)Nr)r? _is_iterable)rDr1r1r2flatten_s rG)argr'cCst|ttfs|fS|Sr=) isinstancelisttuple)rHr1r1r2tupleifygsrLzAny | Iterable[Any]boolcCsddlm}t|st|r4dt|d}t|t}dk rtt||j|j|j |j frtdt|d}t|t|t ot|t t |f S)Nrr!z(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.seriesr"rrtype TypeErrorrrIZExpr DataFrame LazyFramerr:bytes)rHr"msgplr1r1r2rFms rFzSequence[str | int]ztuple[int, ...])versionr'cCs&t|tr|d}tdd|DS)zASimple version parser; split into a tuple of ints for comparison..css$|]}ttddt|VqdS)z\DN)intresubr:).0vr1r1r2 sz parse_version..)rIr:splitrK)rVr1r1r2 parse_versions  r`)objr%r'cCs4ddlm}t||r t||St||p2t||S)Nr)DType)Znarwhals.dtypesrbrI issubclass)rar%rbr1r1r2isinstance_or_issubclasss   rdz Iterable[Any]None)itemsr'csXddlmddlmtfdd|DsDtfdd|DrHdSd}t|dS)NrrQrRc3s|]}t|VqdSr=rIr\itemrgr1r2r^sz$validate_laziness..c3s|]}t|VqdSr=rirjrhr1r2r^sz@The items to concatenate should either all be eager, or all lazy)narwhals.dataframerQrRallNotImplementedError)rfrTr1)rQrRr2validate_lazinesss  rozSeries | BaseFrame[Any])lhsrhsr'cCsddlm}ddlm}ddddd}tt|}tt|}tt|d d |rtt|d d |r||jj j ||jj j | |j |jj j |jj j Stt|d d |rtt|d d |r||jj j ||jjj | |j |jj j |jjj Stt|d d |rjtt|d d |rj||jjj ||jj j ||j|jjj |jj j Stt|d d |rtt|d d |r||jjj ||jjj ||j|jjj |jjj St|t|krd t|d t|}t||S)aO Align `lhs` to the Index of `rhs`, if they're both pandas-like. 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)PandasLikeSeriesrre)indexr'cSs|jsd}t|dS)Nz'given index doesn't have a unique index)Z is_unique ValueError)rtrTr1r1r2_validate_indexsz*maybe_align_index.._validate_index_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )Znarwhals._pandas_like.dataframerrZnarwhals._pandas_like.seriesrsr rrIgetattrrwZ _native_framert_from_compliant_dataframe_from_native_framelocrx_native_series_from_compliant_series_from_native_seriesr?ru)rprqrrrsrvZlhs_anyZrhs_anyrTr1r1r2maybe_align_indexs        rz Any | None)rar'cCs,tt|}t|}t|s"t|r(|jSdS)ae Get the index of a DataFrame or a Series, if it's pandas-like. 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) N)r rrrrrt)raobj_any native_objr1r1r2maybe_get_indexs  rzstr | list[str])df column_namesr'cCs6tt|}t|}t|r2||j||S|S)a Set columns `columns` to be the index of `df`, if `df` is pandas-like. 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 rrrrzrwr{Z set_index)rrZdf_anyZ native_framer1r1r2maybe_set_indexs rcCstt|}t|}t|rJ|}t||r0|S||j|j ddSt |r|}t||rh|S| |j |j ddS|S)a Reset the index to the default integer index of a DataFrame or a Series, if it's pandas-like. 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) T)Zdrop)r rrrZ__native_namespace___has_default_indexrzrwr{Z reset_indexrr~rxr)rarrr&r1r1r2maybe_reset_index7s&    rzpd.Series | pd.DataFrame)native_frame_or_seriesr&r'cCs4|j}t||jo2|jdko2|jt|ko2|jdkS)NrrE)rtrIZ RangeIndexstartstopr?step)rr&rtr1r1r2rfs  rz bool | str)rarDkwargsr'cOsZtt|}t|}t|r4||j|j||St|rV| |j |j||S|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 rrrrzrwr{Zconvert_dtypesrr~rxr)rarDrrrr1r1r2maybe_convert_dtypesrs   rr")seriesr'cCsddlm}|jj}t|j|r:|j|jkr:|jjjdS|j|j krJdS|j|jkrZdSt |}t |rv|jj dkSt |r|jjSt|r|jjSt|r|jjSt|r|jjSdS)a Return 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`. 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)InterchangeSeriesZ is_orderedTFZphysical)Znarwhals._interchange.seriesrrxZ_dtypesrIZdtypeZ Categoricalr}Zdescribe_categoricalrrrZorderingrcatZorderedrrrrO)rrZdtypesZ native_seriesr1r1r2is_ordered_categoricals2%      rrYz list[str])n_bytescolumnsr'cCstdtddt||dS)Nz}Use `generate_temporary_column_name` instead. `generate_unique_token` is deprecated and it will be removed in future versions) stacklevelrr)r DeprecationWarninggenerate_temporary_column_namerr1r1r2generate_unique_tokens rcCsFd}t|}||kr|S|d7}|dkrd|d|}t|qdS)aGenerates a unique token of specified `n_bytes` 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 rrEdzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in N)rAssertionError)rrcountertokenrTr1r1r2rsrz Iterable[str])compliant_framerstrictr'cCsTt|j}t|}|r>|D] }||krd|d}t|qnt|t|}|S)N"z " not found)setrrJr intersection)rrrcolsZto_dropdrTr1r1r2parse_columns_to_drops   rzTypeGuard[Sequence[Any]])sequencer'cCst|tot|t Sr=)rIr r:)rr1r1r2is_sequence_but_not_str&sr)r'cCsddl}ddlm}ddl}t||jj}|}d}zL|r||}| |snt |j dd}r| dr|j }|d7}q:qq:W5~X|S)z Find the first place in the stack that is not inside narwhals. Taken from: https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51 rN)PathZ co_qualnamezsingledispatch.rE) inspectpathlibrZnarwhalsr:__file__parent currentframegetfiler>ryf_codef_back)rrnwZpkg_dirframenfnamequalnamer1r1r2find_stacklevel*s(    r)message_versionr'cCst|ttddS)z Issue a deprecation warning. Parameters ---------- message The message associated with the warning. version Narwhals version when the warning was introduced. Just used for internal bookkeeping. )rcategoryrN)r rr)rrr1r1r2issue_deprecation_warningRs rz bool | None)r pass_throughpass_through_defaultemit_deprecation_warningr'cCsd|dkr|dkr|}nJ|dk rB|dkrB|r:d}t|dd| }n|dkrT|dk rTn d}t||S)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. z1.13.0)rz,Cannot pass both `strict` and `pass_through`)rru)rrrrrTr1r1r2validate_strict_and_pass_thoughas r)G __future__rrZenumrrZsecretsrtypingrrrr r r warningsr Znarwhals._exceptionsr Znarwhals.dependenciesrrrrrrrrrrrrrrZnarwhals.translatertypesrZpandaspdZtyping_extensionsrrrlr rNr"r#r$r@rCrGrLrFr`rdrorrrrrrrrrrrrrrr1r1r1r2st                                & Y"/ /C &(