polars-learn 0.1.0__py3-none-any.whl

polars_learn/__init__.py

@@ -0,0 +1,23 @@
+"""Native Polars feature engineering and schema validation for scikit-learn."""
+
+from .exceptions import (
+    FeatureEngineeringError,
+    PandasConversionWarning,
+    PolarsLearnError,
+    SchemaValidationError,
+)
+from .feature_engineering import FeatureEngineer
+from .feature_spec import FeatureSpec
+from .schema_validation import SchemaValidator
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FeatureEngineer",
+    "FeatureSpec",
+    "SchemaValidator",
+    "PolarsLearnError",
+    "SchemaValidationError",
+    "FeatureEngineeringError",
+    "PandasConversionWarning",
+]

polars_learn/_utils.py

@@ -0,0 +1,143 @@
+"""Shared input conversion and estimator conventions."""
+
+import importlib
+import warnings
+from typing import Any, Self, cast
+
+import numpy as np
+import polars as pl
+from numpy.typing import NDArray
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted  # pyright: ignore[reportUnknownVariableType]
+
+from .exceptions import PandasConversionWarning
+from .types import FeatureNames, OutputMode
+
+
+def to_polars(
+    X: object, *, convert_pandas: bool, warn_on_conversion: bool
+) -> pl.DataFrame:
+    """Validate the container and optionally convert pandas input to Polars.
+
+    Parameters
+    ----------
+    X : object
+        Candidate eager DataFrame. NumPy arrays and LazyFrames are unsupported.
+    convert_pandas : bool
+        Whether pandas DataFrames may be converted with ``pl.from_pandas``.
+    warn_on_conversion : bool
+        Whether conversion emits ``PandasConversionWarning``.
+
+    Returns
+    -------
+    frame : polars.DataFrame
+        Original Polars input or converted pandas DataFrame.
+
+    Raises
+    ------
+    TypeError
+        If input is unsupported, conversion is disabled, or a conversion
+        dependency is unavailable.
+
+    Warns
+    -----
+    PandasConversionWarning
+        If pandas input is converted and warnings are enabled.
+    """
+    if isinstance(X, pl.DataFrame):
+        return X
+    # Inspect the MRO so subclasses work without importing pandas for native inputs.
+    if any(cls.__module__.startswith("pandas.") for cls in type(X).__mro__):
+        if not convert_pandas:
+            raise TypeError(
+                "Received pandas input; set convert_pandas=True to enable conversion."
+            )
+        try:
+            pd = importlib.import_module("pandas")
+        except ImportError as exc:
+            raise TypeError("Pandas conversion requires the 'pandas' extra.") from exc
+        if isinstance(X, pd.DataFrame):
+            try:
+                # Runtime isinstance above narrows an optional, lazily imported type.
+                result = cast(pl.DataFrame, pl.from_pandas(cast(Any, X)))  # pyright: ignore[reportUnknownMemberType, reportUnnecessaryCast]
+            except ImportError as exc:
+                raise TypeError(
+                    "This pandas dtype requires PyArrow; install polars-learn[pandas]."
+                ) from exc
+            if warn_on_conversion:
+                warnings.warn(
+                    "Received a pandas DataFrame and converted it to Polars. "
+                    "For optimal performance, provide a Polars DataFrame directly; "
+                    "conversion may add memory and performance overhead.",
+                    PandasConversionWarning,
+                    stacklevel=3,
+                )
+            return result
+    raise TypeError("Expected a Polars DataFrame (or explicitly enabled pandas input).")
+
+
+class NativeTransformer(TransformerMixin, BaseEstimator, auto_wrap_output_keys=None):
+    """Keep native output and extra columns free of wrapper renames."""
+
+    feature_names_in_: NDArray[np.object_]
+    n_features_in_: int
+    output_features_: NDArray[np.object_]
+
+    def get_feature_names_out(
+        self, input_features: FeatureNames | None = None
+    ) -> NDArray[np.object_]:
+        """Return the fitted output column names.
+
+        Parameters
+        ----------
+        input_features : array-like of str or None, default=None
+            If supplied, names must exactly match ``feature_names_in_``.
+
+        Returns
+        -------
+        feature_names_out : ndarray of shape (n_features_out_,), dtype=object
+            Copy of the fitted output names. For schema validators this
+            describes required columns, excluding inference-only extras.
+
+        Raises
+        ------
+        sklearn.exceptions.NotFittedError
+            If the transformer has not been fitted.
+        ValueError
+            If supplied input names differ from fitted names or order.
+        """
+        check_is_fitted(self, "output_features_")
+        if input_features is not None and not np.array_equal(
+            np.asarray(input_features, dtype=object), self.feature_names_in_
+        ):
+            raise ValueError("input_features must match feature_names_in_ exactly.")
+        return self.output_features_.copy()
+
+    # sklearn exposes set_output as an available_if descriptor.
+    def set_output(self, *, transform: OutputMode | None = None) -> Self:  # pyright: ignore[reportIncompatibleVariableOverride]
+        """Configure native output without automatic container conversion.
+
+        Parameters
+        ----------
+        transform : {"default", "polars"} or None, default=None
+            Both supported values return Polars DataFrames. ``None`` leaves
+            the configuration unchanged. Pandas output is unsupported.
+
+        Returns
+        -------
+        self : estimator instance
+            This transformer.
+
+        Raises
+        ------
+        ValueError
+            If an unsupported output container is requested.
+
+        Notes
+        -----
+        Automatic scikit-learn output wrapping and global output settings are
+        bypassed to preserve native names and permitted extra columns.
+        """
+        if transform not in (None, "default", "polars"):
+            raise ValueError("Only 'default' and 'polars' output are supported.")
+        return self

