enh: Add `polars._typing` aliases

[dangotbanned]

Description

polars defines a pretty extensive set of TypeAlias(s) and I think there's plenty we could steal to improve our UX.

I'd want to take it a step further and add trailing docstrings to them - that way we get some docs "for free" when used in the internals 🙂

Examples

I'm just picking out one example for each kind of alias - but there are many others

Literal(s)

Here it would contribute to (#1942) as we have 14x of this spread across the backends:

how: Literal["horizontal", "vertical", "diagonal"]

polars.concat

def concat(
    items: Iterable[PolarsType],
    *,
    how: ConcatMethod = "vertical",
    rechunk: bool = False,
    parallel: bool = True,
) -> PolarsType:

narwhals.concat

@overload
def concat(
    items: Iterable[DataFrame[IntoDataFrameT]],
    *,
    how: Literal["horizontal", "vertical", "diagonal"] = "vertical",
) -> DataFrame[IntoDataFrameT]: ...


@overload
def concat(
    items: Iterable[LazyFrame[IntoFrameT]],
    *,
    how: Literal["horizontal", "vertical", "diagonal"] = "vertical",
) -> LazyFrame[IntoFrameT]: ...


@overload
def concat(
    items: Iterable[DataFrame[IntoDataFrameT] | LazyFrame[IntoFrameT]],
    *,
    how: Literal["horizontal", "vertical", "diagonal"] = "vertical",
) -> DataFrame[IntoDataFrameT] | LazyFrame[IntoFrameT]: ...


def concat(
    items: Iterable[DataFrame[IntoDataFrameT] | LazyFrame[IntoFrameT]],
    *,
    how: Literal["horizontal", "vertical", "diagonal"] = "vertical",
) -> DataFrame[IntoDataFrameT] | LazyFrame[IntoFrameT]:

Python types

We have cases like this, that would benefit from aliases like PythonLiteral, NumericLiteral, etc.

narwhals/narwhals/expr.py

Lines 1951 to 1957 in d2a9f42

	# need to allow numeric typing
	# TODO @aivanoved: make type alias for numeric type
	def clip(
	self: Self,
	lower_bound: IntoExpr | Any | None = None,
	upper_bound: IntoExpr | Any | None = None,
	) -> Self:

Related

• refactor(python): Rename type_aliases module to _typing pola-rs/polars#17282
• Set up polars.typing module with curated type aliases pola-rs/polars#17420

[dangotbanned]

Resolved via #2362