Python TutorとSphinx向け拡張
すごく雑なきっかけで、Sphinx拡張を増やしました。 [1]
この記事は、日本語で書いた簡易的なリリースノートです。
Python Tutorの紹介
Python Tutorは、Pythonの教育用ツールで、コード実行時におけるメモリの使用や参照の状況を可視化くれます。
ステップ単位で見ていくことが出来るため、動作の理解に役立ちます。
「Python Tutor」という名称ではありますが、JavaやCなどのいくつかの言語にも対応しています。
使ってみる
以下のような流れで使っていきます。
- https://pythontutor.com/visualize.html#mode=edit にアクセスする。
- 横に「Write code in 〜」 とあるセレクトボックスから、言語を選択する。（今回であればPython 3.11を推奨）
- その下のコードブロックにコードを書いていく。
- コードを書いたら、コードブロックの下にある「Visualize Execution」ボタンをクリックする。
- 実行の様子を確認できる画面に切り替わる。
- コードの下にある、スクロールバーとボタンを操作して変数の動きを見る。（画面右に表示される）
- コードを修正したい場合は、「Edit this code」のリンクをクリックすることで編集画面に戻る。
共有する
実行状態を共有したい場合は、「Generate permanent link」「Generate embed code」ボタンをクリックしてください。
それぞれのボタン右にコピー用のコードが出力されます。
例えば、「Generate permanent link」ボタンで出力されるのはこのリンクのURLです。
「Next >」 というボタンを押していくと、listオブジェクトの操作とfor文内の動作を見やすく表現してくれています。 [2]
ドキュメント上で共有する際にはいずれかのURLを貼り付ける必要があるわけですが、若干管理が面倒です。
というのも、この仕組みの関係で貼り付けるURLを再生成するためには、Python Tutorにアクセス→コードを編集→リンクの再生成という手順を踏む必要があるためです。
とはいえ、実はURL内にコードがそのまま含まれています。
なるべくならこの特性を利用して楽に運用したいと思いませんか。
ちょっとした余談
さてこのURLですが、ちょっと変わった作りになっています。
大まかには次の2点がちょっと特殊です。
- 細かいパラメーターが、クエリパラメーターではなくアンカー部で宣言する形式を取っている
- コードがURLEncodeではない形式でエンコードされている
このせいで、続きの話がちょっと面倒になっています。
atsphinx-pythontutor
で、こんなのを作りました。
名前の通りSphinx拡張でPython Tutor用のURL等を生成するためのものとなっています。
使うには
使い方自体は非常にシンプルです。
-
conf.pyのextensionsに、"atsphinx.pythontutor"を追加する。 - 下記のようなディレクティブを記述する。
.. pythontutor::
members = ["Mizuki", "Kageyama", "Matsumoto", "Sakamoto", "Endo"]
print(f"初期: {len(members)} 人")
members.append("Kitadani")
members.remove("Mizuki")
members += ["Okui", "Fukuyama"]
members.remove("Sakamoto")
members.append("Ricardo")
print(f"現在: {len(members)} 人")
for m in members:
print(m)
これだけで、ビルドをするとpythontutorディレクティブのある箇所には、記述したコードを使ったPython Tutorのiframeが出力されるようになります。
なお、altオプションをつけると、そのテキストにはURLのリンクが貼られます。
そもそもなんで作ったのか？
きっかけ自体はPyCon JP 2024のDeveloper Sprintに参加したことです。
これは例年PyCon JPのカンファレンスデーの翌日に行われる、集まったPythonisitaたちなどと一緒に開発や課題解決に取り組むイベントです。
特段チームで動くということをしていなかったのですが、たまたまPython Boot Campのリポジトリを見て、Python Tutorの存在を初めて知りました。
リンクやiframeがそのまま埋め込まれていたのですが、「もし自分のサイトで使うにしてもURLのまま管理するのはなんとなくやだ」というだけの理由でとりあえず作ったものです。
とりあえず、開発欲が解消されたので良い機会でした。
Discussion