refactor: adding Compliant* sub-protocols

[dangotbanned]

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

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

Related issues

• Related issue fix TypeVar used in (SparkLike|DuckDB)Expr  #2044
• fix TypeVar used in (SparkLike|DuckDB)Expr  #2044 (comment)

Checklist

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

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

Note

Thinking about renaming Reuse* -> EagerOnly* or something like that

TODO

• evaluate_into_exprs -> ReuseDataFrame._evaluate_into_exprs
  • mypy cannot cope with the generics
  • pyright understands it
  • The doc is already hinting that this should be a method

  • narwhals/narwhals/_expression_parsing.py

    Lines 53 to 84 in f6a7902

    	def evaluate_into_expr(
    	df: CompliantFrameT_contra,
    	expr: CompliantExpr[CompliantFrameT_contra, CompliantSeriesT_co],
    	) -> Sequence[CompliantSeriesT_co]:
    	"""Return list of raw columns.
    	This is only use for eager backends (pandas, PyArrow), where we
    	alias operations at each step. As a safety precaution, here we
    	can check that the expected result names match those we were
    	expecting from the various `evaluate_output_names` / `alias_output_names`
    	calls. Note that for PySpark / DuckDB, we are less free to liberally
    	set aliases whenever we want.
    	"""
    	_, aliases = evaluate_output_names_and_aliases(expr, df, [])
    	result = expr(df)
    	if list(aliases) != [s.name for s in result]: # pragma: no cover
    	msg = f"Safety assertion failed, expected {aliases}, got {result}"
    	raise AssertionError(msg)
    	return result
    	def evaluate_into_exprs(
    	df: CompliantFrameT_contra,
    	/,
    	*exprs: CompliantExpr[CompliantFrameT_contra, CompliantSeriesT_co],
    	) -> list[CompliantSeriesT_co]:
    	"""Evaluate each expr into Series."""
    	return [
    	item
    	for sublist in (evaluate_into_expr(df, into_expr) for into_expr in exprs)
    	for item in sublist
    	]

[dangotbanned]

Could these all be replaced like this?

• ReuseNamespace._create_compliant_series() -> ReuseSeries()
• ReuseNamespace._create_expr_from_callable() -> ReuseExpr._from_callable()
• ReuseNamespace._create_expr_from_series() -> ReuseExpr._from_series()
• ReuseNamespace._create_series_from_scalar() -> ReuseSeries._from_scalar()

[dangotbanned]

@MarcoGorelli just seen this 😄

• chore: use Expr._from_callable #2070

[dangotbanned]

Probably going to split this into another PR.

Would be helpful for representing this

narwhals/narwhals/_protocols.py

Lines 178 to 185 in b74faa3

	# NOTE: Each side adds an `AssertionError` guard first
	# Would probably make more sense to require a ClassVar, either:
	# - defining the set of permitted impls
	# - setting an unbound method, which also gives the error message
	# - E.g. `PandasLikeSeries._ensure = Implementation.ensure_pandas_like`
	# - That gets called w/ `ReuseSeries._ensure(ReuseSeries._implementation)`
	def __native_namespace__(self: Self) -> ModuleType:
	return self._implementation.to_native_namespace()

narwhals/narwhals/_pandas_like/series.py

Lines 115 to 124 in dc7a0e1

	def __native_namespace__(self: Self) -> ModuleType:
	if self._implementation in {
	Implementation.PANDAS,
	Implementation.MODIN,
	Implementation.CUDF,
	}:
	return self._implementation.to_native_namespace()
	msg = f"Expected pandas/modin/cudf, got: {type(self._implementation)}" # pragma: no cover
	raise AssertionError(msg)

But there are lots of other places this kind of check/error message is copy/pasted at the moment

[dangotbanned]

To be more permissive at this level; I've used:

• Callable[..., ReuseExpr[ReuseSeriesT]] instead of
• type[ReuseExpr[ReuseSeriesT]]

[dangotbanned]

@MarcoGorelli no rush on this, just wanted to check in to see if your happy with the direction of this?

Actually implementing it shouldn't be difficult from this point, but would be a huge diff

[dangotbanned]

Superseded by #2149