xlsx

XLSX の作成、編集、分析

タスク	アプローチ
数式や書式を含めて作成または編集する	openpyxl — 以下の注意点を参照
大量データの読み込みまたは書き出し	pandas（read_excel、to_excel）
シートの概要確認	markitdown file.xlsx — シートごとに ## SheetName、セル座標はなし。.xlsm や正確な編集には openpyxl を使用
モデルの読み取り（数式と値の両方）	load_workbook を2回実行 — 注意点を参照

パッケージが事前にインストールされていると想定しないでください。適切な環境を再利用するか、uv run --with openpyxl==3.1.5 python your_script.py を使用してください。オプションの表形式リーダーは必要な場合にのみインストールしてください。MarkItDown には xlsx エクストラが必要です。同梱のワークフローは openpyxl 3.1.5 と LibreOffice 26.2.4.2 で検証済みです。現在のオンラインの LibreOffice ヘルプは 26.8 について説明しています。

以下のスクリプトパスは、このスキルのディレクトリからの相対パスです。

すべての出力に求められる要件

• ユーザーが別途指示しない限り、全体を通してプロフェッショナルなフォント（Arial、Times New Roman）を使用すること。
• 数式エラーはゼロにすること。recalc.py が errors_found を報告している間は決して納品しないでください。エラーが自分より前から存在すると思う場合は、それを証明してください。元のファイルを data_only=True で読み込み、そのセルを確認してください。自分が導入したエラーは、引き継いだエラーとまったく同じに見えます。
• 数式を使用し、計算結果をハードコードしないこと。 Python で計算した合計値ではなく、sheet['B10'] = '=SUM(B2:B9)' と記述してください。シートは入力が変更されたときに再計算される必要があります。
• ユーザーの仕様に忠実に従うこと。 正確なタブ名、正確な列ヘッダー、およびユーザーが明示した数式。別のものを計算する再設計は、どれほど洗練されていても失敗です。
• すべての前提とハードコードされた数値を文書化すること — 読者が目にする場所に。セルのコメント、または表の末尾の隣接セルなどです。実在する出典がある場合は引用してください（出典: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]）。数値がユーザーから提供されたものである場合は、その旨を明記してください。
• 誰かが記入するためにあなたが作成するワークブックには、編集すべきセルを示す短い凡例と、期待される形式を示す現実的な値のサンプル行を1行用意する必要があります。編集を依頼されたファイルにそのような行を追加しないでください。
• 既存ファイルを編集する場合: その規約に正確に合わせること。 それらはここにあるすべてのガイドラインより優先されます。まずそのファイルの指定された入力セルを見つけてください — 異なるフォント色、塗りつぶし、または網掛けが目印です — ユーザーが数式の変更を要求しない限り、その数式を保持してください。要求された変更は作業コピーに対して行ってください。

再計算と検証

openpyxl は数式を評価しません。これを介して保存するとワークシートの数式キャッシュが削除され、 その後 load_workbook(data_only=True) は、表計算エンジンが計算するまでそれらの数式セルに対して None を返します。 入力定数は残ります。fullCalcOnLoad を設定するだけでは、キャッシュされた値は生成されません。

python scripts/recalc.py output.xlsx 30   # optional timeout in seconds; default 30
python scripts/recalc.py --help

このヘルパーは、ステージングされたコピーに対して LibreOffice の calculateAll() を、一時プロファイルを使用し、ドキュメントマクロを無効化し、リンクされたドキュメントの更新を無効化して実行します。ファイルが書き換えられたこと、元の数式アンカーが残っていること、数式にキャッシュがあること（空文字列の結果は有効です）を確認します。チェックが成功すると、元のパスをアトミックに置き換えます。バックアップを取ってください: LibreOffice はエクスポート中に書式、埋め込みオブジェクト、数式、外部リンクを変更することがあります。これは計算の互換性チェックであり、ネイティブ Excel の認定でも、ネットワークサンドボックスでもありません。

終了コードだけでなく、JSON を読んでください:

• status: success: 型付きエラーセルは見つかりませんでした。total_formulas は配列アンカーを含む数式セルを数えるのであり、配列のすべての出力セルを数えるのではありません。
• status: errors_found: 再計算が完了し、ファイルは置き換えられましたが、型付き Excel エラーが含まれています。どちらのステータスも終了コード 0 で終了します。total_errors と error_summary がエラーを報告します。 各タイプは最大 100 件の位置をリストし、任意で locations_truncated 件数が付きます。
• status のない error キー: 変換または検証が失敗しました。元のファイルは置き換えられておらず、コマンドは終了コード 1 で終了します。無効な CLI 引数は終了コード 2 で終了します。これを成功した再計算として扱うのではなく、元のファイルを保持して調査してください。

クリーンなエラースキャンは、結果が正しいことや配列出力が完全であることを証明しません。 期待値、単位、合計、数式範囲、および意図されたすべての配列出力セルを独立に確認してください。 関連するスタイル、グラフ、リンク、マクロを前後で比較し、意図されたアプリケーションでワークブックを開くかレンダリングして、列幅、数値形式、印刷範囲、グラフを検査してください。 office/validate.py は XLSX スキーマ検証を明示的に行いません。その終了コードは XLSX の有効性証明ではありません。

