o $&]i*<@sUdZddlmZddlmZmZmZmZddlm Z m Z m Z m Z m Z mZddlmZmZmZmZmZmZmZmZmZmZmZe rzddlZddlZddlZddl Z!ddl"m#Z$ddl%m&Z&m'Z'm(Z(e$e e e e e fZ)e d Z*d Z+d e,d <e Z-d e,d <gdZ.Gddde Z/Gdddee/e Z0Gddde/e Z1Gdddeee e Z2Gdddee Z3Gddde0e3e Z4Gddde2e3e Z5Gddde1e Z6Gdd d e4e Z7Gd!d"d"e5e Z8Gd#d$d$e/e Z9Gd%d&d&e4e Z:Gd'd(d(e5e Z;Gd)d*d*e1e Zd e,d.<d/Z?d e,d0<d1Z@d e,d2<d3ZAd e,d4<d5ZBd e,d6<d7ZCd e,d8<d9ZDd e,d:<d;ZEd e,d<<d=ZFd e,d><e DataFrame[IntoDataFrameT]: ... def wrapping_in_lf(native: IntoLazyFrameT) -> LazyFrame[IntoLazyFrameT]: ... def wrapping_in_ser(native: IntoSeriesT) -> Series[IntoSeriesT]: ... ### (1) `Native` Minimal [`Protocol`]s that are [assignable to] *almost any* supported native type of that group: class NativeThing(Protocol): def something_common(self, *args: Any, **kwargs: Any) -> Any: ... Note: This group is primarily a building block for more useful types. ### (2) `Into` *Publicly* exported [`TypeAlias`]s of **(1)**: IntoThing: TypeAlias = NativeThing **But**, occasionally, there'll be an edge-case which we can spell like: IntoThing: TypeAlias = Union[, NativeThing] Tip: Reach for these when there **isn't a need to preserve** the original native type. ### (3) `IntoT` *Publicly* exported [`TypeVar`]s, bound to **(2)**: IntoThingT = TypeVar("IntoThingT", bound=IntoThing) Important: In most situations, you'll want to use these as they **do preserve** the original native type. Putting it all together, we can now add a *narwhals-level* wrapper: class Thing(Generic[IntoThingT]): def to_native(self) -> IntoThingT: ... ## Matching to an `Implementation` This problem differs as we need to *create* a relationship between *otherwise-unrelated* types. Comparing the problems side-by-side, we can more clearly see this difference: def wrapping_in_df(native: IntoDataFrameT) -> DataFrame[IntoDataFrameT]: ... def matching_to_polars(native: pl.DataFrame) -> Literal[Implementation.POLARS]: ... ### (4) `Native` If we want to describe a set of specific types and **match** them in [`@overload`s], then these the tools we need. For common and easily-installed backends, [`TypeAlias`]s are composed of the native type(s): NativePolars: TypeAlias = pl.DataFrame | pl.LazyFrame | pl.Series Otherwise, we need to define a [`Protocol`] which the native type(s) can **match** against *when* installed: class NativeDask(NativeLazyFrame, Protocol): _partition_type: type[pd.DataFrame] Tip: The goal is to be as minimal as possible, while still being *specific-enough* to **not match** something else. Important: See [ibis#9276 comment] for a more *in-depth* example that doesn't fit here 😄 ### (5) `is_native_` [Type guards] for **(4)**, *similar* to those found in `nw.dependencies`. They differ by checking **all** native types/protocols in a single-call and using ``Native`` aliases. [structural]: https://typing.python.org/en/latest/spec/glossary.html#term-structural [nominal]: https://typing.python.org/en/latest/spec/glossary.html#term-nominal [Native types]: https://narwhals-dev.github.io/narwhals/how_it_works/#polars-and-other-implementations [Narwhals type]: https://narwhals-dev.github.io/narwhals/api-reference/dataframe/ [`Implementation`]: https://narwhals-dev.github.io/narwhals/api-reference/implementation/ [`Protocol`]: https://typing.python.org/en/latest/spec/protocol.html [assignable to]: https://typing.python.org/en/latest/spec/glossary.html#term-assignable [`TypeAlias`]: https://mypy.readthedocs.io/en/stable/kinds_of_types.html#type-aliases [`TypeVar`]: https://mypy.readthedocs.io/en/stable/generics.html#type-variables-with-upper-bounds [generic class]: https://docs.python.org/3/library/typing.html#user-defined-generic-types [`@overload`s]: https://typing.python.org/en/latest/spec/overload.html [ibis#9276 comment]: https://github.com/ibis-project/ibis/issues/9276#issuecomment-3292016818 [Type guards]: https://typing.python.org/en/latest/spec/narrowing.html ) annotations)Callable CollectionIterableSized) TYPE_CHECKINGAnyProtocolTypeVarUnioncast) get_cudf get_modin get_pandas get_polars get_pyarrowis_dask_dataframeis_duckdb_relation is_ibis_tableis_pyspark_connect_dataframeis_pyspark_dataframeis_sqlframe_dataframeN) BaseDataFrame)Self TypeAliasTypeIsTzCallable[[Any], TypeIs[T]]r_Guard Incomplete)+ IntoDataFrameIntoDataFrameT IntoFrame IntoFrameT IntoLazyFrameIntoLazyFrameT IntoSeries IntoSeriesT NativeAny NativeArrow NativeCuDF NativeDaskNativeDataFrame NativeDuckDB NativeFrame NativeIbis NativeKnownNativeLazyFrame NativeModin NativePandasNativePandasLikeNativePandasLikeDataFrameNativePandasLikeSeries NativePolars NativePySparkNativePySparkConnectNativeSQLFrame NativeSeriesNativeSparkLike NativeUnknownis_native_arrowis_native_cudfis_native_daskis_native_duckdbis_native_ibisis_native_modinis_native_pandasis_native_pandas_likeis_native_polarsis_native_pysparkis_native_pyspark_connectis_native_spark_likeis_native_sqlframec@s$eZdZed ddZd ddZd S) r-returnrcCdSNselfrMrMN/var/www/html/IGF-ODF-V3/venv/lib/python3.10/site-packages/narwhals/_native.pycolumnszNativeFrame.columnsargskwargscOrKrLrMrOrSrTrMrMrPjoinzNativeFrame.joinNrJrrSrrTrrJr)__name__ __module__ __qualname__propertyrQrVrMrMrMrPr-s r-c@eZdZdddZdS) r+rSrrTrJcOrKrLrMrUrMrMrPdroprWzNativeDataFrame.dropNrY)rZr[r\r_rMrMrMrPr+r+c@r^) r0rSrrTrJcOrKrLrMrUrMrMrPexplainrWzNativeLazyFrame.explainNrY)rZr[r\rarMrMrMrPr0r`r0c@s*eZdZd ddZd ddZd d d Zd S) r:rSrrTrJcOrKrLrMrUrMrMrPfilterrWzNativeSeries.filtercOrKrLrMrUrMrMrP value_countsrWzNativeSeries.value_countscOrKrLrMrUrMrMrPuniquerWzNativeSeries.uniqueNrY)rZr[r\rbrcrdrMrMrMrPr:s  r:c@szeZdZUded< d$ddZd%d d Zd%d d Zed&ddZed'ddZ dddd(ddZ d)d*ddZ d+d!d"Z d#S),_BasePandasLikerindexkeyrJcCrKrLrM)rOrgrMrMrP __getitem__rWz_BasePandasLike.__getitem__other float | Collection[float] | SelfrcCrKrLrMrOrirMrMrP__mul__rWz_BasePandasLike.__mul__cCrKrLrMrkrMrMrP __floordiv__rWz_BasePandasLike.__floordiv__cCrKrLrMrNrMrMrPlocrRz_BasePandasLike.loctuple[int, ...]cCrKrLrMrNrMrMrPshaperRz_BasePandasLike.shape.)axiscopylabelsrqrrboolcCrKrLrM)rOrsrqrrrMrMrPset_axisrWz_BasePandasLike.set_axisdeepcCrKrLrM)rOrvrMrMrPrrrWz_BasePandasLike.copyrSkwdsSelf | IncompletecOsdS)z`mypy` & `pyright` disagree on overloads. `Incomplete` used to fix [more important issue](https://github.com/narwhals-dev/narwhals/pull/3016#discussion_r2296139744). NrMrOrSrwrMrMrPrenamerWz_BasePandasLike.renameN)rgrrJr)rirjrJrrX)rJro)rsrrqrrrrtrJr.)rvrtrJr)rSrrwrrJrx) rZr[r\__annotations__rhrlrmr]rnrprurrrzrMrMrMrPres       rec@s eZdZdS)_BasePandasLikeFrameN)rZr[r\rMrMrMrPr}s r}c@s6eZdZUded<    ddd dZddddZdS)_BasePandasLikeSeries Any | NonenameNdataIterable[Any] | NonerfdtyperSrrTrJNonecOrKrLrM)rOrrfrrrSrTrMrMrP__init__sz_BasePandasLikeSeries.__init__.condrirxcCrKrLrM)rOrrirMrMrPwhererWz_BasePandasLikeSeries.where)NNNN)rrrfrrrrrrSrrTrrJrr{)rrrirrJrx)rZr[r\r|rrrMrMrMrPr~s   r~c@eZdZUded<dS)r*type[pd.DataFrame]_partition_typeNrZr[r\r|rMrMrMrPr* r*c@r^) _CuDFDataFramerSrrwrJcOrKrLrMryrMrMrP to_pylibcudfrWz_CuDFDataFrame.to_pylibcudfNrSrrwrrJrrZr[r\rrMrMrMrPrr`rc@r^) _CuDFSeriesrSrrwrJcOrKrLrMryrMrMrPrrWz_CuDFSeries.to_pylibcudfNrrrMrMrMrPrr`rc@s4eZdZdddZdddZdd d Zdd d Zd S)r.rSrrwrJcOrKrLrMryrMrMrPsqlrWzNativeIbis.sqlcOrKrLrMryrMrMrP__pyarrow_result__rWzNativeIbis.__pyarrow_result__cOrKrLrMryrMrMrP__pandas_result__rWzNativeIbis.__pandas_result__cOrKrLrMryrMrMrP__polars_result__rWzNativeIbis.__polars_result__Nr)rZr[r\rrrrrMrMrMrPr.s    r.c@r)_ModinDataFramer _pandas_classNrrMrMrMrPrrrc@r) _ModinSeriesztype[pd.Series[Any]]rNrrMrMrMrPr rrc@r^) _PySparkDataFrameargrrTrJcOrKrLrM)rOrrTrMrMrPdropDuplicatesWithinWatermarkrWz/_PySparkDataFrame.dropDuplicatesWithinWatermarkN)rrrTrrJr)rZr[r\rrMrMrMrPrr`rz'pl.DataFrame | pl.LazyFrame | pl.Seriesr6zpa.Table | pa.ChunkedArray[Any]r(zduckdb.DuckDBPyRelationr,zpd.DataFrame | pd.Series[Any]r2z_ModinDataFrame | _ModinSeriesr1z_CuDFDataFrame | _CuDFSeriesr)z+pd.Series[Any] | _CuDFSeries | _ModinSeriesr5z/pd.DataFrame | _CuDFDataFrame | _ModinDataFramer4z2NativePandasLikeDataFrame | NativePandasLikeSeriesr3z'_BaseDataFrame[Any, Any, Any, Any, Any]r9r7r8z5NativeSQLFrame | NativePySpark | NativePySparkConnectr;zhNativePolars | NativeArrow | NativePandasLike | NativeSparkLike | NativeDuckDB | NativeDask | NativeIbisr/z0NativeDataFrame | NativeSeries | NativeLazyFramer<zNativeKnown | NativeUnknownr'rr#r!r%r")boundr r$r&objrrJTypeIs[NativePolars]cCs$t}duot||j|j|jfSrL)r isinstance DataFrameSeries LazyFrame)rplrMrMrPrE|srETypeIs[NativeArrow]cC t}duot||j|jfSrL)rrTable ChunkedArray)rparMrMrPr= r=z_Guard[NativeDask]z_Guard[NativeDuckDB]r@z_Guard[NativeSQLFrame]rIz_Guard[NativePySpark]z_Guard[NativePySparkConnect]z_Guard[NativeIbis]TypeIs[NativePandas]cCrrL)rrrr)rpdrMrMrPrCs rCTypeIs[NativeModin]cCrrL)rrrr)rmpdrMrMrPrBrrBTypeIs[NativeCuDF]cCrrL)r rrr)rcudfrMrMrPr>rr>TypeIs[NativePandasLike]cCt|p t|p t|SrL)rCr>rBrrMrMrPrDsrDTypeIs[NativeSparkLike]cCrrL)rIrFrGrrMrMrPrHs rH)rrrJr)rrrJr)rrrJr)rrrJr)rrrJr)rrrJr)rrrJr)b__doc__ __future__rcollections.abcrrrrtypingrrr r r r narwhals.dependenciesr rrrrrrrrrrduckdbpandasrpolarsrpyarrowrsqlframe.base.dataframer_BaseDataFrametyping_extensionsrrrSQLFrameDataFramerrr|r__all__r-r+r0r:rer}r~r*rrr.rrrr6r(r,r2r1r)r5r4r3r9r7r8r;r/r<r'rr#r!r%r"r r$r&rEr=r?r@rIrFrGrArCrBr>rDrHrMrMrMrPs h 4   2