Python 3.15の遅延インポートの導入:CLIの速度を4倍にし、効果がなかった箇所
Adopting Python 3.15's lazy imports: a 4× faster CLI, and where they didn't help (namegarage.com)
要約
この記事では、Python 3.15で導入された遅延インポート機能(PEP 810)をnamegarage社がどのように採用し、コマンドラインインターフェース(CLI)の起動時間を4倍高速化したかについて解説しています。安全性を確保するためにMetaのLifeguard静的アナライザーを用いたゲートを導入し、遅延インポートが効果を発揮しなかったケースや、テスト環境での挙動についても詳細に説明しています。
全文翻訳
Python 3.15の遅延インポートの導入:CLIの速度を4倍にし、効果がなかった箇所
11月3日、私たちはバックオフィスシステムをPython 3.15.2に移行しました。このシステムは、コマンドラインツール、TextualベースのターミナルUI、そしてAIエージェントに同じ操作を提供するMCPサーバーという3つのフロントエンドを持つ単一のPythonパッケージです。これらを統合して、レジストラからドメインインベントリを取得し、価格設定を行い、このウェブサイトを構築しています。
当初、これら3つのフロントエンドはすべて起動が遅いという問題を抱えていました。CLIの--helpコマンドは、CLIのメインモジュールがモジュールスコープでサイトジェネレーター、レジストラクライアント、データベースレイヤーのほぼすべてをインポートしていたため、開発中のMacで約1.3秒かかっていました。Python 3.15では明示的な遅延インポート(PEP 810)が追加されたため、これを利用することにしました。また、新しい組み込み型であるfrozendict(PEP 814)を採用し、新しいサンプリングプロファイラー(PEP 799)についても文書化しました。
この作業は6つのプルリクエストに及びました。この記事では、測定結果、遅延させる前に構築した安全確認ゲート、遅延インポートが遅延しないケース、そしてCLIほど改善されなかった2つのエントリーポイントを含む結果について説明します。
起動時間の内訳
python -X importtimeコマンドは、トリガーされたインポートを含め、各インポートにかかる時間を表示します。CLIでは、--helpコマンドでは決して実行されない処理のために、高コストなインポートチェーンが発生していました。
変更前の--helpコマンドでロードされていた最大のインポートチェーン
--helpによってロードされたパッケージ | 累積ミリ秒 | 最初に到達した経路 |
|---|---|---|
| markdown-it | 694 | CLI → サイトジェネレーター → エージェントドキュメンテーション |
| httpx2 | 331 | CLI → DNSチェッカー |
| asyncio | 321 | CLI → 設定 → 認証情報 |
| DuckDB | 241 | CLI → クーポン → ドメインモデル → タイプ |
| rcssmin | 192 | CLI → サイトジェネレーター |
| Jinja2 | 191 | CLI → サイトジェネレーター |
| PyYAML | 146 | CLI → クーポン → ドメインモデル → セールポリシー |
これらの数値は、ロードアベレージ約50の環境での1回の実行結果です。累積値であるため、ネストされたパッケージは重複しています。
遅延によってどれだけ節約できるかの限界を把握するため、各エントリーポイントをPYTHON_LAZY_IMPORTS=allを設定して実行しました。これにより、すべてのインポートが遅延されます。その結果はバイト単位で同一でした。CLIの--helpは2,230ミリ秒から474ミリ秒に、TUIは3,615ミリ秒から209ミリ秒に、MCPサーバーのインポートは5,667ミリ秒から1,682ミリ秒に短縮されました。この実行はロードアベレージ140〜240の環境で行われたため、意味があるのは比率のみです。
グローバル遅延モードを有効にしなかった理由
グローバルモードは1つのスイッチで有効にできますが、本番環境では使用しませんでした。後述のアナライザーであるLifeguardは、遅延によって変更されうるインポート時の影響を、パッケージとその依存関係にある801ファイルのうち160ファイルで見つけました。そのうちの1つは、インポート時に.envファイルからos.environを埋める私たち自身の設定モジュールです。環境変数を後で読み取るすべてのものは、そのインポートが先に実行されることに依存しています。
明示的なステートメントは記述された場所にのみ適用され、レビュー担当者もそれを確認できます。
from app import config # インポート時にos.environを埋めるため、これは積極的なままです
lazy from app import website
lazy from app.clients import build_registrar
lazy import app.valuation
例のモジュール名は簡略化されています。
遅延可能なインポートを決定するゲート
遅延インポートは、ターゲットモジュールのインポート時の作業を起動時から初回使用時まで移動させます。これは、その作業がその間に変更されるものに依存しない場合にのみ安全です。私たちはすべてのステートメントを目で判断したくなかったので、最初のプルリクエストでゲートを追加し、遅延ステートメントは含めませんでした。
このゲートは、Lifeguard(Meta製の遅延インポートの安全性を確認する静的アナライザー)のバージョン0.7.0を使用して実行されます。Lifeguardは、インポート時の効果を持つモジュール、積極的なインポートが必要なモジュール、およびインポートサイクルを形成するモジュールを報告します。ゲートは次に、astを使用してすべてのlazyステートメントを見つけ、5つのルールをチェックします。
- インポート元のモジュールは、
sys.modulesに書き込むモジュールなど、Lifeguardが積極的なロードを必要とすると判断したモジュールであってはなりません。 - ターゲットは、許可リストのエントリがその正確なペアを保証しない限り、遅延によって変更されうるインポート時の効果を持っていてはなりません。
- ターゲットは、インポート元のモジュール自身の積極的な依存関係であってはなりません。つまり、安全でないモジュール、属性のみで到達するサブモジュール、またはインポートサイクルに入るメンバーです。
- 効果を持つインポート元モジュールは、自身のインポートサイクル内のモジュールを遅延させてはなりません。
- 設定モジュールは決して遅延されません。許可リストのエントリはこのルールを上書きできません。
ゲートは失敗時に閉じます。スキャンするファイルがない場合、Lifeguardがエラーで終了した場合、Lifeguardのレポートが私たちのモジュール名を1つも指定しない場合、または許可リストのエントリが遅延ステートメントに一致しない場合に失敗します。コミットフックは、Pythonファイル、許可リスト、またはロックファイルが変更されるたびにこれを実行します。なぜなら、あらゆる編集がモジュールに新しいインポート時の効果を与える可能性があるからです。私たちのパッケージとその依存関係に対する1回のLifeguard実行は8.4秒かかりました。
ルール1は、まずコードの変更が必要でした。CLIのメインモジュールはパスでデプロイメントスクリプトをロードし、sys.modulesに登録していたため、Lifeguardはモジュール全体を積極的なロードにするよう要求しました。そのローダーを小さなヘルパーモジュールに移動することで、CLIが対象となりました。
許可リストは各ターゲットの効果を記録する
私たちのチェーンで最も重いモジュールは安全ではありませんでした。なぜなら、それぞれがインポート時にパッケージ化されたテンプレートや単語リストを読み込むからです。それを遅延させるには、理由とターゲットの現在の効果を記載した許可リストのエントリが必要です。
[[allow]]
importer = "app.cli.main"
target = "app.direct_sale"
reason = "インポート時に、パッケージ化された契約テンプレートのimportlib.resourcesパスを構築するだけで、作業ディレクトリ、環境、sys.pathに依存しません。テンプレートは後で関数内で読み取られます。"
effects = ["UnsafeMethodCall importlib.resources.abc.Traversable.joinpath"]
理由はその効果が後で実行できる理由を説明する必要があります。特に、起動後にコマンドが変更する状態(作業ディレクトリ、環境変数、sys.pathなど)に依存してはなりません。遅延されたモジュールのインポートエラーも起動時から初回使用時に移動し、理由はそのことを受け入れる必要があります。
effectsは、行番号なしでLifeguardの検出結果をリストします。リストが変更されると、ゲートは失敗し、新しいリストを表示します。そのチェックは実際の変更を捉えました。CLIの変更がレビュー中であった間にマージされた別のプルリクエストは、サイトジェネレーターがインポート時に別のモジュールのテーブルからセットを構築するようにしました。リベース時に、Lifeguardはサイトジェネレーターに対して2つの新しい効果を報告し、ゲートはその古いエントリを拒否しました。理由がまだ有効であることを確認し、新しい効果を記録しました。
Lifeguardはすべてを把握しているわけではありません。printを呼び出しただけのプローブモジュールが対象として報告されました。ゲートはアナライザーのモデルを強制し、レビュー担当者は依然として新しい遅延ステートメントをすべて読みます。現在、ゲートは4つのファイルで59の遅延ステートメントをチェックしており、8つの許可リストエントリがあります。
テストは遅延ステートメントを積極的に実行する
遅延されたfrom m import fは、インポート元のモジュールがその名前を最初に使うときにfをバインドし、モジュールロード時ではありません。テストがその最初の使用前にm.fをパッチした場合、パッチが終了した後もインポーターはモックを保持します。
# user.py
lazy from src import f
def call():
return f()
from unittest import mock
import user # src はまだインポートされていません
with mock.patch("src.f", lambda: "mock"):
print(user.call()) # mock: 最初の使用でfがパッチにバインドされます
print(user.call()) # パッチが解除された後もmockのままです
これがPython 3.15.2で私たちが出力したものです。遅延されたimport mは問題を防ぎます。なぜなら、各呼び出しはm.fをルックアップするからです。しかし、それに切り替えるとすべての呼び出しサイトの名前を変更することになり、私たちのCLIテストはCLIパッケージ自体に名前をパッチしており、これは意図的に維持している契約です。
そのため、テストプロセスは私たち自身の遅延ステートメントを積極的なものにします。3.15.2では、PYTHON_LAZY_IMPORTSと-X lazy_importsはallとnormalのみを受け入れ、どちらも明示的なlazyステートメントを積極的なものにはしません。sys.set_lazy_imports_filterがこれを実行できます。インポートをすぐにロードするフィルタを返します。
# conftest.py, パッケージがインポートされる前
import sys
def eager_in_package(importer: str, name: str, fromlist: object = None) -> bool:
return not (importer == "app" or importer.startswith("app."))
sys.set_lazy_imports_filter(eager_in_package)
インプロセスでのテストは古いインポートタイミングとパッチ動作を確認します。遅延パスは独自のチェックを受けます。サブプロセスでのテストはフィルタなしで実際のエントリーポイントを開始し、--helpがロードしてはならないパッケージをアサートし、ゲートは静的にすべてのステートメントをチェックします。
フィルタなしで実行したスイート全体も1回実行しました。どちらの実行でも14,342のテストがパスしました。どちらの実行でも失敗したテストは、ベースコミットでも失敗したか、単独で再実行するとパスしたか、またはフィルタ自体のセルフテストであり、フィルタなしでは失敗する必要があります。パッチキャプチャによるテスト失敗はありませんでした。
遅延インポートが遅延しないケース
遅延バインディングは、名前が最初にルックアップされたときに解決されます。一部のルックアップはモジュール自体がロード中に発生し、これは遅延を静かに無効にします。
- モジュールレベルのテーブル。 CLIは、レジストラ名と評価ソース名をファクトリ関数にマッピングする辞書を保持していました。辞書を構築するには、すべてのファクトリをルックアップする必要があり、これにより起動時にクライアントパッケージがインポートされていました。
- デフォルト引数値。 3つのMCPツールは、クライアントパッケージからデフォルト値を受け取ります。Pythonは関数が作成されるときにデフォルト値を評価するため、これらのツールを登録するとクライアントパッケージがインポートされ、それに伴ってDuckDB、httpx2、PyYAMLもインポートされます。
- 基底クラス。 TUIのアプリケーションクラスはTextualの
Appをサブクラス化するため、クラス本体が実行される前にTextualをロードする必要があります。 tryブロック。tryブロック内のlazyは構文エラー(「try/exceptブロック内では遅延インポートは許可されていません」)であり、関数内でも同様です。TextualとFastMCPの両方がtryブロック内でインポートされていました。
テーブルは簡単なケースでした。各値は現在、コマンドがそのクライアントを構築するときにのみファクトリをルックアップします。
lazy from app.clients import build_escrow, build_mailer
# このモジュールがロードされるときに、両方の名前をルックアップし、app.clientsをインポートします:
CLIENT_BUILDERS = {"escrow": build_escrow, "mailer": build_mailer}
# 各名前は、コマンドがそのクライアントを構築するときにのみルックアップされます:
CLIENT_BUILDERS = {"escrow": lambda: build_escrow(), "mailer": lambda: build_mailer()}
TUIの作業は、もう1つのルールを追加しました。それは、すでにロードされるものではないものを遅延させることです。TUIの定数モジュールは、インポート時にレジストラリストからカラーテーブルを構築し、クライアントパッケージ、データベースレイヤー、DuckDBをロードします。TUIのメインモジュールでこれらのモジュールを遅延させても、バインディングが移動し、許可リストのエントリが増えるだけで、それらは積極的なままです。
結果
各数値は9回の実行の中央値です。セッション中に古いコードと新しいコードを交互に10回実行し、最初の実行は破棄しました。マシンは他の作業も実行しているApple Silicon開発Macだったため、各行は実行中のロードアベレージを示しています。--helpの出力は、変更前と変更後でバイト単位で同一でした。
明示的な遅延インポートの前後の起動時間
| プロセス | ロードされたモジュール | 中央値時間 | ロードアベレージ |
|---|---|---|---|
CLI --help | 664 → 308 | 1,314 ms → 326 ms | 70–85 |
TUI --help | 797 → 620 | 1,768 ms → 1,406 ms | 21–30 |
| MCPサーバーのインポート | 1,224 → 1,055 | 3,341 ms → 2,827 ms | 47–80 |
CLIの--helpは4倍高速になりました。DuckDB、Jinja2、markdown-it、PyYAML、httpx2、rcssminをロードしなくなり、サブプロセスでのテストがそのリストを固定しているため、それらを再度ロードするインポートはスイートを失敗させます。
TUIは20%、MCPサーバーは15%改善しました。MCPサーバーは、どちらの方法でも同じ94のツールを登録しました。残りの大部分はTextualまたはFastMCP自体であり、上記で説明したクライアントチェーンです。これを削除するには、エントリーポイントとクライアントパッケージの再構築が必要であり、さらにlazyキーワードを追加するだけでは解決しません。
私たちは2つの小さなコストを残しました。asyncioは依然として--helpでロードされます。なぜなら、設定モジュールが認証情報モジュールをインポートし、それがasyncioをインポートするためです。これを変更するには、認証情報モジュールがインポートサイクルを回避する方法を変更する必要があります。rich.progressは約71ミリ秒かかりますが、サードパーティモジュールに対する許可リストのエントリは、そのライブラリのインポート時の効果が変更されるたびにゲートを失敗させます。
遅延ステートメントをオフにする実行時スイッチを追加しませんでした。ロールバックはリバートです。
frozendict
Python 3.15では、組み込みの不変マッピングであるfrozendictも追加されました。ハッシュ可能であり、Mappingであり、json、pickle、copyと連携します。dictのサブクラスではありません。
私たちは3つのMappingProxyType定数をfrozendictに置き換え、新しい定数マッピングのルールとしました。
from collections.abc import Mapping
STATUS_LABELS: Mapping[str, str] = frozendict({ # pyrefly: ignore[bad-argument-count]
"active": "For sale",
"sold": "Sold",
})
既存の121個のモジュールレベルのdict定数は変換しませんでした。コードには約530回のisinstance(x, dict)チェックがあり、frozendictはそれらすべてで失敗します。
2つのツールで注意が必要でした。Python 3.15ターゲットの下では、pyrefly 1.4.0および1.4.1はfrozendict.__init__をパラメータなしで型付けしているため、引数付きのすべてのコンストラクタ呼び出しはエラーになります。1.5.0.dev1プレリリースはそれらを受け入れます。私たちは安定版リリースにとどまり、上記のターゲット指定された無視を追加し、アップグレード後にpyrefly suppress --remove-unused-ignoresでそれらの無視を削除します。Ruffとtyはコードをそのまま受け入れました。
私たちの変更ベースのテスト選択は、モジュールレベルの値のフィンガープリントを作成して、テストが共有する状態を検出します。frozendictを不明として読み取ったため、組み込み型のitemsを介してメンバーを読み取るように教えました。コードレビューでは、frozendictのサブクラスはミュータブルな属性を持つことができるため、正確な型のみがそのパスを取ると指摘されました。
サンプリングプロファイラー
Python 3.15には、python -m profiling.samplingとしてサンプリングプロファイラーが同梱されています。コードをインストルメントすることなく、間隔を置いてプロセスのスタックを読み取ります。実行中のプロセスにattachしたり、現在のスタックをdumpしたり、保存されたキャプチャを別の形式にreplayしたり、プログラムを最初の行からrunしたりできます。
macOSでは、他のプロセスのメモリを読み取るには昇格された権限が必要です。それがない場合、プロファイラーは「macOSでプロセスメモリにアクセスできません」というエラーで停止します。私たちのハウツーの最初のドラフトは、sudoでCLIをrunで実行しました。レビューで、runはターゲットを権限を降格せずに開始するため、データベース、出力ファイル、__pycache__がroot所有になることが指摘されました。文書化されたパターンは、プログラムをあなた自身として開始し、プロファイラーにのみsudoを付与します。
uv run my-tui
# 別のターミナルで:
sudo -E .venv/bin/python -m profiling.sampling attach --flamegraph -o profile.html "$(pgrep -n -f my-tui)"
sudo chown "$USER" profile.html
システム整合性保護はシステムPythonをブロックする可能性があるため、プロジェクトのインタープリターを使用してください。私たちはまだこのコードでプロファイラーを使用していません。起動に関しては、-X importtimeが質問に直接答えます。つまり、何がロードされ、どのチェーンを経由するのかということです。
除外したもの
3.15のいくつかの追加機能は変更の対象となりませんでした。
- センチネル値(PEP 661)と内包表記でのアンパッキング(PEP 798): 2つのセンチネルと38個のフラット化内包表記を書き直しても、リーダーやユーザーが気づくような変化はありませんでした。
- 閉じられた
TypedDict(PEP 728): 15個のクラスが次に変更されるときに適用するのが最善の型変更です。 - TOML 1.1: 他のツールは同じファイルを読み取りますが、これをサポートしていません。
- base64の新しいパディングオプション: 既にバイヤーの受信トレイにあるチェックアウトリンクは、以前とまったく同じようにデコードを続ける必要があります。
あなた自身のコードで試す
測定から始めてください。この出力を累積列でソートし、最大の項目 behind のチェーンを読み取ります。
python -X importtime -m yourapp --help 2> importtime.txt
次に、Lifeguardにどのモジュールが遅延可能か尋ねてください。そのJSONレポートは、遅延可能なモジュール(LAZY_ELIGIBLE)と積極的なロードが必要なモジュール(LOAD_IMPORTS_EAGERLY)をリストします。
uvx --from lifeguard-lazy-imports==0.7.0 lifeguard run-tree src/yourapp report.json --python-version 3.15
依存関係を追跡できるように--site-packagesを渡してください。Lifeguardはシンボリックリンクされたパッケージを追跡しなかったため、ゲートはまずパッケージのソースを一時的なツリーにコピーします。
最初のlazy fromを追加する前に、遅延させる予定の名前のパッチをテストで検索してください。上記のようなフィルタは、それらのテストを正直に保ち、サブプロセスでのテストは遅延パスを正直に保ちます。