Files
headroom/tests/test_transforms_package.py
Tejas Chopra 9b1971dd82 refactor(transforms): deprecate the unused Python AnchorSelector port (#4104)
## Description

`headroom/transforms/anchor_selector.py` is the Python original of the
anchor selector that SmartCrusher now runs in Rust
(`crates/headroom-core/src/transforms/anchor_selector.rs`). Nothing in
Headroom calls it, it has no tests or docs, and no consumer repo imports
it. It is still exported from `headroom.transforms`, so this PR
deprecates it instead of deleting it. There is no replacement.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Accessing `AnchorSelector`, `AnchorStrategy`, `AnchorWeights`,
`DataPattern`, `calculate_information_score` or `compute_item_hash`
through `headroom.transforms` emits one `DeprecationWarning`, attributed
to the caller.
- The resolved object is cached in the package globals, so a `from`
import (which looks the name up twice) warns once.
- Importing `headroom.transforms.anchor_selector` directly warns at
import.
- On Python 3.12+ the 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.
- `import headroom.transforms` and every other export stay quiet.
- The tests cover attribute, `from`, plain and dynamic imports. They
restore `sys.modules`, the parent-package attribute and the export cache
through monkeypatch.
- Evidence: `rg -n
'AnchorSelector|anchor_selector|compute_item_hash|calculate_information_score'
headroom plugins sdk examples benchmarks scripts docs tests`, plus the
consumer repos, finds only the module itself, its lazy exports, the Rust
port and an unpublished wiki design plan.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest tests/test_transforms_package.py tests/test_package_init_lazy.py tests/test_smart_crusher*.py tests/test_transforms/test_smart_crusher*.py
110 passed in 6.09s
$ pytest tests/test_transforms_package.py   # with the previous commit's product code
3 failed, 2 passed (double warning on from-import; importlib-attributed dynamic import)
$ python3.10 -c "compile(anchor_selector.py)"   # 3.10 fallback branch parses
3.10.21 compiles
$ ruff check / format: All checks passed;  mypy: Success
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo `.venv`, this branch's worktree
with the prebuilt `headroom._core`. Temp `HOME`,
`HEADROOM_WORKSPACE_DIR` and `CODEX_HOME`; nothing touched the real
home.
- Exact command / steps: (1) shared smoke harness: a real proxy from
this checkout against a local fake upstream, with one Anthropic and one
OpenAI request carrying a compressible tool result (`smoke.sh
<worktree>`); (2) `python -W always -c 'from headroom.transforms import
AnchorSelector'`, plus a script that calls
`importlib.import_module('headroom.transforms.anchor_selector')`.
- Observed result: The proxy serves both requests (200) with savings.
The from-import warns once at `<string>:2`, and the dynamic import is
attributed to `plugin_loader.py:2`, not to importlib. Output below.
- Not tested: The full test suite on Python 3.10/3.11 (only the fallback
branch was compile-checked there).

```text
branch: cleanup/transforms-deprecate-anchor-selector @ 8f2f5e37
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE/ws/logs/proxy-50549.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE)
```

```text
$ python -W always -c "from headroom.transforms import AnchorSelector"
<string>:2: DeprecationWarning: headroom.transforms.AnchorSelector is deprecated and will be removed in a future release; it has no replacement (SmartCrusher's anchor selection runs in Rust).
ok
$ python -W always plugin_loader.py   # importlib.import_module("headroom.transforms.anchor_selector")
plugin_loader.py:2: DeprecationWarning: headroom.transforms.anchor_selector is deprecated and will be removed in a future release; it has no replacement (SmartCrusher's anchor selection runs in Rust).
  importlib.import_module("headroom.transforms.anchor_selector")
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Not applicable; no rollout-managed behaviour
is touched.
- Stable/default behavior changed: Only a DeprecationWarning when the
deprecated names are used. Return values do not change.
- Kill switch / disable path: Not applicable; the warning is a standard
DeprecationWarning and can be filtered with `warnings`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this single commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

Not applicable.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

Documentation changes are not in this PR. They are recorded in the
cleanup docs ledger for the single follow-up docs PR.

Deprecated (not removed): `AnchorSelector`, `AnchorStrategy`,
`AnchorWeights`, `DataPattern`, `calculate_information_score`,
`compute_item_hash`, and the module
`headroom.transforms.anchor_selector`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-10-10 09:03:24 -07:00

92 lines
3.4 KiB
Python

from __future__ import annotations
import importlib
import sys
import warnings
import pytest
import headroom.transforms as transforms
def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(transforms, "_HTML_EXTRACTOR_AVAILABLE", True)
monkeypatch.setattr(
transforms,
"_LAZY_EXPORTS",
{"FakeExport": ("fake.module", "VALUE")},
)
monkeypatch.setattr(transforms, "import_module", lambda name: type("M", (), {"VALUE": 123})())
assert transforms.__getattr__("_HTML_EXTRACTOR_AVAILABLE") is True
assert transforms.__getattr__("FakeExport") == 123
assert transforms.FakeExport == 123
assert "FakeExport" in transforms.__dir__()
with pytest.raises(AttributeError, match="__path__"):
transforms.__getattr__("__path__")
with pytest.raises(AttributeError, match="MissingExport"):
transforms.__getattr__("MissingExport")
_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.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)
assert transforms.ContentRouter is not None
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__
@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__
@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__