cleanframe-engine 0.3.0__tar.gz → 0.3.1__tar.gz

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-09-04
+
+First follow-up to the 0.3.0 release, from the CI and code-scanning results that
+only appear once a project is public.
+
+### Fixed
+
+- **`Severity` comparisons were alphabetical, not ordered.** Only `__lt__` was
+  defined, so the `str` mixin answered everything else: `Severity.ERROR >
+  Severity.INFO` returned `False` because `"error" < "info"` as text. All four
+  comparisons are now defined on the severity rank. Library code always used
+  `.rank` explicitly, so nothing internal was affected, but any caller comparing
+  severities directly got wrong answers. Found by CodeQL's incomplete-ordering
+  query.
+- **`mypy` failed in CI** with `numpy/__init__.pyi:737: error: Type statement is
+  only supported in Python 3.12 and greater`. The `python_version = "3.10"` pin
+  also governs how dependency stubs are parsed, and numpy 2.5's stubs use syntax
+  that needs 3.12. Removed the pin; minimum-version support is still checked by
+  ruff's `target-version` and by the Python 3.10 test job.
+- **The wiki sync workflow could not push.** GitHub Actions' built-in token can
+  clone a wiki but not write to it, so the job committed and then failed on
+  authentication. It now requires the `WIKI_TOKEN` secret and stops up front with
+  an explanatory message. `wiki/README.md` claimed no token was needed; corrected.
+- Two module-level import cycles removed: `profile` with `ops`, and `recipe` with
+  `validate`. `COMMON_DATE_FORMATS` now lives in `ops`, which owns date parsing,
+  and is re-exported from `profile` so every existing import keeps working.
+  `validate` imports `ValidationRule` for annotations only.
+- Empty exception handlers in `fingerprint` and `report` replaced with a helper
+  that returns whether a cell is missing, so the intent is in the code rather
+  than in a comment beside `pass`.
+- Redundant function-level `import re` in the dates detector removed; it now
+  reuses the module's compiled pattern instead of recompiling per call.
+
+### Changed
+
+- Workflow actions updated: checkout to v7, setup-python to v7, upload-artifact
+  to v7, download-artifact to v8, codeql-action to v4. Clears the Node 20
+  deprecation warnings.
+- Dependabot groups the `github-actions` ecosystem, so action bumps arrive as one
+  pull request instead of one per action.
+- CodeQL analyses the library and skips `tests`. Test fixtures are deliberately
+  hostile (catastrophic-backtracking patterns, injection payloads, handlers that
+  assert something must not raise) and are not part of the wheel, so reporting
+  them buries real findings. Configuration lives in
+  `.github/codeql/codeql-config.yml`.
+- Protocol methods on `LLMClient` and `Planner` carry a docstring instead of a
+  bare `...`.
+- Installation docs link the package page, show how to pin a version, and mention
+  `cleanframe --version`. `CHANGELOG.md` gained the Keep a Changelog link
+  definitions now that releases are tagged.
+
+### Verified
+
+335 tests pass on Python 3.10 with the declared minimum pins (pandas 1.5.3,
+numpy 1.23.5), on Python 3.13 with pandas 2.3.3, and on Python 3.13 with pandas
+3.0.5 and numpy 2.5.2, which is what a fresh `pip install` resolves today.
+
 ## [0.3.0] — 2026-09-04
 
 Release-readiness pass driven by a full audit of the CLI, the Python API, packaging and
@@ -233,3 +290,9 @@ now fail loudly, and a few transforms that quietly corrupted data no longer run.
 - Initial public release: profiler, detectors, rules + optional LLM planner, recipe YAML,
   deterministic executor, validation/quarantine, cell-level diff, schema drift, HTML reports,
   codegen, and CLI.
+
+[Unreleased]: https://github.com/inboxpraveen/Cleanframe/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/inboxpraveen/Cleanframe/releases/tag/v0.3.1
+[0.3.0]: https://github.com/inboxpraveen/Cleanframe/releases/tag/v0.3.0
+[0.2.0]: https://github.com/inboxpraveen/Cleanframe/commits/main
+[0.1.0]: https://github.com/inboxpraveen/Cleanframe/commits/main

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cleanframe-engine
-Version: 0.3.0
+Version: 0.3.1
 Summary: The reproducible data-cleaning engine for Python. AI writes the recipe once; the recipe runs forever — deterministic, diffable, reviewable.
 Project-URL: Homepage, https://github.com/inboxpraveen/Cleanframe
 Project-URL: Repository, https://github.com/inboxpraveen/Cleanframe