外部リンクと保護された機能

='[1]Returns Analysis'!$B$2 は、ワークブックの外部参照リストを通じて別のファイルを参照します。keep_links=True（openpyxl のデフォルト）は、サポートされている場合に外部リンクデータを保持しますが、保存時にワークシート数式のキャッシュされた結果を保持するものではありません。利用できないソースは、再計算後に以前キャッシュされた結果をエラーに変える可能性があります。

このヘルパーは、認識した直接参照、名前付き参照、配列参照のワークシートキャッシュが存在しない場合、それらを拒否します。これは部分的なガードです。推移的な名前、グラフ、条件付き書式、その他のリンクは検出を逃れる可能性があります。--force はこれを回避し、起こりうる損失を受け入れます。使い捨てのコピーにのみ使用してください。欠落したソースファイルを補ったり、リンクされたデータを更新したりはしません。 重要な外部リンク、VBA/UDF、動的スピル、コントロール、その他の Excel 専用機能については、互換性のある Excel ワークフローを使用し、実際のターゲットエンジンを検証してください。静的な値が要求された場合は、元のキャッシュ値ロードからそれらを抽出し、その変換であることを明確に示してください。

検証を通過する数式の選び方

openpyxl で記述する数式には、Calc の UI がセミコロンを使用していても、英語の関数名とカンマを使用してください。元の仕様の後に追加された OOXML 関数には _xlfn. が必要な場合があります。一部はさらに _xlws. も使用します。プレフィックスはエンジンのサポートを保証するものではありません。

• SUMIFS、INDEX、MATCH、IFERROR、SUMPRODUCT は、引き続き有用で移植性の高い選択肢です。
• 新しい関数には必要に応じてプレフィックスを付けます。例えば =_xlfn.TEXTJOIN(",",TRUE,A1:A3) のようにします。 デプロイ先のエンジンで正確な数式を検証してください。その表記からサポートを推測しないでください。
• スカラーの XLOOKUP と XMATCH は現在の LibreOffice で動作します。 どちらも 24.8 で追加されました。 _xlfn.XLOOKUP(2,A1:A3,B1:B3) と _xlfn.XMATCH(2,A1:A3) は 26.2.4.2 で動作確認済みです。 XMATCH は位置を返します。スピル配列関数ではありません。
• SORT、FILTER、UNIQUE、SEQUENCE も LibreOffice 24.8 以降に存在しますが、配列の 格納方法が重要です。素の =_xlfn.SEQUENCE(3,1,1,1) は、テストしたラウンドトリップで エラーなしに最初の値のみを生成しました。エラーのないセルを完全なスピルと同一視しないでください。
• 固定の出力範囲には、openpyxl は ArrayFormula をサポートしています。これを範囲の 左上のセルに割り当て、すべての出力を検証してください。これは自動的にサイズ変更される Excel の動的スピルを約束するものではありません。サイズ変更/スピルのセマンティクスが必要な場合は、ネイティブの Excel を使用してください。

from openpyxl import Workbook
from openpyxl.worksheet.formula import ArrayFormula

wb = Workbook()
ws = wb.active
ws["A1"] = ArrayFormula("A1:A3", "=_xlfn.SEQUENCE(3,1,1,1)")
wb.save("sequence.xlsx")
wb.close()
# Run recalc.py sequence.xlsx, then verify A1:A3 == [1, 2, 3].

openpyxl の注意点

• モデルの読み取りには 2 回のロードが必要です。 data_only=True は数式が消えたキャッシュ値を返します。デフォルトは値のない数式文字列を返します。1 回のパスで両方を得ることはできません。
• data_only=True は保存すると破壊的です。 そのワークブックには数式が残っていないため、保存するとすべてがリテラルに置き換えられ、元に戻せなくなります。
• openpyxl が書き込んだばかりのファイルに対して data_only=True を使うと、数式セルは None を返します — 先に recalc.py を実行してください。(結果が "" である数式も None として読み戻されます。)
• 結合セル: 左上のアンカーにのみ書き込んでください。 範囲内の他のすべてのセルは MergedCell で、その .value は読み取り専用です。
• .xlsm は load_workbook に keep_vba=True を渡さない限りマクロを失います。 これは VBA データを保持しますが、すべての Excel 機能を保持するわけではありません。機能豊富なワークブックを編集する前に、図形、コントロール、描画、その他の埋め込みオブジェクトを棚卸ししてください。openpyxl はそれらすべてを保持するわけではありません。作業コピーを保存し、保存と再計算の後にそれらのオブジェクトを比較してください。必要なオブジェクトがラウンドトリップを生き延びられない場合は、機能を削ぎ落としたワークブックを納品するのではなく、互換性のある Excel ワークフローを使用してください。
• シート間参照ではシート名を引用符で囲んでください: ='Assumptions Inputs'!$B$5。アポストロフィもエスケープするには openpyxl.utils.cell.quote_sheetname(name) を使用してください。
• リッチテキストは、そのセルレベルの書式を保持する必要がある場合、ロード時に rich_text=True が必要です。
• テンプレートには wb.template=True と一致する .xltx/.xltm 拡張子が必要です。通常のワークブックの名前を変更するだけでは不十分です。ヘルパーはテンプレートを AsTemplate=False で編集用にロードします。
• = で始まる信頼できないテキストはテキストのままにしておく必要があります。それを割り当ててから、セルの data_type = "s" を設定してください。先頭にゼロがある識別子は文字列のままにし、明示的な単位/日付は測定値とは別にしてください。