polars_learn/exceptions.py

@@ -0,0 +1,17 @@
+"""Public errors and warnings."""
+
+
+class PolarsLearnError(Exception):
+    """Base package exception."""
+
+
+class SchemaValidationError(PolarsLearnError):
+    """Raised when input schema validation fails."""
+
+
+class FeatureEngineeringError(PolarsLearnError):
+    """Raised when a feature transformation fails."""
+
+
+class PandasConversionWarning(UserWarning):
+    """Warning emitted when pandas input is converted."""

polars_learn/feature_engineering.py

@@ -0,0 +1,223 @@
+"""Sequential feature engineering for scikit-learn pipelines."""
+
+from collections.abc import Sequence
+from typing import Self
+
+import numpy as np
+import polars as pl
+from sklearn.utils.validation import check_is_fitted  # pyright: ignore[reportUnknownVariableType]
+
+from ._utils import NativeTransformer, to_polars
+from .exceptions import FeatureEngineeringError
+from .feature_spec import FeatureSpec
+from .types import Schema
+
+
+class FeatureEngineer(NativeTransformer, auto_wrap_output_keys=None):
+    """Apply ordered, stateless feature specifications to Polars DataFrames.
+
+    Parameters
+    ----------
+    features : sequence of FeatureSpec
+        Specifications evaluated in order. Later specifications may reference
+        earlier outputs. An empty sequence produces an identity transformation.
+        The constructor retains this parameter unchanged for estimator cloning.
+    convert_pandas : bool, default=False
+        Allow pandas DataFrames and convert them to Polars. Requires pandas;
+        some dtypes also require PyArrow. No conversion occurs for Polars input.
+    warn_on_conversion : bool, default=True
+        Emit ``PandasConversionWarning`` when converting pandas input.
+
+    Attributes
+    ----------
+    n_features_in_ : int
+        Number of columns observed during fitting.
+    feature_names_in_ : ndarray of shape (n_features_in_,), dtype=object
+        Input column names in training order.
+    input_schema_ : dict of str to polars.DataType
+        Input dtypes observed during fitting, independent of other estimators.
+    output_schema_ : dict of str to polars.DataType
+        Expected transformed names, order, and dtypes.
+    output_features_ : ndarray of shape (n_features_out_,), dtype=object
+        Output column names, including retained inputs and engineered features.
+
+    See Also
+    --------
+    FeatureSpec : Describe one feature operation.
+    SchemaValidator : Validate and normalise raw input before engineering.
+
+    Notes
+    -----
+    The public API accepts eager DataFrames. Internally, lazy operations retain
+    dependency order and collect once per execution. Fitting executes the
+    training transformation to validate it but learns no feature statistics.
+    Transform requires fitted input names and order and the fitted output schema.
+    Both default and explicitly requested Polars output remain native Polars.
+
+    Examples
+    --------
+    >>> import polars as pl
+    >>> from polars_learn import FeatureEngineer, FeatureSpec
+    >>> X = pl.DataFrame({"price": [10.0], "quantity": [2]})
+    >>> engineer = FeatureEngineer([
+    ...     FeatureSpec(pl.col("price") * pl.col("quantity"), alias="notional")
+    ... ])
+    >>> engineer.fit_transform(X)["notional"].to_list()
+    [20.0]
+    >>> engineer.get_feature_names_out().tolist()
+    ['price', 'quantity', 'notional']
+    """
+
+    def __init__(
+        self,
+        features: Sequence[FeatureSpec],
+        *,
+        convert_pandas: bool = False,
+        warn_on_conversion: bool = True,
+    ) -> None:
+        self.features = features
+        self.convert_pandas = convert_pandas
+        self.warn_on_conversion = warn_on_conversion
+
+    def _input(self, X: object) -> pl.DataFrame:
+        return to_polars(
+            X,
+            convert_pandas=self.convert_pandas,
+            warn_on_conversion=self.warn_on_conversion,
+        )
+
+    def _execute(self, frame: pl.DataFrame) -> pl.DataFrame:
+        if not isinstance(self.features, Sequence) or isinstance(self.features, str):
+            raise TypeError(
+                "features must be an ordered sequence of FeatureSpec objects."
+            )
+        plan = frame.lazy()
+        labels: list[str] = []
+        for index, spec in enumerate(self.features):
+            if not isinstance(spec, FeatureSpec):
+                raise TypeError(f"features[{index}] must be a FeatureSpec.")
+            label = spec.name or f"specification {index}: {spec!r}"
+            labels.append(label)
+            try:
+                plan = plan.with_columns(spec.expressions)
+                # Resolve each stage for precise dependency/drop errors, without
+                # materialising data until the final collect.
+                schema = plan.collect_schema()
+                missing = set(spec.drop) - set(schema.names())
+                if missing:
+                    raise ValueError(f"Cannot drop missing columns: {sorted(missing)}")
+                if spec.drop:
+                    plan = plan.drop(spec.drop)
+            except Exception as exc:
+                raise FeatureEngineeringError(
+                    f"Failed to generate {label}: {exc}"
+                ) from exc
+        try:
+            return plan.collect()
+        except Exception as exc:
+            raise FeatureEngineeringError(
+                f"Failed to execute feature plan ({'; '.join(labels)}): {exc}"
+            ) from exc
+
+    def fit(self, X: object, y: object = None) -> Self:
+        """Validate training expressions and learn input and output schemas.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_features)
+            Training data. Pandas input requires ``convert_pandas=True``.
+        y : object, default=None
+            Ignored. Present for scikit-learn estimator compatibility.
+
+        Returns
+        -------
+        self : FeatureEngineer
+            Fitted transformer.
+
+        Raises
+        ------
+        TypeError
+            If input or feature specifications have unsupported types.
+        FeatureEngineeringError
+            If expressions or drop operations fail. The underlying exception
+            is preserved as the cause.
+        """
+        frame = self._input(X)
+        result = self._execute(frame)
+        self.feature_names_in_ = np.asarray(frame.columns, dtype=object)
+        self.n_features_in_ = frame.width
+        self.input_schema_: Schema = dict(frame.schema)
+        self.output_schema_: Schema = dict(result.schema)
+        self.output_features_ = np.asarray(result.columns, dtype=object)
+        return self
+
+    def fit_transform(
+        self, X: object, y: object = None, **fit_params: object
+    ) -> pl.DataFrame:
+        """Fit to training data and return its transformed representation.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_features)
+            Training data. Pandas input requires ``convert_pandas=True``.
+        y : object, default=None
+            Ignored. Present for scikit-learn estimator compatibility.
+        **fit_params : dict
+            Accepted for the scikit-learn method signature. Additional fit
+            parameters are unsupported and raise ``TypeError`` when supplied.
+
+        Returns
+        -------
+        X_transformed : polars.DataFrame of shape (n_samples, n_features_out)
+            Result of fitting this transformer and transforming the same data.
+
+        See Also
+        --------
+        fit : Learn the fitted schema and feature names.
+        transform : Apply the fitted transformer and its validation policies.
+        """
+        if fit_params:
+            raise TypeError(
+                f"Additional fit parameters are unsupported: {sorted(fit_params)}."
+            )
+        return self.fit(X, y).transform(X)
+
+    def transform(self, X: object) -> pl.DataFrame:
+        """Generate features and verify the fitted output schema.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_features)
+            Input with the fitted column names and order. Pandas input requires
+            ``convert_pandas=True``. Input dtypes may differ only if the final
+            output schema still matches the fitted expectations.
+
+        Returns
+        -------
+        X_transformed : polars.DataFrame of shape (n_samples, n_features_out)
+            Retained and engineered columns in native Polars order.
+
+        Raises
+        ------
+        sklearn.exceptions.NotFittedError
+            If ``fit`` has not completed successfully.
+        TypeError
+            If the input is unsupported or pandas conversion is disabled.
+        FeatureEngineeringError
+            If input columns differ, feature execution fails, or the generated
+            output schema differs from the fitted schema.
+        """
+        check_is_fitted(self, "output_schema_")
+        frame = self._input(X)
+        if frame.columns != self.feature_names_in_.tolist():
+            raise FeatureEngineeringError(
+                f"Input columns must match fitted names and order. Expected "
+                f"{self.feature_names_in_.tolist()}, received {frame.columns}."
+            )
+        result = self._execute(frame)
+        if list(result.schema.items()) != list(self.output_schema_.items()):
+            raise FeatureEngineeringError(
+                f"Output schema differs from fit. Expected {self.output_schema_}, "
+                f"received {dict(result.schema)}."
+            )
+        return result