@@ -291,7 +291,7 @@ pip install "cleanframe-engine[all]"
 pip install "cleanframe-engine @ git+https://github.com/inboxpraveen/Cleanframe"
 ```
 
-Python 3.10+. The distribution is `cleanframe-engine`; the import package is
+Python 3.10+. The distribution is [`cleanframe-engine`](https://pypi.org/project/cleanframe-engine/); the import package is
 `cleanframe` (`import cleanframe as cf`), and the CLI is `cleanframe` (or
 `python -m cleanframe`).
 

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/README.md

@@ -241,7 +241,7 @@ pip install "cleanframe-engine[all]"
 pip install "cleanframe-engine @ git+https://github.com/inboxpraveen/Cleanframe"
 ```
 
-Python 3.10+. The distribution is `cleanframe-engine`; the import package is
+Python 3.10+. The distribution is [`cleanframe-engine`](https://pypi.org/project/cleanframe-engine/); the import package is
 `cleanframe` (`import cleanframe as cf`), and the CLI is `cleanframe` (or
 `python -m cleanframe`).
 

cleanframe_engine-0.3.1/cleanframe/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/codegen.py

@@ -45,11 +45,11 @@ def _constants_source() -> str:
         _KNOWN_CODES,
         _UNIT_ALIASES,
         _UNIT_TO_FAMILY,
+        COMMON_DATE_FORMATS,
         CURRENCY_SYMBOLS,
         DEFAULT_NA_TOKENS,
         UNIT_FAMILIES,
     )
-    from .profile import COMMON_DATE_FORMATS
 
     unit_factors = {u: f for fam in UNIT_FAMILIES.values() for u, f in fam.items()}
     na_tokens = sorted({t.casefold() for t in DEFAULT_NA_TOKENS})  # includes '' (H9)

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/detectors/dates.py

@@ -175,11 +175,9 @@ def detect_dates(series: pd.Series, ctx: DetectorContext) -> Issues:
 
 def _is_ambiguous(values: list[str]) -> bool:
     """True if no value disambiguates day-vs-month order (all numeric components <= 12)."""
-    import re
-
     saw_slashlike = False
     for v in values:
-        m = re.match(r"^\s*(\d{1,2})[/\-.](\d{1,2})[/\-.]\d{2,4}\s*$", v)
+        m = _SLASH_DATE_RE.match(v)
         if not m:
             continue
         saw_slashlike = True

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/fingerprint.py

@@ -17,20 +17,24 @@ import pandas as pd
 DEFAULT_SAMPLE_ROWS = 200
 
 
+def _is_missing(value: Any) -> bool:
+    """True for None/NaN/NaT. An exotic cell pd.isna cannot judge counts as present."""
+    if value is None:
+        return True
+    try:
+        return bool(pd.isna(value))  # raises on array-like; cells are scalars here
+    except (TypeError, ValueError):
+        return False
+
+
 def _canonical(value: Any) -> str:
     """Render a single cell to a stable string.
 
     ``NaN``/``None`` collapse to a single sentinel so that a missing value hashes
     the same whether it arrived as ``float('nan')``, ``None``, or ``pd.NA``.
     """
-    if value is None:
+    if _is_missing(value):
         return "\x00NA\x00"
-    # pd.isna raises on array-like; cells are scalars here.
-    try:
-        if pd.isna(value):
-            return "\x00NA\x00"
-    except (TypeError, ValueError):
-        pass
     if isinstance(value, float):
         # repr(float) is round-trippable and stable across platforms in CPython.
         return repr(value)

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/llm.py

@@ -61,7 +61,8 @@ class LLMClient(Protocol):
 
     model: str
 
