chore: @requires for backend method constraints

[dangotbanned]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Related issue #<issue number>
• Closes #<issue number>

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

If you have comments or can explain your changes, please do so below

Adds a method decorator for consistent error messages on unsupported versions

Main use case is for enforcing a minimum version, e.g.:

class PolarsExpr:
    @requires(min_version=(1,))
    def rolling_var(
        self: Self, window_size: int, *, min_samples: int, center: bool, ddof: int
    ) -> Self: ...

Still have some other cases I wanna explore:

• Providing a hint (PolarsNamespace.nth)

Possible follow-ups

PandasLike*

.pivot is a good example of multiple cases dependent on more than just backend_version:

narwhals/narwhals/_pandas_like/dataframe.py

Lines 1032 to 1049 in d63ec65

	def pivot(
	self: Self,
	on: list[str],
	*,
	index: list[str] | None,
	values: list[str] | None,
	aggregate_function: Any | None,
	sort_columns: bool,
	separator: str,
	) -> Self:
	if self._implementation is Implementation.PANDAS and (
	self._backend_version < (1, 1)
	): # pragma: no cover
	msg = "pivot is only supported for pandas>=1.1"
	raise NotImplementedError(msg)
	if self._implementation is Implementation.MODIN:
	msg = "pivot is not supported for Modin backend due to https://github.com/modin-project/modin/issues/7409."
	raise NotImplementedError(msg)

Parameter combinations

I'd only want to include the version-based parameter restrictions on @requires:

• DuckDBLazyFrame.join(how="cross")
• DuckDBExpr.broadcast(kind=ExprKind.AGGREGATION)
• PolarsDataFrame.__array__(copy=...)
• PolarsExpr.over(order_by=...)

It seems there are more blanket parameter restrictions, but they don't make sense as a @requires:

• DaskExpr.cum_*(reverse=True)
• DaskExpr.rolling_*(ddof=2) (or not 1)
• (Dask|DuckDB)Expr.quantile(interpolation="(nearest|higher|lower|midpoint)")
• DuckDBLazyFrame.join_asof(strategy="nearest")
• (DuckDB|SparkLike)Expr.fill_null(strategy=...)
• (DuckDB|SparkLike)Expr.rank(method="(average|max|ordinal)")
• DuckDBExprStringNamespace.to_datetime(format=None)

How to document this?

Like with not_implemented, we could mark the methods with runtime metadata. Then consume that in a script for something like https://narwhals-dev.github.io/narwhals/api-completeness/

[dangotbanned]

Been think about an alternative spelling which could be more easily adapted for other requirements.

Imports

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from typing_extensions import Self

    from narwhals._polars.expr import PolarsExpr

Current

Decorator constructor

class requires:  # noqa: N801
    def __init__(self, *, min_version: tuple[int, ...], hint: str = "") -> None:
        self._min_version: tuple[int, ...] = min_version
        self._hint: str = hint
        self._wrapped_name: str

Usage

class DuckDBExpr:
    @requires(min_version=(1, 3))
    def is_first_distinct(self) -> Self: ...

class PolarsNamespace:
    @requires(
        min_version=(1, 0, 0), hint="Please use `col` for columns selection instead."
    )
    def nth(self, *indices: int) -> PolarsExpr: ...

Alternative

Would be pretty easy to add support for multi-implementation cases this way - without it affecting the more common usage.

I also like that we can stay aligned with the backend_version name, while still indicating it is a minimum

Decorator constructor

See (651cf2f)

Code block

class requires:  # noqa: N801
    @classmethod
    def backend_version(cls, min_version: tuple[int, ...], /, hint: str = "") -> Self:
        obj = cls.__new__(cls)
        obj._min_version = min_version
        obj._hint = hint
        return obj

Usage

class DuckDBExpr:
    @requires.backend_version((1, 3))
    def is_first_distinct(self) -> Self: ...

class PolarsNamespace:
    @requires.backend_version(
        (1, 0, 0), "Please use `col` for columns selection instead."
    )
    def nth(self, *indices: int) -> PolarsExpr: ...

[dangotbanned]

I want to switch everything over to this style, see for comparison (#2371 (comment))

Also the one current use for coverage (0ac9595)