mxi*<UdZddlmZddlmZmZmZmZddlm Z m Z m Z m Z m Z mZddlmZmZmZmZmZmZmZmZmZmZmZe r@ddlZddlZddlZddl 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.Gdde Z/Gddee/e Z0Gdde/e Z1Gddeee e Z2Gddee Z3Gdde0e3e Z4Gdde2e3e Z5Gdde1e Z6Gdd e4e Z7Gd!d"e5e Z8Gd#d$e/e Z9Gd%d&e4e Z:Gd'd(e5e Z;Gd)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&eZdZeddZddZy)r.cyNselfs G/home/htdocs/ttos/venv/lib/python3.12/site-packages/narwhals/_native.pycolumnszNativeFrame.columnss!cyrMrNrPargskwargss rQjoinzNativeFrame.joinrSNreturnr rVr rWr r[r )__name__ __module__ __qualname__propertyrRrXrNrSrQr.r.s !!9rSr.ceZdZddZy)r,cyrMrNrUs rQdropzNativeDataFrame.droprYrSNr\)r]r^r_rcrNrSrQr,r,s9rSr,ceZdZddZy)r1cyrMrNrUs rQexplainzNativeLazyFrame.explainrYrSNr\)r]r^r_rfrNrSrQr1r1sr>s4- B ,  bhh (2rSz_Guard[NativeDask]z_Guard[NativeDuckDB]rAz_Guard[NativeSQLFrame]rJz_Guard[NativePySpark]z_Guard[NativePySparkConnect]z_Guard[NativeIbis]cftx}duxr"t||j|jfSrM)rrrr)rpds rQrDrDs-, Bt + Z 3ryy@Y0ZZrScftx}duxr"t||j|jfSrM)rrrr)rmpds rQrCrCs4; Ct +   cmmSZZ (1rScftx}duxr"t||j|jfSrM)rrrr)rcudfs rQr?r?s4J Dt +   dnndkk *1rScLt|xst|xs t|SrM)rDr?rCrs rQrErEs! C ON3$7 O?3;OOrScLt|xst|xs t|SrM)rJrGrHrs rQrIrIs)3 * S ! * $S )rS)rr r[zTypeIs[NativePolars])rr r[zTypeIs[NativeArrow])rr r[zTypeIs[NativePandas])rr r[zTypeIs[NativeModin])rr r[zTypeIs[NativeCuDF])rr r[zTypeIs[NativePandasLike])rr r[zTypeIs[NativeSparkLike])b__doc__ __future__rcollections.abcrrrrtypingrr r r r r narwhals.dependenciesrrrrrrrrrrrduckdbpandasrpolarsrpyarrowrsqlframe.base.dataframer_BaseDataFrametyping_extensionsrrrSQLFrameDataFramerrrr__all__r.r,r1r;rorrr+rrr/rrrr7r)r-r3r2r*r6r5r4r:r8r9r<r0r=r(r r$r"r&r#r!r%r'rFr>r@rArJrGrHrBrDrCr?rErIrNrSrQrs fP#AAEE    G99&sCc3'>? A4FI4J , d:(: :e[(:=k8=<5(3-<  eX (L?OXK NL/8 N(((@)8@@'@EhE&*H&((((RRD iC: Y:3 i39 i99 Y96 I6$Q Q'X9XR)RE E, y,"3i3TTD YDM yM4 94* y* !*!<= y=]M9: 9: % I$ \ 3  )? )?m:6    *,=>);&;-B*B02FG "$@*M:[  PrS