-    def complete(self, system: str, user: str, *, max_tokens: int = 2048) -> LLMResponse: ...
+    def complete(self, system: str, user: str, *, max_tokens: int = 2048) -> LLMResponse:
+        """Return the model's reply plus token accounting."""
 
 
 class AnthropicClient:

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/ops.py

@@ -749,6 +749,34 @@ def round_op(series: pd.Series, decimals: int = 0) -> pd.Series:
 # ---------------------------------------------------------------------------
 # Date ops
 # ---------------------------------------------------------------------------
+#: Candidate date formats, ordered most-specific first. Shared with the dates
+#: detector so profiling and planning agree on what "a date" looks like. Pure
+#: all-digit formats are intentionally excluded to avoid classifying plain
+#: integers (``"20240101"``, ``"1200"``) as dates.
+COMMON_DATE_FORMATS = [
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%d",
+    "%Y/%m/%d",
+    "%d/%m/%Y",
+    "%m/%d/%Y",
+    "%d-%m-%Y",
+    "%m-%d-%Y",
+    "%d.%m.%Y",
+    "%d/%m/%y",
+    "%m/%d/%y",
+    "%d-%m-%y",
+    "%d %b %Y",
+    "%d %B %Y",
+    "%b %d, %Y",
+    "%B %d, %Y",
+    "%d-%b-%Y",
+    "%d-%b-%y",
+    "%b %d %Y",
+    "%d %b %y",
+]
+
+
 def _coerce_parse_date(raw: Any) -> dict:
     raw = raw or {}
     if not isinstance(raw, dict):
@@ -819,8 +847,6 @@ def parse_dates_to_datetime(
         # and NOT order-dependent, unlike a bare format-less pd.to_datetime which locks
         # onto the first row's inferred format and silently nulls otherwise-valid dates
         # (and behaves differently across pandas versions).
-        from .profile import COMMON_DATE_FORMATS
-
         formats = list(COMMON_DATE_FORMATS)
         flex_fallback = True
 
@@ -1238,6 +1264,7 @@ __all__ = [
     "apply_frame_op",
     "parse_dates_to_datetime",
     "parse_unit_scalar",
+    "COMMON_DATE_FORMATS",
     "CAST_TARGETS",
     "UNIT_FAMILIES",
     "CURRENCY_SYMBOLS",

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/planner.py

@@ -83,7 +83,8 @@ class Planner(Protocol):
         schema: Any | None = None,
         mode: Mode | str = Mode.REVIEW,
         options: dict[str, Any] | None = None,
-    ) -> Recipe: ...
+    ) -> Recipe:
+        """Return a recipe for ``df``, honouring the mode's confidence policy."""
 
 
 def _op_key(op: Op) -> tuple[str, str]:

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/profile.py

@@ -19,7 +19,7 @@ from typing import Any
 
 import pandas as pd
 
-from .ops import CURRENCY_SYMBOLS, parse_unit_scalar
+from .ops import COMMON_DATE_FORMATS, CURRENCY_SYMBOLS, parse_unit_scalar
 
 PATTERN_SAMPLE_CAP = 5000
 
@@ -37,32 +37,8 @@ _TIMESTAMPISH_RE = re.compile(r"\d{4}-\d{2}-\d{2}|\d{1,2}:\d{2}")
 _DIGIT_RE = re.compile(r"\d")
 _BOOL_TOKENS = {"true", "false", "yes", "no", "t", "f", "y", "n"}
 
