feat: Add the concept of Version-ing

`Version` is never stored on an `IR` node and should only be needed when converting back to another representation (`to_*`)

Author: dangotbanned

narwhals/_plan/common.py

@@ -3,6 +3,8 @@
 from typing import TYPE_CHECKING
 from typing import TypeVar
 
+from narwhals.utils import Version
+
 if TYPE_CHECKING:
     from typing import Any
     from typing import Callable
@@ -119,15 +121,17 @@ def __init__(self, **kwds: Any) -> None:
 class ExprIR(Immutable):
     """Anything that can be a node on a graph of expressions."""
 
-    def to_narwhals(self) -> DummyExpr:
-        from narwhals._plan.dummy import DummyExpr
+    def to_narwhals(self, version: Version = Version.MAIN) -> DummyExpr:
+        from narwhals._plan import dummy
 
-        return DummyExpr._from_ir(self)
+        if version is Version.MAIN:
+            return dummy.DummyExpr._from_ir(self)
+        return dummy.DummyExprV1._from_ir(self)
 
-    def to_compliant(self) -> DummyCompliantExpr:
+    def to_compliant(self, version: Version = Version.MAIN) -> DummyCompliantExpr:
         from narwhals._plan.dummy import DummyCompliantExpr
 
-        return DummyCompliantExpr._from_ir(self)
+        return DummyCompliantExpr._from_ir(self, version)
 
     @property
     def is_scalar(self) -> bool:

narwhals/_plan/dummy.py

@@ -14,6 +14,7 @@
 from narwhals._plan.window import Over
 from narwhals.dtypes import DType
 from narwhals.utils import Version
+from narwhals.utils import _hasattr_static
 from narwhals.utils import flatten
 
 if TYPE_CHECKING:
@@ -29,21 +30,26 @@
 # Entirely ignoring namespace + function binding
 class DummyExpr:
     _ir: ExprIR
+    _version: t.ClassVar[Version] = Version.MAIN
 
     def __repr__(self) -> str:
-        return f"Narwhals DummyExpr:\n{self._ir!r}"
+        return f"Narwhals DummyExpr ({self.version.name.lower()}):\n{self._ir!r}"
 
     @classmethod
     def _from_ir(cls, ir: ExprIR, /) -> Self:
         obj = cls.__new__(cls)
         obj._ir = ir
         return obj
 
+    @property
+    def version(self) -> Version:
+        return self._version
+
     def alias(self, name: str) -> Self:
         return self._from_ir(expr.Alias(expr=self._ir, name=name))
 
     def cast(self, dtype: DType | type[DType]) -> Self:
-        dtype = dtype if isinstance(dtype, DType) else Version.MAIN.dtypes.Unknown()
+        dtype = dtype if isinstance(dtype, DType) else self.version.dtypes.Unknown()
         return self._from_ir(expr.Cast(expr=self._ir, dtype=dtype))
 
     def count(self) -> Self:
@@ -92,7 +98,7 @@ def over(
         order_by: DummyExpr | t.Iterable[DummyExpr] | None = None,
         descending: bool = False,
         nulls_last: bool = False,
-    ) -> DummyExpr:
+    ) -> Self:
         order: tuple[Seq[ExprIR], SortOptions] | None = None
         partition = tuple(expr._ir for expr in flatten(partition_by))
         if not (partition) and order_by is None:
