Skip to content

Commit d060577

Browse files
committed
docs: Fluff up "Matching to an Implementation"
1 parent 3683b06 commit d060577

File tree

1 file changed

+16
-10
lines changed

1 file changed

+16
-10
lines changed

narwhals/_native.py

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@
1818
1919
Our goal is to **wrap** a *partially-unknown* native object **in** a [generic class]:
2020
21-
DataFrame[IntoDataFrameT]
22-
LazyFrame[IntoLazyFrameT]
23-
Series[IntoSeriesT]
21+
def wrapping_in_df(native: IntoDataFrameT) -> DataFrame[IntoDataFrameT]: ...
22+
def wrapping_in_ldf(native: IntoLazyFrameT) -> LazyFrame[IntoLazyFrameT]: ...
23+
def wrapping_in_ser(native: IntoSeriesT) -> Series[IntoSeriesT]: ...
2424
2525
### (1) `Native<Thing>`
2626
Minimal [`Protocol`]s that are [assignable to] *almost any* supported native type of that group:
@@ -57,24 +57,30 @@ class Thing(Generic[IntoThingT]):
5757
def to_native(self) -> IntoThingT: ...
5858
5959
## Matching to an `Implementation`
60-
[//]: # (TODO @dangotbanned: Introduce this section?)
60+
This problem differs as we need to *create* a relationship between *otherwise-unrelated* types.
61+
62+
Comparing the problems side-by-side, we can more clearly see this difference:
63+
64+
def wrapping_in_df(native: IntoDataFrameT) -> DataFrame[IntoDataFrameT]: ...
65+
def matching_to_polars(native: pl.DataFrame) -> Literal[Implementation.POLARS]: ...
6166
6267
### (4) `Native<Backend>`
63-
If we want to describe a set of more specific types (e.g. in [`@overload`s]), then these protocols/aliases are the right tool.
68+
If we want to describe a set of specific types and **match** them in [`@overload`s], then these the tools we need.
6469
65-
For common and easily-installed backends, aliases are composed of the native type(s):
70+
For common and easily-installed backends, [`TypeAlias`]s are composed of the native type(s):
6671
6772
NativePolars: TypeAlias = pl.DataFrame | pl.LazyFrame | pl.Series
6873
69-
Otherwise, we need to define a [`Protocol`] which the native type(s) can match against *when* installed:
74+
Otherwise, we need to define a [`Protocol`] which the native type(s) can **match** against *when* installed:
7075
7176
class NativeDask(NativeLazyFrame, Protocol):
7277
_partition_type: type[pd.DataFrame]
7378
74-
Important:
75-
The goal is to be as minimal as possible, while still being *specific-enough* to **not** match something else.
79+
Tip:
80+
The goal is to be as minimal as possible, while still being *specific-enough* to **not match** something else.
7681
77-
For a more complete example, see [ibis#9276 comment].
82+
Important:
83+
See [ibis#9276 comment] for a more *in-depth* example that doesn't fit here 😄
7884
7985
### (5) `is_native_<backend>`
8086
[Type guards] for **(4)**, *similar* to those found in `nw.dependencies`.

0 commit comments

Comments
 (0)