-#: Candidate date formats, ordered most-specific first. Shared with the dates
-#: detector so profiling and planning agree on what "a date" looks like. Pure
-#: all-digit formats are intentionally excluded to avoid classifying plain
-#: integers (``"20240101"``, ``"1200"``) as dates.
-COMMON_DATE_FORMATS = [
-    "%Y-%m-%dT%H:%M:%S",
-    "%Y-%m-%d %H:%M:%S",
-    "%Y-%m-%d",
-    "%Y/%m/%d",
-    "%d/%m/%Y",
-    "%m/%d/%Y",
-    "%d-%m-%Y",
-    "%m-%d-%Y",
-    "%d.%m.%Y",
-    "%d/%m/%y",
-    "%m/%d/%y",
-    "%d-%m-%y",
-    "%d %b %Y",
-    "%d %B %Y",
-    "%b %d, %Y",
-    "%B %d, %Y",
-    "%d-%b-%Y",
-    "%d-%b-%y",
-    "%b %d %Y",
-    "%d %b %y",
-]
+#: Re-exported from :mod:`cleanframe.ops`, which owns date parsing. Imported here
+#: because profiling and schema inference both classify against the same table.
 
 # Column-name hints (lowercased substrings) that nudge ambiguous classifications.
 _NAME_HINTS = {

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/report.py

@@ -218,14 +218,19 @@ _CLEAN_BODY = """
 """
 
 
-def _fmt_cell(value: Any) -> str:
-    if value is None or (isinstance(value, float) and pd.isna(value)):
-        return "∅"
+def _is_missing(value: Any) -> bool:
+    """True for None/NaN/NaT. An exotic cell pd.isna cannot judge counts as present."""
+    if value is None:
+        return True
     try:
-        if pd.isna(value):
-            return "∅"
+        return bool(pd.isna(value))
     except (TypeError, ValueError):
-        pass
+        return False
+
+
+def _fmt_cell(value: Any) -> str:
+    if _is_missing(value):
+        return "∅"
     return str(value)
 
 

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/types.py

@@ -58,11 +58,29 @@ class Severity(str, Enum):
     def rank(self) -> int:
         return {"info": 0, "warning": 1, "error": 2}[self.value]
 
+    # All four comparisons are spelled out. The ``str`` mixin already provides
+    # lexicographic versions, so ``functools.total_ordering`` would leave them in
+    # place and "error" < "info" would silently compare as text.
     def __lt__(self, other: object) -> bool:
         if isinstance(other, Severity):
             return self.rank < other.rank
         return NotImplemented
 
+    def __le__(self, other: object) -> bool:
+        if isinstance(other, Severity):
+            return self.rank <= other.rank
+        return NotImplemented
+
+    def __gt__(self, other: object) -> bool:
+        if isinstance(other, Severity):
+            return self.rank > other.rank
+        return NotImplemented
+
+    def __ge__(self, other: object) -> bool:
+        if isinstance(other, Severity):
+            return self.rank >= other.rank
+        return NotImplemented
+
 
 class LLMExposure(str, Enum):
     """How much of your data an LLM planner is permitted to see.

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/cleanframe/validate.py

@@ -24,7 +24,7 @@ import re
 import warnings
 from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import pandas as pd
@@ -33,9 +33,11 @@ import yaml
 from ._util import safe_compile_regex
 from .errors import CleanFrameWarning, RecipeError, ValidationFailure
 from .profile import EMAIL_RE, URL_RE
-from .recipe import ValidationRule
 from .types import Mode
 
+if TYPE_CHECKING:  # annotations only — importing it at runtime would cycle
+    from .recipe import ValidationRule
+
 # ---------------------------------------------------------------------------
 # Validator registry (named checks)
 # ---------------------------------------------------------------------------

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/docs/installation.md

@@ -15,6 +15,20 @@ The distribution name on PyPI is `cleanframe-engine`; the import package is
 `cleanframe` (`import cleanframe as cf`), and the CLI is `cleanframe` — or
 `python -m cleanframe`, an equivalent alias for every invocation.
 
+Package page: [https://pypi.org/project/cleanframe-engine/](https://pypi.org/project/cleanframe-engine/)
+
+Pin a version in a requirements file the usual way:
+
+```
+cleanframe-engine==0.3.1
+```
+
+Check what you got:
+
+```bash
+cleanframe --version
+```
+
 ### Extras
 
 | Extra | Installs | Needed for |

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/pyproject.toml

@@ -95,7 +95,9 @@ filterwarnings = [
 ]
 
 [tool.mypy]
-python_version = "3.10"
+# No python_version pin: it also governs how dependency stubs are parsed, and
+# numpy's stubs use syntax that only parses on 3.12+. Minimum-version support is
+# covered by ruff's target-version and by the 3.10 test job.
 ignore_missing_imports = true
 files = ["cleanframe"]
 

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/tests/test_audit_hardening.py

@@ -124,8 +124,7 @@ def test_openai_base_url_does_not_hijack_openrouter(monkeypatch):
     monkeypatch.setenv("OPENAI_BASE_URL", "https://evil.example/v1")
     monkeypatch.setenv("OPENROUTER_API_KEY", "sk-test")
     client = get_client("openrouter/google/gemma-4-26b-a4b-it")
-    assert "openrouter.ai" in (client._base_url or "")
-    assert "evil.example" not in (client._base_url or "")
+    assert client._base_url == "https://openrouter.ai/api/v1"
 
 
 def test_openai_base_url_still_applies_to_openai(monkeypatch):

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/tests/test_llm_schema.py

@@ -56,7 +56,7 @@ def test_sample_exposure_anonymizes_and_shuffles():
     email_col = next(c for c in md["columns"] if c["name"] == "Email")
     assert email_col["example_values"]
     assert all("@" in v for v in email_col["example_values"])
-    assert "example.com" in email_col["example_values"][0]
+    assert email_col["example_values"][0] == "user@example.com"
     # deterministic across calls
     md2 = build_metadata(df, profile_dataframe(df), Issues(), None, LLMExposure.SAMPLE)
     assert md["columns"][0]["example_values"] == md2["columns"][0]["example_values"]
@@ -81,7 +81,7 @@ def test_get_client_resolves_openai_compatible_providers(monkeypatch):
     assert groq._api_key == "groq-key"
 
     gemini = get_client("gemini/gemini-2.0-flash")  # alias for google
-    assert "generativelanguage.googleapis.com" in (gemini._base_url or "")
+    assert gemini._base_url == "https://generativelanguage.googleapis.com/v1beta/openai/"
 
     ollama = get_client("ollama/llama3.2")
     assert ollama._base_url == "http://localhost:11434/v1"

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/tests/test_release_hardening.py

@@ -187,6 +187,16 @@ def test_unknown_or_wrongly_typed_op_parameters_are_refused(op):
         Recipe.from_dict({"version": 1, "columns": {"a": {"ops": [op]}}})
 
 
+def test_severity_compares_by_rank_not_alphabetically():
+    """The str mixin made `ERROR > INFO` compare "error" to "info", which is False."""
+    low, mid, high = cf.Severity.INFO, cf.Severity.WARNING, cf.Severity.ERROR
+    assert low < mid < high
+    assert high > mid > low
+    assert low <= low and high >= high
+    assert sorted([high, low, mid]) == [low, mid, high]
+    assert max(high, low) is high and min(high, low) is low
+
+
 def test_round_accepts_both_documented_forms():
     for raw in ({"round": 2}, {"round": {"decimals": 2}}):
         recipe = Recipe.from_dict({"version": 1, "columns": {"a": {"ops": [raw]}}})

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/tests/test_wave1_hardening.py

@@ -6,6 +6,7 @@ or crashes the pipeline. They must fail before the Batch-A fixes and pass after.
 from __future__ import annotations
 
 import io
+from contextlib import suppress
 
 import pandas as pd
 import pytest
@@ -99,10 +100,8 @@ def test_multiindex_columns_do_not_raise_raw_error():
     """M4: MultiIndex columns must not leak a raw TypeError from .astype(str)."""
     df = pd.DataFrame([[1, 2], [3, 4]], columns=pd.MultiIndex.from_tuples([("a", "x"), ("a", "y")]))
     # Either succeeds (flattened labels) or raises a clean CleanFrameError — never a raw TypeError.
-    try:
+    with suppress(CleanFrameError):
         cf.clean(df)
-    except CleanFrameError:
-        pass
 
 
 def test_string_index_with_name_column_does_not_crash():

{cleanframe_engine-0.3.0 → cleanframe_engine-0.3.1}/tests/test_wave2_vectorization.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import pandas as pd
 
+from cleanframe import ops
 from cleanframe.executor import execute
 from cleanframe.ops import apply_column_op
 from cleanframe.recipe import Recipe
@@ -36,8 +37,6 @@ _TRICKY = [
 
 def _elementwise(op_name, series):
     """The reference: force the elementwise path by disabling the fast-path."""
-    import cleanframe.ops as ops
-
     orig = ops._is_pure_string
     ops._is_pure_string = lambda s: False
     try:

cleanframe_engine-0.3.0/cleanframe/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"