chore: Remove/update comments/notes

Author: dangotbanned

narwhals/_plan/__init__.py

@@ -1,41 +1 @@
-"""Brainstorming an `Expr` internal representation.
-
-Notes:
-- Each `Expr` method should be representable by a single node
-  - But the node does not need to be unique to the method
-- A chain of `Expr` methods should form a plan of operations
-- We must be able to enforce rules on what plans are permitted:
-  - Must be flexible to both eager/lazy and individual backends
-  - Must be flexible to a given context (select, with_columns, filter, group_by)
-- Nodes & plans are:
-  - Immutable, but
-    - Can be extended/re-written at both the Narwhals & Compliant levels
-  - Introspectable, but
-    - Store as little-as-needed for the common case
-    - Provide properties/methods for computing the less frequent metadata
-
-References:
-- https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-python/src/lazyframe/visitor/expr_nodes.rs
-- https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-plan/src/dsl/expr.rs
-- https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-plan/src/dsl/function_expr/mod.rs
-- https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-plan/src/dsl/options/mod.rs#L137-L172
-- https://github.com/pola-rs/polars/blob/3fd7ecc5f9de95f62b70ea718e7e5dbf951b6d1c/crates/polars-plan/src/plans/options.rs#L35-L106
-- https://github.com/pola-rs/polars/blob/3fd7ecc5f9de95f62b70ea718e7e5dbf951b6d1c/crates/polars-plan/src/plans/options.rs#L131-L236
-- https://github.com/pola-rs/polars/blob/3fd7ecc5f9de95f62b70ea718e7e5dbf951b6d1c/crates/polars-plan/src/plans/options.rs#L240-L267
-- https://github.com/pola-rs/polars/blob/6df23a09a81c640c21788607611e09d9f43b1abc/crates/polars-plan/src/plans/aexpr/mod.rs
-
-Related:
-- https://github.com/narwhals-dev/narwhals/pull/2483#issuecomment-2866902903
-- https://github.com/narwhals-dev/narwhals/pull/2483#issuecomment-2867331343
-- https://github.com/narwhals-dev/narwhals/pull/2483#issuecomment-2867446959
-- https://github.com/narwhals-dev/narwhals/pull/2483#issuecomment-2869070157
-- (https://github.com/narwhals-dev/narwhals/pull/2538/commits/a7eeb0d23e67cb70e7cfa73cec2c7b69a15c8bef#r2083562677)
-- https://github.com/narwhals-dev/narwhals/issues/2225
-- https://github.com/narwhals-dev/narwhals/issues/1848
-- https://github.com/narwhals-dev/narwhals/issues/2534#issuecomment-2875676729
-- https://github.com/narwhals-dev/narwhals/issues/2291
-- https://github.com/narwhals-dev/narwhals/issues/2522
-- https://github.com/narwhals-dev/narwhals/pull/2555
-"""
-
 from __future__ import annotations

narwhals/_plan/aggregation.py

@@ -72,7 +72,6 @@ class Std(Agg):
     __slots__ = (*Agg.__slots__, "ddof")
 
     ddof: int
-    """https://github.com/narwhals-dev/narwhals/pull/2555"""
 
 
 class Sum(Agg): ...
@@ -82,7 +81,6 @@ class Var(Agg):
     __slots__ = (*Agg.__slots__, "ddof")
 
     ddof: int
-    """https://github.com/narwhals-dev/narwhals/pull/2555"""
 
 
 class OrderableAgg(Agg): ...

narwhals/_plan/categorical.py

@@ -17,7 +17,6 @@ class GetCategories(CategoricalFunction):
 
     @property
     def function_options(self) -> FunctionOptions:
-        """https://github.com/pola-rs/polars/blob/62257860a43ec44a638e8492ed2cf98a49c05f2e/crates/polars-plan/src/dsl/function_expr/cat.rs#L41."""
         return FunctionOptions.groupwise()
 
     def __repr__(self) -> str:

narwhals/_plan/expr.py

@@ -1,10 +1,4 @@
-"""Top-level `Expr` nodes.
-
-Todo:
-- `Selector`
-- `Ternary`
-- `Window` (investigate variants)
-"""
+"""Top-level `Expr` nodes."""
 
 from __future__ import annotations
 
@@ -489,10 +483,7 @@ class BinarySelector(
 
 
 class Ternary(ExprIR):
-    """When-Then-Otherwise.
-
-    Deferring this for now.
-    """
+    """When-Then-Otherwise."""
 
     __slots__ = ("falsy", "predicate", "truthy")
 

narwhals/_plan/functions.py

@@ -1,8 +1,4 @@
-"""General functions that aren't namespaced.
-
-Todo:
-- repr
-"""
+"""General functions that aren't namespaced."""
 
 from __future__ import annotations
 

narwhals/_plan/meta.py

@@ -1,7 +1,5 @@
 """`pl.Expr.meta` namespace functionality.
 
-- It seems like there might be a need to distinguish the top-level nodes for iterating
-  - polars_plan::dsl::expr::Expr
 - https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-plan/src/dsl/meta.rs#L11-L111
 - https://github.com/pola-rs/polars/blob/dafd0a2d0e32b52bcfa4273bffdd6071a0d5977a/crates/polars-plan/src/plans/iterator.rs#L10-L105
 """

narwhals/_plan/options.py

@@ -115,7 +115,6 @@ def aggregation() -> FunctionOptions:
         return FunctionOptions.groupwise().with_flags(FunctionFlags.RETURNS_SCALAR)
 
 
-# TODO @dangotbanned: Decide on constructors
 class SortOptions(Immutable):
     __slots__ = ("descending", "nulls_last")
 

narwhals/_plan/selectors.py

@@ -1,7 +1,7 @@
 """Deviations from `polars`.
 
 - A `Selector` corresponds to a `nw.selectors` function
-- Binary ops are represented as a subtype of `BinaryExpr`
+- Binary ops are represented as a `BinarySelector`, similar to `BinaryExpr`.
 """
 
 from __future__ import annotations