feat(infra): diagnostics utils, better terminal warnings#124
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces a centralized warning infrastructure to classify warning origins (raitap subsystem + known third-party libraries), render warning panels differently for dev vs installed users (paths vs docs links), and suppress a noisy Captum UserWarning at runtime.
Changes:
- Added
raitap.utils.warningsfor origin resolution, docs-link mapping, dev-install detection, and asuppress_warning()helper. - Updated Rich warning panel rendering to use resolved origins and audience-aware headers (dev: path/line; installed: docs link; third-party: “via ”).
- Suppressed Captum’s repetitive “required_grads” warning at import time and aligned pytest warning filters accordingly; added unit tests for the new warnings utilities.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/raitap/utils/warnings.py |
New warning infrastructure (origin classification, suppression helper, dev-install heuristic, docs URL mapping, origin stash queue). |
src/raitap/utils/tests/test_warnings.py |
New unit tests covering origin resolution, suppression, dev-install detection, and docs URL generation. |
src/raitap/utils/console.py |
Moves frame-walk logic out of console; warning panel header now uses resolved origin + dev/install branching. |
src/raitap/utils/__init__.py |
Exposes WarningOrigin and suppress_warning from the utils package. |
src/raitap/transparency/explainers/captum_explainer.py |
Silences Captum’s noisy UserWarning at import time via suppress_warning(). |
pyproject.toml |
Documents/keeps pytest filterwarnings entry to match runtime suppression behavior. |
…path false matches
…packages, py.warnings gate
…ith future error pipeline
…ed warning rendering
stanlrt
changed the title
stanlrt
changed the title
stanlrt
changed the title
6 tasks
pizzajojo
requested changes
May 9, 2026
Comment on lines
+109
to
+113
| ) | ||
| formatted = message % args if args else message | ||
| try: | ||
| warnings.warn(formatted, category, stacklevel=stacklevel + 1) | ||
| finally: |
Comment on lines
+116
to
+123
| def info(self, message: object, *args: object, stacklevel: int = 2, **kwargs: Any) -> None: | ||
| """Log at INFO level on the caller's module logger.""" | ||
| _caller_logger(stacklevel).info(message, *args, stacklevel=stacklevel + 1, **kwargs) | ||
|
|
||
| def debug(self, message: object, *args: object, stacklevel: int = 2, **kwargs: Any) -> None: | ||
| """Log at DEBUG level on the caller's module logger.""" | ||
| _caller_logger(stacklevel).debug(message, *args, stacklevel=stacklevel + 1, **kwargs) | ||
|
|
Comment on lines
+408
to
+414
| hw_symbol = "⚠︎ " if is_cpu else "✓ " | ||
| if is_cpu: | ||
| docs_url = "https://caiivs.github.io/raitap/using-raitap/installation.html#execution-dependencies" | ||
| hw_text = Text.from_markup( | ||
| f"[{hw_color}]{hw_symbol}{hw_label}[/] " | ||
| f"[{hw_color} underline link={docs_url}]Use GPU[/]" | ||
| ) |
Comment on lines
+1
to
+6
| """Unified raitap logger: ``raitap_log.warn`` / ``.info`` / ``.debug`` / ``.error`` / ``.suppress``. | ||
|
|
||
| A single import surface so call sites never have to choose between | ||
| :func:`warnings.warn`, :func:`logging.info`, ``logging.getLogger(__name__)``, and | ||
| ``raise``. The methods underneath dispatch to the right primitive: | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
src/raitap/utils/warnings.pymodule:WarningOrigindataclass,resolve_warn_origin(frame walk for raitap subsystem + third-party lib detection),suppress_warningadapter helper,is_dev_installheuristic,docs_urlmapper.RaitapRichHandler._emit_panelnow branches onis_dev_install()and the resolved origin: dev shows<Subsystem> · path:line, installed shows<Subsystem>linked to docs, third-party addsvia <lib>. Frame-walk logic moved out ofconsole.py.suppress_warning(...)at import to silence theInput Tensor … required_gradsUserWarning that captum auto-fixes anyway.Closes #123 (infra portion). Out of scope per plan: full error-message rewrap (issue #22) — this only ships the infrastructure that #22 will build on, plus one captum smoke-test.
Test plan
uv run pytest— 573 passed, 22 skipped (pre-existing failures gated on missing optional deps unaffected).resolve_warn_origin,is_dev_install(mocked__file__),docs_url,suppress_warning.uv run ruff check .+uv run ruff format --check .clean.uv run pyrighton changed files: 0 errors.uv run raitapsmoke test: dev mode renders▲ Warning · Metrics · <full path>; captum warning no longer appears.▲ Warning · Metricslinked to docs (manual verification when wheel published).🤖 Generated with Claude Code