polars_learn/feature_spec.py

@@ -0,0 +1,122 @@
+"""Composable descriptions of native Polars feature operations."""
+
+from collections.abc import Sequence
+
+import polars as pl
+
+
+class FeatureSpec:
+    """Describe a native Polars feature operation.
+
+    Parameters
+    ----------
+    expression : polars.Expr or None, default=None
+        Single expression to evaluate. Specify exactly one of ``expression`` or
+        ``expressions``. Its native output name is used unless ``alias`` is set.
+    expressions : sequence of polars.Expr or None, default=None
+        Nonempty sequence of expressions evaluated together. Expressions within
+        one specification cannot reference columns created by siblings.
+    alias : str or None, default=None
+        Override the output name of a single expression. Multiple expressions
+        or an expression expanding to multiple outputs cannot use this option.
+    drop : sequence of str or None, default=None
+        Columns to remove after evaluating the expressions. Missing names fail
+        during execution; later specifications cannot use dropped columns.
+    name : str or None, default=None
+        Descriptive label included in feature execution errors.
+
+    Attributes
+    ----------
+    expressions : tuple of polars.Expr
+        Canonical expression representation, including any explicit alias.
+    drop : tuple of str
+        Columns to drop after evaluating this specification.
+    name : str or None
+        Optional debugging label.
+
+    Raises
+    ------
+    TypeError
+        If expressions, drop columns, or their containers have invalid types.
+    ValueError
+        If expression arguments conflict, expressions are empty, an explicit
+        alias is ambiguous, output names are duplicated, or a label is invalid.
+
+    See Also
+    --------
+    FeatureEngineer : Execute an ordered sequence of specifications.
+
+    Notes
+    -----
+    Existing columns may be overwritten deliberately. Expressions follow native
+    Polars naming, so an additional alias is not required when the expression
+    already has a determinable output name. Selector names and duplicates that
+    depend on the input schema are resolved by the feature engineer.
+
+    Examples
+    --------
+    >>> import polars as pl
+    >>> from polars_learn import FeatureSpec
+    >>> spec = FeatureSpec(
+    ...     pl.col("price") * pl.col("quantity"), alias="notional"
+    ... )
+    >>> spec.expressions[0].meta.output_name()
+    'notional'
+    """
+
+    def __init__(
+        self,
+        expression: pl.Expr | None = None,
+        *,
+        expressions: Sequence[pl.Expr] | None = None,
+        alias: str | None = None,
+        drop: Sequence[str] | None = None,
+        name: str | None = None,
+    ) -> None:
+        if (expression is None) == (expressions is None):
+            raise ValueError("Specify exactly one of expression or expressions.")
+        if expressions is not None and (
+            isinstance(expressions, (str, pl.Expr))
+            or not isinstance(expressions, Sequence)
+        ):
+            raise TypeError("expressions must be a sequence of Polars expressions.")
+        canonical = (
+            (expression,) if expression is not None else tuple(expressions or ())
+        )
+        if not canonical:
+            raise ValueError("expressions must not be empty.")
+        if any(not isinstance(expr, pl.Expr) for expr in canonical):
+            raise TypeError("Every expression must be a Polars Expr.")
+        if alias is not None:
+            if not isinstance(alias, str) or not alias:
+                raise ValueError("alias must be a nonempty string.")
+            if len(canonical) != 1 or canonical[0].meta.has_multiple_outputs():
+                raise ValueError("An explicit alias requires exactly one output.")
+            canonical = (canonical[0].alias(alias),)
+        names: list[str] = []
+        for expr in canonical:
+            if not expr.meta.has_multiple_outputs():
+                output_name = expr.meta.output_name(raise_if_undetermined=False)
+                if output_name is None:
+                    raise ValueError("Expression needs a determinable name or alias.")
+                names.append(output_name)
+        if len(names) != len(set(names)):
+            raise ValueError("Expressions have duplicate output names.")
+        if drop is not None and (
+            isinstance(drop, str)
+            or not isinstance(drop, Sequence)
+            or any(not isinstance(col, str) or not col for col in drop)
+        ):
+            raise TypeError("drop must be a sequence of nonempty column names.")
+        if name is not None and (not isinstance(name, str) or not name):
+            raise ValueError("name must be a nonempty string.")
+        self.expressions: tuple[pl.Expr, ...] = canonical
+        self.drop: tuple[str, ...] = tuple(drop or ())
+        self.name: str | None = name
+
+    def __repr__(self) -> str:
+        """Return the canonical specification representation."""
+        return (
+            f"FeatureSpec(expressions={self.expressions!r}, "
+            f"drop={self.drop!r}, name={self.name!r})"
+        )