@@ -102,7 +108,7 @@ def over(
             by = tuple(expr._ir for expr in flatten([order_by]))
             options = SortOptions(descending=descending, nulls_last=nulls_last)
             order = by, options
-        return Over().to_window_expr(self._ir, partition, order).to_narwhals()
+        return self._from_ir(Over().to_window_expr(self._ir, partition, order))
 
     def sort_by(
         self,
@@ -121,78 +127,98 @@ def sort_by(
         options = SortMultipleOptions(descending=desc, nulls_last=nulls)
         return self._from_ir(expr.SortBy(expr=self._ir, by=sort_by, options=options))
 
-    def __eq__(self, other: DummyExpr) -> DummyExpr:  # type: ignore[override]
+    def __eq__(self, other: DummyExpr) -> Self:  # type: ignore[override]
         op = ops.Eq()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __ne__(self, other: DummyExpr) -> DummyExpr:  # type: ignore[override]
+    def __ne__(self, other: DummyExpr) -> Self:  # type: ignore[override]
         op = ops.NotEq()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __lt__(self, other: DummyExpr) -> DummyExpr:
+    def __lt__(self, other: DummyExpr) -> Self:
         op = ops.Lt()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __le__(self, other: DummyExpr) -> DummyExpr:
+    def __le__(self, other: DummyExpr) -> Self:
         op = ops.LtEq()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __gt__(self, other: DummyExpr) -> DummyExpr:
+    def __gt__(self, other: DummyExpr) -> Self:
         op = ops.Gt()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __ge__(self, other: DummyExpr) -> DummyExpr:
+    def __ge__(self, other: DummyExpr) -> Self:
         op = ops.GtEq()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __add__(self, other: DummyExpr) -> DummyExpr:
+    def __add__(self, other: DummyExpr) -> Self:
         op = ops.Add()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __sub__(self, other: DummyExpr) -> DummyExpr:
+    def __sub__(self, other: DummyExpr) -> Self:
         op = ops.Sub()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __mul__(self, other: DummyExpr) -> DummyExpr:
+    def __mul__(self, other: DummyExpr) -> Self:
         op = ops.Multiply()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __truediv__(self, other: DummyExpr) -> DummyExpr:
+    def __truediv__(self, other: DummyExpr) -> Self:
         op = ops.TrueDivide()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __floordiv__(self, other: DummyExpr) -> DummyExpr:
+    def __floordiv__(self, other: DummyExpr) -> Self:
         op = ops.FloorDivide()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __mod__(self, other: DummyExpr) -> DummyExpr:
+    def __mod__(self, other: DummyExpr) -> Self:
         op = ops.Modulus()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __and__(self, other: DummyExpr) -> DummyExpr:
+    def __and__(self, other: DummyExpr) -> Self:
         op = ops.And()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
 
-    def __or__(self, other: DummyExpr) -> DummyExpr:
+    def __or__(self, other: DummyExpr) -> Self:
         op = ops.Or()
-        return op.to_binary_expr(self._ir, other._ir).to_narwhals()
+        return self._from_ir(op.to_binary_expr(self._ir, other._ir))
+
+    def __invert__(self) -> Self:
+        return self._from_ir(boolean.Not().to_function_expr(self._ir))
+
 
-    def __invert__(self) -> DummyExpr:
-        return boolean.Not().to_function_expr(self._ir).to_narwhals()
+class DummyExprV1(DummyExpr):
+    _version: t.ClassVar[Version] = Version.V1
 
 
 class DummyCompliantExpr:
     _ir: ExprIR
+    _version: Version
+
+    @property
+    def version(self) -> Version:
+        return self._version
 
     @classmethod
-    def _from_ir(cls, ir: ExprIR, /) -> Self:
+    def _from_ir(cls, ir: ExprIR, /, version: Version) -> Self:
         obj = cls.__new__(cls)
         obj._ir = ir
+        obj._version = version
         return obj
 
+    def to_narwhals(self) -> DummyExpr:
+        if self.version is Version.MAIN:
+            return DummyExpr._from_ir(self._ir)
+        return DummyExprV1._from_ir(self._ir)
+
 
 class DummySeries:
     _compliant: DummyCompliantSeries
+    _version: t.ClassVar[Version] = Version.MAIN
+
+    @property
+    def version(self) -> Version:
+        return self._version
 
     @property
     def dtype(self) -> DType:
@@ -205,31 +231,38 @@ def name(self) -> str:
     @classmethod
     def from_native(cls, native: NativeSeries, /) -> Self:
         obj = cls.__new__(cls)
-        obj._compliant = DummyCompliantSeries.from_native(native)
+        obj._compliant = DummyCompliantSeries.from_native(native, cls._version)
         return obj
 
 
+class DummySeriesV1(DummySeries):
+    _version: t.ClassVar[Version] = Version.V1
+
+
 class DummyCompliantSeries:
     _native: NativeSeries
     _name: str
+    _version: Version
+
+    @property
+    def version(self) -> Version:
+        return self._version
 
     @property
     def dtype(self) -> DType:
-        return Version.MAIN.dtypes.Float64()
+        return self.version.dtypes.Float64()
 
     @property
     def name(self) -> str:
         return self._name
 
     @classmethod
-    def from_native(cls, native: NativeSeries, /) -> Self:
-        from narwhals.utils import _hasattr_static
-
+    def from_native(cls, native: NativeSeries, /, version: Version) -> Self:
         name: str = "<PLACEHOLDER>"
-
         if _hasattr_static(native, "name"):
             name = getattr(native, "name", name)
         obj = cls.__new__(cls)
         obj._native = native
         obj._name = name
+        obj._version = version
         return obj