From 685a75226e90de4546e7aaf7d9724d66e5b54458 Mon Sep 17 00:00:00 2001 From: xillig <56161060+xillig@users.noreply.github.com> Date: Wed, 11 Nov 2026 05:32:35 +0100 Subject: [PATCH] fix(preprocessor): clear the stale mark after a successful fit mark_stale() flags the current fitted state as outdated. Fitting the same object again replaced that state, but lifecycle_state_ kept reporting STALE with the old reason, so a freshly fitted preprocessor looked unusable. A successful fit now removes the mark and the state returns to FITTED. A fit that raises leaves the mark in place. The attribute is removed rather than reset, so the spec and fingerprint of a never-stale preprocessor are unchanged. --- docs/core_concepts/reproducibility.md | 4 +- pretab/preprocessor.py | 9 +++- tests/integration/test_frozen_lifecycle.py | 49 +++++++++++++++++++++- 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/docs/core_concepts/reproducibility.md b/docs/core_concepts/reproducibility.md index 63755dd..06e572c 100644 --- a/docs/core_concepts/reproducibility.md +++ b/docs/core_concepts/reproducibility.md @@ -109,7 +109,9 @@ pre.set_params(...) # raises FrozenRepresentationError while frozen Freezing is useful when a representation is validated and about to ship. To make a fresh, unfrozen copy, use `clone_unfitted()`. To retrain, `refit(X, y)` returns a **new** fitted object and leaves the original untouched, and `mark_stale(reason)` records why an existing one -should no longer be used. +should no longer be used. The mark is advisory and describes the current fitted state: fitting +the same (unfrozen) object again with `fit` replaces that state, so a successful `fit` clears +the mark and the state returns to `FITTED`. ```{warning} `fit`, `fit_transform`, and `set_params` on a frozen preprocessor raise `FrozenRepresentationError`. This is deliberate: diff --git a/pretab/preprocessor.py b/pretab/preprocessor.py index aaba9df..20b07a1 100644 --- a/pretab/preprocessor.py +++ b/pretab/preprocessor.py @@ -709,6 +709,11 @@ def fit(self, X, y=None, embeddings=None): self._enforce_output_budget(X.shape[0]) + # This fit replaces the fitted state that mark_stale() flagged as outdated. + # The attribute is removed instead of reset, so a spec of a never-stale + # preprocessor is unchanged. + self.__dict__.pop("_stale_reason", None) + if verbose >= 1: numerical_summary = _method_summary(numerical_features, is_numerical=True, config=config) categorical_summary = _method_summary(categorical_features, is_numerical=False, config=config) @@ -1512,7 +1517,9 @@ def mark_stale(self, reason: str) -> "Preprocessor": Records ``reason`` and flips :attr:`lifecycle_state_` to ``STALE`` (unless already ``FROZEN``). Purely advisory: it does not alter the fitted state. - Returns ``self`` for chaining. + A later successful :meth:`fit` of this object replaces that state, so it + clears the mark and the state returns to ``FITTED``; a ``fit`` that raises + leaves the mark in place. Returns ``self`` for chaining. """ check_is_fitted(self) self._stale_reason = reason diff --git a/tests/integration/test_frozen_lifecycle.py b/tests/integration/test_frozen_lifecycle.py index 9c491c7..c77c96b 100644 --- a/tests/integration/test_frozen_lifecycle.py +++ b/tests/integration/test_frozen_lifecycle.py @@ -9,7 +9,7 @@ import pandas as pd import pytest -from pretab import FrozenRepresentationError, Preprocessor +from pretab import FrozenRepresentationError, OutputBudgetError, Preprocessor @pytest.fixture @@ -101,6 +101,53 @@ def test_mark_stale(frame, target): assert p.stale_reason_ == "input schema drifted" +def test_fit_clears_the_stale_mark(frame, target): + """A successful fit replaces the state the mark described; it used to stay STALE.""" + p = _make().fit(frame, target) + p.mark_stale("drift") + p.fit(frame.assign(a=frame["a"] * 2), target) + assert p.lifecycle_state_ == "FITTED" + assert p.stale_reason_ is None + + +def test_fit_transform_clears_the_stale_mark(frame, target): + p = _make().fit(frame, target) + p.mark_stale("drift") + p.fit_transform(frame, target) + assert p.lifecycle_state_ == "FITTED" + assert p.stale_reason_ is None + + +def test_failed_fit_keeps_the_stale_mark(frame, target): + p = _make().fit(frame, target) + p.mark_stale("drift") + p.set_params(max_output_features=1) + with pytest.raises(OutputBudgetError): + p.fit(frame, target) + assert p.stale_reason_ == "drift" + + +def test_fit_does_not_add_stale_state_to_the_spec(frame, target): + """Clearing the mark removes the attribute, so specs of never-stale fits are unchanged.""" + never_stale = _make().fit(frame, target) + assert "_stale_reason" not in never_stale.to_spec()["state"] + + refitted = _make().fit(frame, target) + refitted.mark_stale("drift") + refitted.fit(frame, target) + assert refitted.to_spec()["state"] == never_stale.to_spec()["state"] + assert refitted.fingerprint_ == never_stale.fingerprint_ + + +def test_stale_mark_survives_a_spec_round_trip_until_refit(frame, target): + p = _make().fit(frame, target) + p.mark_stale("drift") + restored = Preprocessor.from_spec(p.to_spec()) + assert restored.lifecycle_state_ == "STALE" + restored.fit(frame, target) + assert restored.lifecycle_state_ == "FITTED" + + def test_frozen_takes_precedence_over_stale(frame, target): p = _make().fit(frame, target) p.mark_stale("drift")