polars_learn/schema_validation.py

@@ -0,0 +1,280 @@
+"""Learned schema validation and explicit, predictable type normalisation."""
+
+from typing import Self
+
+import numpy as np
+import polars as pl
+from sklearn.utils.validation import check_is_fitted  # pyright: ignore[reportUnknownVariableType]
+
+from ._utils import NativeTransformer, to_polars
+from .exceptions import SchemaValidationError
+from .types import ExtraColumnPolicy, Schema, ValidationMode
+
+_INTEGER_RANGES: dict[pl.DataType | type[pl.DataType], tuple[int, int]] = {
+    pl.Int8: (-(2**7), 2**7 - 1),
+    pl.Int16: (-(2**15), 2**15 - 1),
+    pl.Int32: (-(2**31), 2**31 - 1),
+    pl.Int64: (-(2**63), 2**63 - 1),
+    pl.UInt8: (0, 2**8 - 1),
+    pl.UInt16: (0, 2**16 - 1),
+    pl.UInt32: (0, 2**32 - 1),
+    pl.UInt64: (0, 2**64 - 1),
+}
+
+
+def _safe_widen(series: pl.Series, target: pl.DataType) -> bool:
+    """Return whether this series satisfies the lossless widening policy."""
+    source = series.dtype
+    if source in _INTEGER_RANGES and target in _INTEGER_RANGES:
+        source_min, source_max = _INTEGER_RANGES[source]
+        target_min, target_max = _INTEGER_RANGES[target]
+        return target_min <= source_min and source_max <= target_max
+    if source == pl.Float32 and target == pl.Float64:
+        return True
+    if source in _INTEGER_RANGES and target == pl.Float64:
+        try:
+            restored = series.cast(pl.Float64).cast(source, strict=True)
+            return bool((series == restored).fill_null(True).all())
+        except pl.exceptions.PolarsError:
+            return False
+    return False
+
+
+class SchemaValidator(NativeTransformer, auto_wrap_output_keys=None):
+    """Learn an input schema and validate subsequent Polars DataFrames.
+
+    Parameters
+    ----------
+    mode : {"strict", "semi-strict", "permissive"} or None, default=None
+        Validation policy. ``None`` resolves to strict mode unless ``strict``
+        is explicitly false. Strict mode requires identical dtypes. Semi-strict
+        allows only the documented lossless widening policy. Permissive mode
+        attempts strict Polars casts, which may be lossy but raise on failure.
+    allow_extra_columns : bool, default=False
+        Allow columns not present during fitting. Missing required columns
+        always raise, regardless of the validation mode.
+    enforce_column_order : bool, default=True
+        Require the relative order of required columns to match training.
+        If false, output uses fitted column order followed by preserved extras.
+    extra_columns : {"preserve", "drop"}, default="preserve"
+        Treatment of permitted extras. This option does not itself permit
+        extra columns; ``allow_extra_columns`` must also be true.
+    convert_pandas : bool, default=False
+        Allow pandas DataFrames and convert them to Polars. Requires pandas;
+        some dtypes also require PyArrow.
+    warn_on_conversion : bool, default=True
+        Emit ``PandasConversionWarning`` when converting pandas input.
+    strict : bool or None, default=None
+        Shorthand for strict mode when true or permissive mode when false.
+        Conflicting explicit ``mode`` and ``strict`` values raise ``ValueError``.
+
+    Attributes
+    ----------
+    schema_ : dict of str to polars.DataType
+        Learned required columns and dtypes, in training order.
+    n_features_in_ : int
+        Number of training columns.
+    feature_names_in_ : ndarray of shape (n_features_in_,), dtype=object
+        Required input names in training order.
+    output_features_ : ndarray of shape (n_features_in_,), dtype=object
+        Fitted required names. Inference-only extras are not included.
+
+    See Also
+    --------
+    FeatureEngineer : Engineer features after validating raw inputs.
+
+    Notes
+    -----
+    Semi-strict allows integer widening when the source dtype's entire range
+    fits inside the target dtype, Float32 to Float64, and integer to Float64
+    only when every non-null value round-trips exactly. It rejects string to
+    numeric conversion, narrowing, and Null dtype to another dtype. Null values
+    in compatible columns are preserved; nullability constraints are not learned.
+    Fit always learns a fresh schema; transform always validates against it.
+    Input data and schemas owned by other transformers are never mutated.
+
+    Examples
+    --------
+    >>> import polars as pl
+    >>> from polars_learn import SchemaValidator
+    >>> train = pl.DataFrame({"x": pl.Series([1], dtype=pl.Int64)})
+    >>> test = pl.DataFrame({"x": pl.Series([2], dtype=pl.Int32)})
+    >>> validator = SchemaValidator(mode="semi-strict").fit(train)
+    >>> validator.transform(test).schema["x"]
+    Int64
+    """
+
+    def __init__(
+        self,
+        mode: ValidationMode | None = None,
+        *,
+        allow_extra_columns: bool = False,
+        enforce_column_order: bool = True,
+        extra_columns: ExtraColumnPolicy = "preserve",
+        convert_pandas: bool = False,
+        warn_on_conversion: bool = True,
+        strict: bool | None = None,
+    ) -> None:
+        self.mode = mode
+        self.allow_extra_columns = allow_extra_columns
+        self.enforce_column_order = enforce_column_order
+        self.extra_columns = extra_columns
+        self.convert_pandas = convert_pandas
+        self.warn_on_conversion = warn_on_conversion
+        self.strict = strict
+
+    def _mode(self) -> ValidationMode:
+        if self.mode not in (None, "strict", "semi-strict", "permissive"):
+            raise ValueError("mode must be 'strict', 'semi-strict', or 'permissive'.")
+        if self.strict is not None and not isinstance(self.strict, bool):
+            raise TypeError("strict must be a bool or None.")
+        legacy = "strict" if self.strict is not False else "permissive"
+        if self.strict is not None and self.mode is not None and self.mode != legacy:
+            raise ValueError("strict and mode specify conflicting validation modes.")
+        if self.extra_columns not in ("preserve", "drop"):
+            raise ValueError("extra_columns must be 'preserve' or 'drop'.")
+        return self.mode or legacy
+
+    def _input(self, X: object) -> pl.DataFrame:
+        return to_polars(
+            X,
+            convert_pandas=self.convert_pandas,
+            warn_on_conversion=self.warn_on_conversion,
+        )
+
+    def fit(self, X: object, y: object = None) -> Self:
+        """Learn column names, order, and dtypes without changing the input.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_features)
+            Training data whose schema becomes the required schema. Pandas
+            input requires ``convert_pandas=True``.
+        y : object, default=None
+            Ignored. Present for scikit-learn estimator compatibility.
+
+        Returns
+        -------
+        self : SchemaValidator
+            Fitted validator with a newly learned schema.
+
+        Raises
+        ------
+        TypeError
+            If the input type is unsupported or pandas conversion is disabled.
+        ValueError
+            If validation configuration is invalid or conflicting.
+        """
+        self._mode()
+        frame = self._input(X)
+        self.schema_: Schema = dict(frame.schema)
+        self.feature_names_in_ = np.asarray(frame.columns, dtype=object)
+        self.n_features_in_ = frame.width
+        self.output_features_ = self.feature_names_in_.copy()
+        return self
+
+    def fit_transform(
+        self, X: object, y: object = None, **fit_params: object
+    ) -> pl.DataFrame:
+        """Fit to training data and return its transformed representation.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_features)
+            Training data. Pandas input requires ``convert_pandas=True``.
+        y : object, default=None
+            Ignored. Present for scikit-learn estimator compatibility.
+        **fit_params : dict
+            Accepted for the scikit-learn method signature. Additional fit
+            parameters are unsupported and raise ``TypeError`` when supplied.
+
+        Returns
+        -------
+        X_transformed : polars.DataFrame of shape (n_samples, n_features_out)
+            Result of fitting this transformer and transforming the same data.
+
+        See Also
+        --------
+        fit : Learn the fitted schema and feature names.
+        transform : Apply the fitted transformer and its validation policies.
+        """
+        if fit_params:
+            raise TypeError(
+                f"Additional fit parameters are unsupported: {sorted(fit_params)}."
+            )
+        return self.fit(X, y).transform(X)
+
+    def transform(self, X: object) -> pl.DataFrame:
+        """Validate the learned schema and normalise permitted differences.
+
+        Parameters
+        ----------
+        X : polars.DataFrame or pandas.DataFrame of shape (n_samples, n_columns)
+            Input containing all fitted required columns. Additional columns
+            must be explicitly permitted. Pandas requires conversion enabled.
+
+        Returns
+        -------
+        X_validated : polars.DataFrame of shape (n_samples, n_output_columns)
+            Validated input with any configured casts, ordering, and extra
+            column policy applied. The original input is never mutated.
+
+        Raises
+        ------
+        sklearn.exceptions.NotFittedError
+            If ``fit`` has not completed successfully.
+        TypeError
+            If the input is unsupported or pandas conversion is disabled.
+        SchemaValidationError
+            If required columns are missing, extras or order are disallowed,
+            dtypes are incompatible, or a cast fails. Multiple mismatches are
+            reported together, with cast exceptions preserved as the cause.
+        """
+        check_is_fitted(self, "schema_")
+        mode = self._mode()
+        frame = self._input(X)
+        expected_names = list(self.schema_)
+        missing = [col for col in expected_names if col not in frame.columns]
+        extras = [col for col in frame.columns if col not in self.schema_]
+        issues: list[str] = []
+        if missing:
+            issues.append(f"Missing required columns: {missing}.")
+        if extras and not self.allow_extra_columns:
+            issues.append(f"Unexpected columns: {extras}.")
+        present = [col for col in frame.columns if col in self.schema_]
+        if self.enforce_column_order and not missing and present != expected_names:
+            issues.append(
+                f"Column order differs. Expected {expected_names}, received {present}."
+            )
+        conversions: list[pl.Series] = []
+        cause: Exception | None = None
+        for column, target in self.schema_.items():
+            if column in missing:
+                continue
+            series = frame[column]
+            source = series.dtype
+            if source == target:
+                continue
+            detail = (
+                f"Column {column!r} has an incompatible type. "
+                f"Expected: {target}; Received: {source}; Validation mode: {mode}."
+            )
+            if mode == "strict" or (
+                mode == "semi-strict" and not _safe_widen(series, target)
+            ):
+                issues.append(detail)
+                continue
+            try:
+                conversions.append(series.cast(target, strict=True))
+            except pl.exceptions.PolarsError as exc:
+                cause = exc
+                issues.append(f"{detail} Cast failed: {exc}")
+        if issues:
+            raise SchemaValidationError("\n".join(issues)) from cause
+        result = frame.with_columns(conversions) if conversions else frame
+        if self.extra_columns == "drop" or not self.enforce_column_order:
+            columns = expected_names
+            if self.extra_columns == "preserve":
+                columns = columns + extras
+            result = result.select(columns)
+        return result

