HMR Docs

Python 向け HMR

HMR は、Python らしく柔軟で、段階的に使い始められる直感的なリアクティブプログラミングの エンジン／フレームワーク を提供し、その上に、きめ細かく必要に応じて動作するホットリロード ツール を備えています。

Python では、HMR は Hot Module Reload の略ですが、JavaScript では一般に Hot Module Replacement を指します。基本的には同じ概念です。これは、プロセス全体を再起動することなく、アプリ全体を再実行せずに、実行時にアプリの一部を更新できる機能です。

watchfiles CLI、uvicorn --reload、Flask のデバッグモードといった従来の Python リローダーとは異なり、HMR ははるかに効率的で堅牢です。これらのツールは通常、ファイルが変更されるたびにプロセス全体を再起動するため、無駄が生じます。一方、HMR は必要な部分だけを賢く再実行し、アプリの状態を維持します。

https://github.com/user-attachments/assets/f9ac6302-44dc-4a6d-86ae-f299fae7be80

FastAPI を使い、初期化に 5 秒かかるモデルを備えた ML サービスを開発しているとします。uvicorn --reload を使うと、簡単な docstring の更新でさえ変更のたびにプロセス全体の再起動を引き起こし、そのたびに 5 秒待つことになります。これは、交差点のたびに赤信号に遭遇するほどいらだたしいものです。

HMR なら、よりスムーズに開発できます。HMR は 変数レベルできめ細かく動作するため、変更は即座に反映されます。コードベースは依存関係グラフのように機能し、ファイルを変更すると、HMR は変更されたモジュールからエントリーポイントのファイルまで、影響を受けるモジュールだけを再実行します。何も依存していない変数を更新した場合、何も起こりません。

注意

このパッケージが提供しないもの

hmr は、サーバーコードの変更時にブラウザーのコンテンツを更新するクライアントサイドのホットリロードと混同しないでください。このパッケージが実装するのはサーバーサイド HMR であり、変更時に Python コードのみを再読み込みします。

使い方

HMR を手早く試すには、CLI を使います。

pip install hmr
hmr path/to/your/entry-file.py

パラメーターは python コマンドとまったく同じですが、ファイルの変更時にホットリロードされるようになります。ファイルを保存して、状態を失わずに更新が即座に反映されることを確認してください。

uv がインストールされている場合は、次のコマンドで hmr を直接試せます。

uvx hmr path/to/your/entry-file.py

エコシステム

HMR には、さまざまな Python 開発シナリオに対応する豊富なツールエコシステムがあります。

パッケージ	用途
hmr	リアクティブプログラミングライブラリおよび HMR のコア実装
uvicorn-hmr	ASGI アプリ（FastAPI、Starlette など）向けの HMR 対応 Uvicorn サーバー
mcp-hmr	HMR 対応の MCP / FastMCP サーバー
hmr-daemon	変更時にモジュールを更新するバックグラウンドデーモン
fastapi-reloader	ページを自動で再読み込みするブラウザー自動更新ミドルウェア

ヒント

hmr エコシステムは、ほとんどのユースケースで実質的に安定しており、本番環境で使用できます。遅延インポート、動的インポート、モジュールレベルの __getattr__、デコレーターなど、よくある多くのエッジケースや Python らしい マジック なパターンに対応できるよう、慎重に設計されています。ただし、一部のエッジケースでは循環依存によって予期しない動作が発生する可能性があります。__init__.py に大量のコードがある場合は、注意して使用してください。

https://github.com/user-attachments/assets/fb247649-193d-4eed-b778-05b02d47c3f6

その他のデモ

• demo/ - ホットモジュールリロードに対応した基本的なスクリプト
• fastapi/ - ホットリロードとブラウザー更新に対応した FastAPI サーバー
• flask/ - ホットモジュールリロードに対応した Flask アプリ
• mcp/ - 接続を切断せずにコードをリアルタイムで更新できる MCP サーバー

開発の動機

HMR はすでにフロントエンドの世界では一般的な機能です。Vite などのウェブフレームワークは、ページ全体を再読み込みせずにブラウザーへ変更を同期できます。Vitest などのテストフレームワークは、すべてを再実行せずに、必要に応じてテスト結果を更新できます。

それなら、この魔法を Python にも取り入れてみてはどうでしょうか？

仕組み

HMR は静的解析ではなく実行時の依存関係追跡を使用し、きめ細かなリアクティブ性を実現します。

1. シグナルとオブザーバーのパターン：Signal はオブザーバーパターンに代わるものです。データがアクセスまたは変更されるたびに通知するため、シンプルなシグナルシステムを実装しました。
2. カスタムモジュールクラス：すべての __getattr__ と __setattr__ の呼び出しを追跡するカスタムの Module クラスを実装しました。変数が変更されると、その変数を使用するモジュールに通知します。この通知は再帰的に行われますが、粒度は細かく保たれます。
3. ファイルシステムの追跡：watchfiles を使用してファイルの変更を検出します。変更されたパスがインポート済みの Python モジュールである場合、影響を受けるコードの再読み込みが実行されます。さらに、HMR は sys.addaudithook を通じてすべてのファイル読み取りを監視するため、Python 以外のファイル（YAML、JSON など）の変更も適切な再読み込みを実行します。

この実行時アプローチにより、変数単位の粒度での追跡が可能になり、あらゆるファイル形式にまたがる依存関係を追跡できます。これは静的解析よりもはるかに精密です。

コントリビューション

これは、Python エコシステム初の変数レベルで細粒度な HMR フレームワークのひとつかもしれません。そして正直なところ、本当の魅力は、その周りに築いていくエコシステムにあります。

uvicorn と hmr を組み合わせれば、Vite のような開発体験が得られます。pytest と hmr を組み合わせれば、Vitestに匹敵するテスト駆動開発が実現できます。他のライブラリとの組み合わせなら、可能性は無限大です。一緒にアイデアを出し合いましょう。楽しいこと（あるいはちょっとカオスなこと）が生まれるかもしれません！

ヒント

少し背景をお話しすると、hmr のコードは別のリポジトリにあります。実を言うと、HMR フレームワークを作るつもりはありませんでした。これは、Python にリアクティブプログラミングを取り入れる実験として始まりました。その過程で、モジュールのグローバル変数をリアクティブにできるのではないかと思いついたのです。こうして HMR が誕生しました！サイドプロジェクトとして始まりましたが、Python の開発体験を向上させる大きな可能性を秘めていると感じています。

現時点では、このリポジトリに主な実装とサンプルを置いています。HMR に可能性を感じた方も、アイデアを気軽に話し合いたい方も、ぜひご意見をお聞かせください。Python コミュニティには、より動的で応答性の高い開発体験が必要だと考えています。これによって何が実現できるのか、とても楽しみにしています！

さらに読む

細粒度のリアクティビティについては、SolidJS による優れた解説を読むことをおすすめします。