ctj=.UdZddlmZddlZddlmZmZmZmZddl m Z m Z m Z m Z mZddlmZmZmZmZmZmZmZmZmZmZmZmZe rJddl mZddlZddlZddl Z!ddl"Z#ddl$m%Z&dd l'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 Z0Gddee0e Z1Gdde0e Z2Gddeee e Z3Gddee Z4Gdde1e4e Z5Gdde3e4e Z6Gdde2e Z7Gd d!e5e Z8Gd"d#e6e Z9Gd$d%e0e Z:Gd&d'e5e Z;Gd(d)e6e Z<Gd*d+e2e Z=d,Z>d e-d-<d.Z?d e-d/<d0Z@d e-d1<d2ZAd e-d3<d4ZBd e-d5<d6ZCd e-d7<d8ZDd e-d9<d:ZEd e-d;<dZGd e-d?<e=ZHd e-d@<e=ZId e-dA<dBZJd e-dC<dDZKd e-dE<dFZLd e-dG<dHZMd e-dI<e1ZNd e-dJ< e2e:zZOd e-dK<eNeOzZPd e-dL< e3ZQd e-dM< e dNePOZR e dPeNOZS e dQeOOZTe dReQOZU dldWZVdmdYZWedZeZXeZYd[e-d\<eZZd]e-d^<ed_eZ[ed`eZ\edaeZ]dndcZ^dodeZ_dpdgZ`dqdiZadrdkZbdS)suThe home for *mostly* [structural] counterparts to [nominal] native types. If you find yourself being yelled at by a typechecker and ended up here - **do not fear!** We have 5 funky flavors, which tackle two different problem spaces. How do we describe [Native types] when ... - ... **wrapping in** a [Narwhals type]? - ... **matching to** an [`Implementation`]? ## Wrapping in a Narwhals type [//]: # (TODO @dangotbanned: Replace `Thing` with a better name) The following examples use the placeholder type `Thing` which represents one of: - `DataFrame`: (Eager) 2D data structure representing data as a table with rows and columns. - `LazyFrame`: (Lazy) Computation graph/query against a DataFrame/database. - `Series`: 1D data structure representing a single column. Our goal is to **wrap** a *partially-unknown* native object **in** a [generic class]: def wrapping_in_df(native: IntoDataFrameT) -> 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 ) annotationsN)Callable CollectionIterableSized) TYPE_CHECKINGAnyProtocolTypeVarcast) IMPORT_HOOKSget_cudf get_modin get_pandas get_polars get_pyarrowis_dask_dataframeis_duckdb_relation is_ibis_tableis_pyspark_connect_dataframeis_pyspark_dataframeis_sqlframe_dataframe) TypeAlias) BaseDataFrame)SelfTypeIsTzCallable[[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.eZdZeddZd dZdS) r.returnr cdSNselfs N/var/www/html/CA-Chatbot/venv/lib/python3.11/site-packages/narwhals/_native.pycolumnszNativeFrame.columnss!cargskwargscdSrNrOrQrUrVs rRjoinzNativeFrame.joinrTNrLr rUr rVr rLr )__name__ __module__ __qualname__propertyrSrYrOrTrRr.r.s2 !!!X!999999rTr.ceZdZddZdS)r,rUr rVrLcdSrNrOrXs rRdropzNativeDataFrame.droprZrTNr\)r]r^r_rcrOrTrRr,r,s999999rTr,ceZdZddZdS)r1rUr rVrLcdSrNrOrXs rRexplainzNativeLazyFrame.explainrZrTNr\)r]r^r_rfrOrTrRr1r1s<<<<<r>s7-- B ,  bh (22rTz_Guard[NativeDask]z_Guard[NativeDuckDB]rAz_Guard[NativeSQLFrame]rJz_Guard[NativePySpark]z_Guard[NativePySparkConnect]z_Guard[NativeIbis]TypeIs[NativePandas]ctx}duot|j|jfp t fdt DS)Nc3K|]N}tj|dxduo%tjjjjfVOdSrN)sysmodulesgetrpandasrr).0 module_namemodrs rR z#is_native_pandas..su     T22 24? G sSZ13:3DE F F      rT)rrrranyr )rpdrs` @rRrDrDsq|| D(WZblBI=V-W-W       (     rTTypeIs[NativeModin]c^tx}duot||j|jfSrN)rrrr)rmpds rRrCrCs7;; Ct +   cmSZ (11rTTypeIs[NativeCuDF]c^tx}duot||j|jfSrN)rrrr)rcudfs rRr?r?s7JJ Dt +   dndk *11rTTypeIs[NativePandasLike]c\t|pt|pt|SrN)rDr?rCrs rRrErEs* C ON3$7$7 O?3;O;OOrTTypeIs[NativeSparkLike]c\t|pt|pt|SrN)rJrGrHrs rRrIrIs23 * S ! ! * $S ) )rT)rr rLr)rr rLr)rr rLr)rr rLr)rr rLr)rr rLr)rr rLr)c__doc__ __future__rrcollections.abcrrrrtypingrr r r r narwhals.dependenciesr rrrrrrrrrrrrduckdbrrpolarsrpyarrowrsqlframe.base.dataframer_BaseDataFrametyping_extensionsrrSQLFrameDataFramerrrr__all__r.r,r1r;rorrr+rrr/rrrr7r)r-r3r2r*r6r5r4r:r8r9r<r0r=r(r r$r"r&r#r!r%r'rFr>r@rArJrGrHrBrDrCr?rErIrOrTrRrskfffP#""""" AAAAAAAAAAAA>>>>>>>>>>>>>>                                    MMMGGGGGG........&sCc3'>? A4F4444J, , , d:::::(::: :::::e[(:::=====k8===<<<<<5(3-<<<      eX   (LKKKK?OXKKK N N N N NL/8 N N N(((((((((@@@@@)8@@@@@@@@'@@@EEEEEhEEE&&&&&*H&&&((((((((((RRRRRRRRD CCCC: ::::3 33339 99999 99996 6666$QQQQQ'XXXXXRRRRREEEEE, ,,,,"33333TTTTTD DDDDM MMMM4 4444* **** +Z7 7777$}4 4444 % $$$$ W\ 3 3 3  )??? )???gm:666    *,=>>);;;;;-BBBBBD02FGG D"$@*M::  PPPPrT