xlsx

Excel ワークブック

openpyxl と pandas はすでにご存じでしょう。このスキルでは、コードからは分からないことを補います。ワークブックで実際に何が問題なのかを報告する再計算の手順と、ファイルを気付かないうちに壊してしまう openpyxl と LibreOffice の動作です。

スクリプトの実行

<skill> はこのファイルが置かれているディレクトリです。バンドルされたスクリプトは、ユーザーの作業ディレクトリを基準に絶対パスで実行してください。そうすれば、スクリプト内の相対パスがそのまま機能します。

uv run <skill>/scripts/recalc.py model.xlsx

作成した Python コードは、依存関係を宣言して実行してください。uv run --with openpyxl script.py を使うか、PEP 723 ヘッダーを記述します。再計算には LibreOffice（soffice）が必要です。

ツールの選択

• openpyxl は、納品するワークブックすべてに使用します。数式、書式、グラフ、入力規則、コメントに対応しています。読み込んだファイルのグラフ、画像、コメント、データの入力規則、条件付き書式は保持します。図形、テキストボックス、スライサー、フォームコントロールなど、モデル化されていない要素は削除されるため、それらを含むワークブックを編集する前に確認してください。
• pandas は、分析と一括読み込みに使用します。書き込み時に保持されるのは値だけなので、今後もユーザーが使い続けるワークブックの編集には決して使用しないでください。
• .xlsm ファイルは、load_workbook(path, keep_vba=True) で読み込んでください。そうしないと、保存時にマクロが失われます。

値ではなく数式を使う

何かから導出される値は、入力が変わったときにもワークブックが正しく保たれるよう、シート内の数式にしてください。スプレッドシートで表現できない処理だけを Python で計算し、ラベル付きの入力値として書き込みます。

ws["B10"] = "=SUM(B2:B9)"          # not ws["B10"] = df["Sales"].sum()
ws["C5"] = "=(C4-C2)/C2"           # growth, from the cells it depends on
ws["D3"] = "=B3*(1+$B$1)"          # assumptions live in their own cells

出力の確認

openpyxl は数式を書き込みますが、値は書き込みません。そのため、再計算が完了するまでファイルは完成ではありません。数式に影響する保存を行うたびに、次の処理を実行し、納品前に報告された問題を修正してください。

uv run <skill>/scripts/recalc.py model.xlsx

この処理は LibreOffice で再計算し、値をファイルに書き戻して、JSON を出力します。問題がなければ終了ステータスは 0、問題があれば 1、実行できなかった場合は 2 です。

フィールド	意味と修正方法
errors	{"#DIV/0!": {"count": 3, "locations": ["Model!C7", …]}} のように、種類ごとのエラー値を示します。種類ごとに最大50件の場所が表示されます。該当するセルの数式を修正してください。
missing_prefix	ファイル形式で必要な接頭辞を付けずに記述された、新しい関数を示します（下記参照）。ファイルは変更されず、各項目の fix に修正済みの数式が含まれます。
circular_references	相互に依存しているセルのグループを示します。LibreOffice ではこれらが #VALUE! と表示されるため、まず循環参照を解消してください。
uncalculated	LibreOffice が値を計算しなかった数式を示します。通常は LibreOffice が実装していない関数が原因です。Excel ではワークブックが引き続き動作する場合がありますが、その旨をユーザーに伝えてください。

別のワークブックへのリンクがある場合、再計算によってリンク先の値が上書きされるため、処理は停止します。ユーザーがそれを了承した場合に限り、--force を渡してください。

ひそかに失敗する落とし穴

• 関数のプレフィックス。 Excel 2007 より後に追加された関数は、プレフィックス付きで保存されます。=_xlfn.XLOOKUP(…)、=_xlfn.TEXTJOIN(…)、=_xlfn.IFS(…)、=_xlfn._xlws.FILTER(…)、=_xlfn._xlws.SORT(…) と記述してください。プレフィックスがないと、Excel と LibreOffice の両方で #NAME? が表示されます。recalc を使えば、問題が起きる前にこれらを検出できます。LibreOffice 24.8 より古いバージョン（soffice --version）では、XLOOKUP、XMATCH、FILTER、SORT、SORTBY、UNIQUE、SEQUENCE、LET がサポートされていないため、プレフィックスを付けても recalc で警告されます。Excel では引き続きブックを計算できるため、数式を書き換えるのではなく、その旨をユーザーに伝えてください。
• 行や列の挿入・削除。 insert_rows、delete_rows、insert_cols、delete_cols はセルを移動しますが、それらを参照する数式は書き換えません。行の上に行を挿入しても、=SUM(B1:B4) は =SUM(B1:B4) のままです。影響を受ける数式は自分で書き換えるか、挿入が必要にならないようにシートを構成してください。
• data_only=True はキャッシュされた値を読み込みます。この状態で開いたブックを保存すると、すべての数式が最後に計算された値に置き換わり、元に戻せなくなります。
• 動的配列。 openpyxl では、スピルする数式を書き込めません。FILTER、SORT、UNIQUE、SEQUENCE は1つのセルに格納され、Excel によって @ が付与されます。1セルごとに1つの値を返す数式を優先してください。
• インデックス。 行番号と列番号は1から始まります。get_column_letter と column_index_from_string を使い、列 Z より先の列を手作業で数えないでください。

グラフ

ブック内に含めるグラフには openpyxl のネイティブグラフ（openpyxl.chart）を使用してください。これらのグラフはセルとのリンクを維持します。グラフを別の場所で使用する場合に限り、matplotlib の画像をレンダリングしてください。

既存のブックとテンプレート

変更する前にファイルを確認し、フォント、塗りつぶし、数値形式、列幅、レイアウトを正確に合わせてください。そのファイルの規則は、以下の内容より優先されます。

財務モデル

ユーザーまたはテンプレートに別の指示がない限り、次のとおりにしてください。

• 役割ごとのフォント色： ハードコードされた入力値は青 0000FF、数式は黒、他のシートへのリンクは緑 008000、他のファイルへのリンクは赤 FF0000 にします。重要な前提条件は黄色の塗りつぶし FFFF00 で示します。
• 数値形式：
  • 通貨：$#,##0;($#,##0);-。単位はヘッダーに記載します（例：「Revenue ($mm)」）。
  • パーセンテージ：0.0%。
  • 倍率：0.0x。
  • 負の数：括弧で囲みます。
  • 年：テキストとして記述し、「2026」が「2,026」にならないようにします。
• 構成： 各前提条件はラベル付きの独立したセルに置き、数式にはそのセルを参照させます。数式に直接入力しないでください。各予測期間には、前の期間と同じ数式を使用します。
• 出典： ハードコードされた数値にはすべて、セルのコメントまたは隣接するセルに出典を記載します（例：「Source: Company 10-K, FY2025, p. 45」）。