polars_learn/types.py

@@ -0,0 +1,15 @@
+"""Shared public type aliases."""
+
+from collections.abc import Sequence
+from typing import Literal, TypeAlias
+
+import numpy as np
+import polars as pl
+from numpy.typing import NDArray
+
+ValidationMode: TypeAlias = Literal["strict", "semi-strict", "permissive"]
+ExtraColumnPolicy: TypeAlias = Literal["preserve", "drop"]
+Schema: TypeAlias = dict[str, pl.DataType]
+
+OutputMode: TypeAlias = Literal["default", "polars"]
+FeatureNames: TypeAlias = Sequence[str] | NDArray[np.str_] | NDArray[np.object_]

polars_learn-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: polars-learn
+Version: 0.1.0
+Summary: Native Polars feature engineering and schema validation for scikit-learn
+Author: Jack
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: polars>=1.20
+Requires-Dist: scikit-learn>=1.6
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == 'pandas'
+Requires-Dist: pyarrow>=14; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# polars-learn
+
+High-performance feature engineering for scikit-learn, powered by Polars.
+
+## Features
+
+- Composable native Polars expressions, evaluated in dependency order.
+- Learned schemas with strict, semi-strict, and permissive validation.
+- scikit-learn estimators with cloning, parameters, and feature names.
+- Native Polars output and optional, explicit pandas conversion.
+- Python 3.11+, Polars 1.20+, and scikit-learn 1.6+.
+
+## Installation
+
+```bash
+uv add polars-learn
+# From a local checkout:
+uv pip install .
+# Optional pandas and PyArrow support:
+uv pip install '.[pandas]'
+```
+
+## Quick Start
+
+```python
+import polars as pl
+from polars_learn import FeatureEngineer, FeatureSpec, SchemaValidator
+
+X = pl.DataFrame({"price": [10.0, 20.0, 30.0], "quantity": [2, 3, 4]})
+validator = SchemaValidator(mode="strict").fit(X)
+validated = validator.transform(X)
+
+engineer = FeatureEngineer(
+    [
+        FeatureSpec(pl.col("price") * pl.col("quantity"), alias="notional"),
+        FeatureSpec(
+            pl.col("notional").log1p(),
+            alias="log_notional",
+            drop=["quantity"],
+        ),
+    ]
+)
+result = engineer.fit_transform(validated)
+print(result)
+print(engineer.get_feature_names_out())
+# ['price' 'notional' 'log_notional']
+```
+
+## Feature Engineering
+
+`FeatureSpec` accepts exactly one of `expression` (one `pl.Expr`) or `expressions` (a nonempty sequence of expressions). It stores a single canonical expression tuple. Names follow Polars conventions: an existing alias or a native output name needs no additional alias. An explicit `alias` overrides the name of one output; it is rejected for multiple outputs. Selectors and expression expansion are supported, with their output names resolved against the frame.
+
+```python
+spec = FeatureSpec(
+    expressions=[
+        (pl.col("ask") - pl.col("bid")).alias("spread"),
+        ((pl.col("ask") + pl.col("bid")) / 2).alias("mid"),
+    ],
+    drop=["ask", "bid"],
+    name="quote_features",
+)
+quotes = pl.DataFrame({"ask": [11.0], "bid": [9.0]})
+print(FeatureEngineer([spec]).fit_transform(quotes))
+```
+
+Expressions within one specification are evaluated together and cannot reference new columns created by siblings. Separate specifications execute sequentially; later ones can use earlier outputs. Drops happen after each specification. Missing expression inputs, missing drop columns, and duplicate output names raise `FeatureEngineeringError` (duplicate names detectable at construction raise `ValueError`). Overwriting existing columns is allowed and keeps Polars' column position. For example, `FeatureSpec(pl.col("price") + 1)` replaces `price`.
+
+`fit` executes the training transformation to validate expressions and learn output names and dtypes. `transform` requires the fitted input column names and order and the exact fitted output schema. Input dtype differences are acceptable only when the resulting schema remains identical; use `SchemaValidator` first for explicit input type policies. Empty feature lists are identity transforms. The public API accepts eager DataFrames; internally, lazy stages preserve sequential semantics and collect once per execution. Expressions are stateless; training transformations do not learn statistics. Use deterministic expressions to keep training and inference consistent.
+
+## Schema Validation
+
+```python
+validator = SchemaValidator(
+    mode="semi-strict",
+    allow_extra_columns=False,
+    enforce_column_order=True,
+)
+validator.fit(X)  # Always learns the raw input schema
+print(validator.schema_)
+validated = validator.transform(X)  # Always validates against that schema
+```
+
+| Mode               | Policy for differing dtypes                             |
+| ------------------ | ------------------------------------------------------- |
+| `strict` (default) | Reject every dtype difference.                          |
+| `semi-strict`      | Allow only the explicit lossless widening policy below. |
+| `permissive`       | Use Polars `cast(strict=True)` and report failures.     |
+
+Semi-strict allows integer widening when the entire source dtype's range fits inside the target integer dtype (including compatible unsigned-to-signed widening), Float32 → Float64, and integer → Float64 only when **every non-null value round-trips exactly**. For example, Int64 `2**53` and `2**54` are accepted, but `2**53 + 1` is rejected. It rejects narrowing, strings to numbers, and Null dtype to a different dtype. Null values in already compatible columns are preserved; nullability constraints are not part of this version.
+
+Permissive casts may be lossy according to Polars semantics, such as floats to integers. Failed casts never silently replace invalid values with nulls. Missing required columns always fail; multiple schema mismatches are reported in `SchemaValidationError`. Strict mode does not cast or rename columns.
+
+Extra columns fail by default. Set `allow_extra_columns=True` to preserve them, or also set `extra_columns="drop"` to explicitly remove them. Column order checks compare the relative order of required columns; permitted extras may appear anywhere. With `enforce_column_order=False`, output is normalised to fitted column order, followed by preserved extras in their input order. `get_feature_names_out()` describes fitted required columns; inference-only extras are not included. Avoid preserving inference-only extras before a fixed-width downstream estimator or `FeatureEngineer`.
+
+The shorthand `strict=True` means strict mode, and `strict=False` means permissive mode. Conflicting `strict` and `mode` arguments are rejected. Schemas learned by the validator and feature engineer are independent.
+
+## scikit-learn Pipelines
+
+```python
+import numpy as np
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+pipeline = Pipeline(
+    [
+        ("schema", SchemaValidator(mode="semi-strict")),
+        ("features", engineer),
+        ("scale", StandardScaler().set_output(transform="polars")),
+        ("model", RandomForestRegressor(n_estimators=20, random_state=0)),
+    ]
+)
+pipeline.fit(X, np.array([1.0, 2.0, 3.0]))
+print(pipeline.predict(X))
+print(pipeline[:-1].get_feature_names_out())
+```
+
+These transformers implement `fit`, `transform`, `fit_transform`, `get_params`, `set_params`, and `get_feature_names_out`. Fitted attributes include `feature_names_in_`, `n_features_in_`, and `output_features_`. Cloning discards fitted state. Supplied `input_features` must exactly match fitted input names.
+
+Data stays in Polars between our transformers. Both support `set_output(transform="default")` and `set_output(transform="polars")`, which return native Polars frames. They reject `"pandas"` output and deliberately bypass scikit-learn's automatic output wrapping, including global output settings, to preserve native names and allowed extras. No automatic NumPy conversion occurs. Downstream estimator support for Polars depends on the estimator and installed scikit-learn version; arbitrary string columns do not work with random forests.
+
+Tests run applicable scikit-learn constructor, parameter, and cloning checks. Generic checks requiring NumPy array input do not apply to this deliberately DataFrame-only API. No LazyFrame, sparse-array, or NumPy input is accepted.
+
+## Optional Pandas Support
+
+```bash
+uv sync --extra pandas
+```
+
+```python
+# Requires the pandas extra; both transformers expose these options.
+import pandas as pd
+
+pandas_X = pd.DataFrame({"price": [10.0, 20.0], "quantity": [2, 3]})
+validator = SchemaValidator(convert_pandas=True, warn_on_conversion=False)
+polars_X = validator.fit_transform(pandas_X)
+```
+
+Pandas input is rejected unless `convert_pandas=True`. Conversion returns Polars and emits `PandasConversionWarning` about memory and performance overhead unless `warn_on_conversion=False`. Imports are lazy; core functionality works without pandas or PyArrow. The extra includes PyArrow because nullable, extension, and other non-NumPy-backed pandas dtypes can require it for `pl.from_pandas`. Conversion follows Polars conventions (including NaN-to-null and ignoring the pandas index). Unsupported conversion dtypes raise rather than falling back to row-wise operations.
+
+## Development
+
+```bash
+uv sync
+uv sync --extra pandas     # Optional interoperability test coverage
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv build
+```
+
+`uv.lock` pins reproducible development dependencies. Pyright includes its Node runtime through the development extra, so no system Node installation is needed. Pandas tests use `pytest.importorskip("pandas")`; core tests also run without the optional extra. The package ships `py.typed` for downstream typing tools.
+
+Library requirements use minimum versions without speculative upper bounds. Add an upper bound or exclude a release only when a known incompatibility requires it; the lockfile pins the development environment without constraining downstream applications.
+
+### Releases
+
+GitHub Actions follows the same release setup as Conformity. Configure the repository or `pypi` environment secret `PYPI_API_TOKEN` with a PyPI upload token for `polars-learn`. The publishing job uses the `pypi` environment. No API token belongs in this repository.
+
+Update `project.version` in `pyproject.toml` and `__version__` in `src/polars_learn/__init__.py`, run `uv lock`, and push the changes. Then run **Create GitHub Release** from the Actions tab. It checks tests, linting, formatting, and types; rejects an existing `vX.Y.Z` tag; builds and validates distributions; creates a GitHub release with those files; and passes the same artifacts directly to **Upload Python Package** for PyPI publishing. The reusable workflow call is necessary because a release created with GitHub's workflow token does not trigger another release workflow.
+
+Alternatively, publish a GitHub release tagged `vX.Y.Z` matching `project.version`. **Upload Python Package** checks the package, builds distributions, and publishes them automatically. Pushes and pull requests run **Tests** on Python 3.11 and 3.12, both with and without the pandas extra. Creating or publishing a release uploads that version to PyPI; ordinary pushes do not publish packages.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

