fix(transforms): warn once per deprecated AnchorSelector export and name the real importer

A from-import looks the name up twice, so each deprecated export warned twice. The resolved
object is now cached in the package globals on first access.

On Python 3.12+ the module's import-time warning skips importlib's frames
(skip_file_prefixes), so importlib.import_module() is attributed to its caller. Python 3.10
and 3.11 have no such option, so there the warning still names importlib.

The tests cover attribute, from-, plain and dynamic imports, and restore sys.modules and the
parent-package attribute through monkeypatch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assisted-by: claude-code:claude-opus-5-5
Headline-Session: 6e77a807-8dd4-4a77-a2fa-ddce6dc2515e
Headline-AI-Share: 2% strict / 7% weighted
This commit is contained in:
Tejas Chopra
2026-10-09 18:36:40 -07:00
co-authored by Claude Opus 5.5
parent 5aa13fa48a
commit 8f2f5e37ab
3 changed files with 63 additions and 11 deletions
+5 -1
View File
@@ -236,7 +236,11 @@ def __getattr__(name: str) -> object:
with warnings.catch_warnings():
warnings.simplefilter("ignore", DeprecationWarning)
module = import_module(module_name)
return getattr(module, attr_name)
value = getattr(module, attr_name)
# Cache it, so `from headroom.transforms import X` (which looks the
# name up twice) warns once, and later accesses stay quiet.
globals()[name] = value
return value
module = import_module(module_name)
value = getattr(module, attr_name)
+13 -1
View File
@@ -40,8 +40,11 @@ Example usage:
from __future__ import annotations
import hashlib
import importlib
import json
import logging
import os
import sys
import warnings
from collections import Counter
from dataclasses import dataclass
@@ -57,7 +60,16 @@ _DEPRECATION_MESSAGE = (
"future release; it has no replacement (SmartCrusher's anchor selection runs in Rust)."
)
warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
if sys.version_info >= (3, 12):
# Skip importlib's own frames too, so `importlib.import_module(...)` is
# attributed to its caller, like a plain `import` statement.
warnings.warn(
_DEPRECATION_MESSAGE,
DeprecationWarning,
skip_file_prefixes=(os.path.dirname(importlib.__file__) + os.sep,),
)
else: # pragma: no cover - Python 3.10/3.11 lack skip_file_prefixes
warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
class DataPattern(Enum):
+45 -9
View File
@@ -1,5 +1,9 @@
from __future__ import annotations
import importlib
import sys
import warnings
import pytest
import headroom.transforms as transforms
@@ -26,13 +30,27 @@ def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:
transforms.__getattr__("MissingExport")
def test_anchor_selector_exports_are_deprecated(monkeypatch: pytest.MonkeyPatch) -> None:
import sys
import warnings
_ANCHOR_EXPORTS = (
"AnchorSelector",
"AnchorStrategy",
"AnchorWeights",
"DataPattern",
"calculate_information_score",
"compute_item_hash",
)
@pytest.fixture
def fresh_anchor_selector(monkeypatch: pytest.MonkeyPatch) -> None:
"""Drop cached exports and the module; monkeypatch restores both afterwards."""
for name in _ANCHOR_EXPORTS:
monkeypatch.delitem(transforms.__dict__, name, raising=False)
monkeypatch.delitem(sys.modules, "headroom.transforms.anchor_selector", raising=False)
monkeypatch.delitem(transforms.__dict__, "AnchorSelector", raising=False)
monkeypatch.delattr(transforms, "anchor_selector", raising=False)
@pytest.mark.usefixtures("fresh_anchor_selector")
def test_anchor_selector_attribute_access_warns_once() -> None:
# A live export stays quiet.
with warnings.catch_warnings():
warnings.simplefilter("error", DeprecationWarning)
@@ -40,16 +58,34 @@ def test_anchor_selector_exports_are_deprecated(monkeypatch: pytest.MonkeyPatch)
with pytest.warns(DeprecationWarning, match="AnchorSelector is deprecated") as record:
selector_cls = transforms.AnchorSelector
assert transforms.AnchorSelector is selector_cls # cached: no second warning
assert selector_cls.__name__ == "AnchorSelector"
# One warning, attributed to this file rather than to importlib.
assert len(record) == 1
assert record[0].filename == __file__
def test_anchor_selector_module_import_is_deprecated(monkeypatch: pytest.MonkeyPatch) -> None:
import importlib
import sys
@pytest.mark.usefixtures("fresh_anchor_selector")
def test_anchor_selector_from_import_warns_once() -> None:
with warnings.catch_warnings(record=True) as record:
warnings.simplefilter("always")
from headroom.transforms import AnchorSelector # noqa: F401
deprecations = [w for w in record if issubclass(w.category, DeprecationWarning)]
assert len(deprecations) == 1
assert deprecations[0].filename == __file__
monkeypatch.delitem(sys.modules, "headroom.transforms.anchor_selector", raising=False)
with pytest.warns(DeprecationWarning, match="anchor_selector is deprecated"):
@pytest.mark.usefixtures("fresh_anchor_selector")
def test_anchor_selector_import_statement_is_deprecated() -> None:
with pytest.warns(DeprecationWarning, match="anchor_selector is deprecated") as record:
import headroom.transforms.anchor_selector # noqa: F401
assert record[0].filename == __file__
@pytest.mark.usefixtures("fresh_anchor_selector")
def test_anchor_selector_dynamic_import_is_deprecated() -> None:
with pytest.warns(DeprecationWarning, match="anchor_selector is deprecated") as record:
importlib.import_module("headroom.transforms.anchor_selector")
if sys.version_info >= (3, 12):
# Older Pythons cannot skip importlib's frame, so the warning names importlib.
assert record[0].filename == __file__