Lazy Import Refactor

import torch

import tensorflow

When to Use

• import <library>

  単体で SIGSEGV (CUDA driver 不在 + triton C-ext segfault 等)
• 起動時間短縮のため重い import を遅延させたい
• WebAPI 専用利用者に heavy native dep を不要にしたい
• 上流 lib の lazy import 化を下流プロジェクトから依頼する設計検討

import <ML ライブラリ>

Step 1: Pre-flight grep — 影響範囲完全洗い出し

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

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.torch

@patch("path.to.module.torch")

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)
    ...

Step 4: Verification — CI-equivalent filter で必ず検証

rules/testing.md

-m unit

cd <package-path>
uv run pytest -m "not downloads_and_runs_model and not calls_real_webapi"

Step 5: Cross-repo PR 順序

1. lib 側で fix + CI-equivalent test pass を確認
2. lib 側 PR 起票 → merge 待ち
3. merge 後、下流プロジェクトで submodule pin 更新 PR 起票

gh pr create

hook_pre_pr_submodule_check.py

CI-EQUIV-TESTED

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 で検証する