lazy-import-refactor
Refactor module-level imports of heavy native dependencies (torch, tensorflow, jax) to function-internal lazy imports. Use when a library import triggers SIGSEGV or slow startup in environments where the native dep cannot fully initialize (e.g., CUDA driver absent, triton C-extension segfault, missing GPU). Predicts test-side effects from removed module attributes.
How do I install this agent skill?
npx skills add https://github.com/nextaltair/altairs-agent-dev-kit --skill lazy-import-refactorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides technical guidelines and code patterns for refactoring module-level imports into function-internal lazy imports to optimize startup performance and avoid native dependency crashes. No security issues or malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Lazy Import Refactor
Module-level import torch / import tensorflow 等 heavy native dependency を function-internal lazy import に移行するための手順 + test 副作用予測 + CI-equivalent 検証要件。
When to Use
import <library>単体で SIGSEGV (CUDA driver 不在 + triton C-ext segfault 等)- 起動時間短縮のため重い import を遅延させたい
- WebAPI 専用利用者に heavy native dep を不要にしたい
- 上流 lib の lazy import 化を下流プロジェクトから依頼する設計検討
該当した実例: Linux + triton + CUDA driver 不在で import <ML ライブラリ> が SIGSEGV → torch / transformers の module-level import 排除で恒久解消したケースがある
Step 1: Pre-flight grep — 影響範囲完全洗い出し
Module-level import 全件 (col 0 のみ):
find src -name "*.py" | while read f; do
awk -v fn="$f" '/^(import torch|from torch|import torchvision|from torchvision|import tensorflow|from tensorflow)/{print fn":"NR":"$0}' "$f"
done
テスト側の module attribute patch 全件:
find tests -name "*.py" | while read f; do
awk -v fn="$f" '/@patch.*\.(torch|tensorflow|jax)|patch\.object.*\.(torch|tensorflow|jax)/{print fn":"NR":"$0}' "$f"
done
Module-level import を関数内に移すと、その module の module.torch 属性が消滅する。test 側で @patch("path.to.module.torch") を使用している箇所は全件 AttributeError で壊れる ため、事前 grep が必須。
Step 2: Refactor パターン
# Before (module-level)
import torch
class Foo:
def bar(self, x: torch.Tensor) -> torch.Tensor:
with torch.no_grad():
...
# After (TYPE_CHECKING + function-internal)
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
import torch
class Foo:
def bar(self, x: torch.Tensor) -> torch.Tensor:
import torch # lazy load
with torch.no_grad():
...
必須事項:
from __future__ import annotationsを冒頭に追加 (型ヒントを文字列化、runtime evaluation 回避)- runtime で使う関数の冒頭で
import torchを再宣言 - module-level の bare
import torchは削除
Step 3: Test 副作用対応
# Before
@patch("your_package.core.heavy_deps.torch")
def test_foo(mock_torch):
...
# After
def test_foo(monkeypatch):
import sys
from unittest.mock import MagicMock
mock_torch = MagicMock()
monkeypatch.setitem(sys.modules, "torch", mock_torch)
...
詳細パターン (context manager mock, cuda.is_available, getattr-based access 等) は test-side-effects.md 参照。
Step 4: Verification — CI-equivalent filter で必ず検証
プロジェクトの testing ルール(例: rules/testing.md の "CI-equivalent filter で local 検証する" セクション)を参照。
-m unit 等の短縮 filter では検証不充分 (本 SKILL の存在理由 — サブモジュール側の marker 差分が短縮 filter では再現できず下流 CI で初検出された実例がある)。CI workflow の filter を完全一致で local 実行する。
モノレポ内の独立パッケージ (submodule 等) の場合:
cd <package-path>
uv run pytest -m "not downloads_and_runs_model and not calls_real_webapi"
Step 5: Cross-repo PR 順序
submodule で利用される lib の場合:
- lib 側で fix + CI-equivalent test pass を確認
- lib 側 PR 起票 → merge 待ち
- merge 後、下流プロジェクトで submodule pin 更新 PR 起票
順序を逆にすると下流 CI で初検出され、hot-fix PR 連鎖が必要になる。
gh pr create 実行時、kit の submodule pre-PR check hook (hook_pre_pr_submodule_check.py) が導入されていれば、submodule 変更を含む PR で CI-equivalent test 実行確認を要求する (bypass は CI-EQUIV-TESTED marker comment)。
Anti-patterns
- module-level の上位 lib import:
from transformers.models.clip import CLIPProcessorは transformers が torch を eager load するため lazy 化が必要。直接import torchでなくても heavy native dep を引き連れる import は全て対象 - TYPE_CHECKING 内のみで対応:
cast(<heavy_lib>.Type, ...)やisinstance(x, <heavy_lib>.Type)のような runtime 評価が必要な箇所では完全には escape できない →from __future__ import annotationsで型ヒントの string 化と、関数内importの両方を必須とする - subprocess regression test の欠落: lazy import 化が効いているか検証する test を同 PR で追加する。fresh interpreter での
import <lib>; assert 'torch' not in sys.modulesパターンを推奨 (subprocess 経由で session 汚染を回避) -m unitでの local 検証: CI が独立 marker (standard等) を使う場合、必ず CI 設定の filter で検証する
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/nextaltair/altairs-agent-dev-kit/lazy-import-refactor">View lazy-import-refactor on skillZs</a>