財務モデル

ユーザーが別途指示しない限り、または既存のファイルがすでに別の方法をとっていない限り。

色: ハードコードされた入力値とシナリオのレバーには青いテキスト (0,0,255) · 数式には黒 · 別のシートへのリンクには緑 (0,128,0) · 別のファイルへのリンクには赤 (255,0,0) · 重要な前提とユーザーが入力すべきセルには黄色の塗りつぶし (255,255,0)。

数値: 通貨 $#,##0、単位はヘッダーに記載 (Revenue ($mm)) · ゼロは - で表示 ($#,##0;($#,##0);"-") · 負の値は括弧で囲む · パーセンテージ 0.0%;(0.0%);"-"、小数として保存 (0.15 は 15.0% と表示され、15 を保存すると 1500.0% と表示される) · バリュエーション倍率 0.0"x" · 年はテキストとして ("2024"、2,024 にはしない)。

構造: すべての前提はそれぞれラベル付きのセルに置き、それを使用する数式から参照する (=B5*(1+$B$6)、=B5*1.05 にはしない) · 数式はすべての予測期間で一貫させる。行の途中で 1つのセルだけが編集されているのが最もよくあるサイレントエラーのため · ゼロになり得る分母はガードする。

検証の実例

この小さな合成例は LibreOffice 26.2.4.2 で再計算しました。濃度は 例示用であり、実験による測定値ではありません。再計算後は数式ワークブックを 保存したままにしてください。data_only=True の検証用ロードは保存しないでください。

from openpyxl import Workbook, load_workbook
from openpyxl.comments import Comment
from openpyxl.styles import Font

wb = Workbook()
ws = wb.active
ws.title = "Dilution"
ws.append(["Sample", "Stock (mM)", "Stock volume (uL)", "Final volume (uL)", "Final (mM)"])
ws.append(["Example A", 10, 20, 100, "=B2*C2/D2"])
ws["A4"] = "Edit A2:D2; E2 calculates concentration. Synthetic example inputs."
ws["B2"].comment = Comment("Illustrative stock concentration; replace with measured input.", "Source")
for row in ws.iter_rows():
    for cell in row:
        cell.font = Font(name="Arial", size=11)
for cell in ws[1]:
    cell.font = Font(name="Arial", size=11, bold=True)
for col in "ABCDE":
    ws.column_dimensions[col].width = 22
ws["E2"].number_format = '0.00'
ws.freeze_panes = "A2"
wb.save("dilution.xlsx")
wb.close()
# Run: python scripts/recalc.py dilution.xlsx
# Then in a separate verification step:
# cached = load_workbook("dilution.xlsx", data_only=True)
# assert cached["Dilution"]["E2"].value == 2
# cached.close()

テーブルのみの新規エクスポートには、pandas が df.to_excel("table.xlsx", sheet_name="Data", index=False, engine="openpyxl") をサポートしています。 pd.read_excel(path, sheet_name=None, engine="openpyxl") はすべてのシートを辞書に読み込みます。 dtype/converters と欠損値の扱いは意図的に選択してください。DataFrame のラウンドトリップは スタイル付きモデル、数式、埋め込みオブジェクトを保存するワークフローではありません。

依存関係とレビュー済みドキュメント

再計算には openpyxl と別途インストールした LibreOffice (PATH 上の soffice) が必要です。 共有 OOXML ユーティリティは defusedxml と lxml も使用します。オプションの pandas は表形式データを 扱います。MarkItDown は XLSX 変換に markitdown[xlsx] を必要とします。MarkItDown の XLSX コンバーターで .xlsm がサポートされると想定しないでください。そのドキュメント化されたソースディスパッチが認識するのは .xlsx/XLSX MIME です。ワークブックの処理に API 認証情報やリモートサービス呼び出しは必要ありません。

• openpyxl の読み込み、保存、テンプレート
• openpyxl の数式と ArrayFormula
• pandas read_excel と to_excel
• MarkItDown XLSX コンバーター
• LibreOffice XLOOKUP、XMATCH、SEQUENCE
• LibreOffice ドキュメント読み込みプロパティ と calculateAll

---

このスキルは Anthropic に由来します。リポジトリのメタデータと追加の保存に関するガイダンスを加えてここに適応させたものです。条件については LICENSE.txt を参照してください。