mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 12:05:34 +08:00
## 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)
92 lines
3.4 KiB
Python
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__
|