polars_learn-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+polars_learn/__init__.py,sha256=iteuOV22jzl0YR6_LVenPyEvCssDHIex2xcisJta6sk,568
+polars_learn/_utils.py,sha256=SdVXWmRNWHV-NCigjy3IlPDfvQezolr8TMHMY_O0m14,5380
+polars_learn/exceptions.py,sha256=XaO_9T_QIt6_tOQLjTcdFxyL8oyjgLQHcCfymtJMwnI,416
+polars_learn/feature_engineering.py,sha256=IjtFpkTqOQbEaZ8iJrjBjfR_dj4V20f4AtihQI7f9SE,9048
+polars_learn/feature_spec.py,sha256=mQUwrx6UUtoWWqgrakz38GVlKFBCdiwJ9vNzCtYPQyo,5075
+polars_learn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polars_learn/schema_validation.py,sha256=cw6sCFfNHjsFElSbaGqY7X-Jm95JUYFi0Zwe7t7foS4,11951
+polars_learn/types.py,sha256=WLxyQouJhhF8MGDehZWuSoSosWNj8feHKHHYuOwdW10,496
+polars_learn-0.1.0.dist-info/METADATA,sha256=VOzCRXCqSn4LrLJ1OM3SW2I1V02geQB-7aVEoumLVRk,10792
+polars_learn-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+polars_learn-0.1.0.dist-info/licenses/LICENSE,sha256=udA5kf7HpCT8TszrVTQLu2HDngsJlAq3GVMoFu0_wgc,1061
+polars_learn-0.1.0.dist-info/RECORD,,

polars_learn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

polars_learn-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.