xlsx

Xlsx スキル

Python と openpyxl を使用して Excel の .xlsx ブックを操作します。数式やグラフを含む、スタイル設定済みの複数シートのブックを作成したり、既存ファイルを検査またはダンプしたり、セルや構造を編集したり、CSV との相互変換を行ったりできます。すべてのヘルパースクリプトは argparse の CLI で、JSON を出力し、明示的に UTF-8 で入出力します。

使用する場面

• .xlsx レポートの作成：複数のシート、数値形式、スタイル設定、セルの結合、ウィンドウ枠の固定、オートフィルター、条件付き書式、グラフ、データ検証のドロップダウン、Excel ネイティブのテーブル、定義名、ハイパーリンク、セルのメモ、シートの保護。
• ブックの読み取り：シート一覧、データの JSON または CSV 形式でのダンプ、数式とキャッシュ値の一覧表示、メモ、定義名、テーブル。
• 既存ファイルの編集：セルの設定、行の追加、行や列の挿入・削除（xlsx_restructure.py を使用した参照先の更新に対応）、シート、テーブル、名前、メモ、保護のコピーや名前変更。
• LibreOffice を使用したヘッドレスでの数式再計算（xlsx_recalc.py）。
• 型推論や UTF-8 以外のエンコーディングに対応した CSV 相互運用。
• 旧式の .xls バイナリ形式には対応していません（先に LibreOffice で変換してください：soffice --headless --convert-to xlsx old.xls）。

前提条件

• openpyxl をインストールした Python 3.10 以降（pip install openpyxl）。他のサードパーティ製パッケージは不要で、それ以外はすべて標準ライブラリを使用します。
• 任意：ヘッドレスでの再計算や形式変換に使用する LibreOffice（soffice）。

実行方法

このスキルの scripts/ ディレクトリから terminal ツールを使ってヘルパースクリプトを実行します（すべてのスクリプトが --help に対応しています）。

python scripts/xlsx_create.py spec.json report.xlsx   # build from JSON spec
python scripts/xlsx_read.py report.xlsx --sheets      # inventory
python scripts/xlsx_read.py report.xlsx --json --sheet Data
python scripts/xlsx_read.py report.xlsx --formulas
python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2
python scripts/xlsx_recalc.py report.xlsx
python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data

write_file で JSON 仕様を作成し、read_file または標準出力からスクリプトの JSON 出力を直接確認します。

クイックリファレンス

タスク	コマンド
仕様からブックを作成	xlsx_create.py spec.json out.xlsx
シート名とサイズ	xlsx_read.py f.xlsx --sheets
シートを JSON としてダンプ	xlsx_read.py f.xlsx --json --sheet S
シートを CSV としてダンプ	xlsx_read.py f.xlsx --csv --out d.csv
数式とキャッシュ値を一覧表示	xlsx_read.py f.xlsx --formulas
セル／数式を設定	xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"
行を追加	xlsx_edit.py f.xlsx --append '[1,"x",true]'
2 行を挿入、参照先は移動しない	xlsx_edit.py f.xlsx --insert-rows 3:2
2 行を挿入、参照先も移動	xlsx_restructure.py f.xlsx --insert-rows 3:2
列を削除、参照先も移動	xlsx_restructure.py f.xlsx --delete-cols B
ネイティブテーブルを作成	xlsx_edit.py f.xlsx --add-table Sales:A1:C9
テーブル内に行を追加	--table-append 'Sales=["West",5]'
テーブルを一覧表示	xlsx_edit.py f.xlsx --list-tables
定義名	--define-name "Rates='Data'!$B$2:$B$9" / --delete-name Rates / xlsx_read.py f.xlsx --names
ハイパーリンク	`--hyperlink "A1=https://example.com
セルのメモ	`--note "B2=Check this
シートを保護（注意点を参照）	--protect your-password --unlock B2:B9
LibreOffice で再計算	xlsx_recalc.py f.xlsx
シートをコピー／名前変更	--copy-sheet Src:New --rename-sheet Old:New
開いたときに再計算を強制	xlsx_edit.py f.xlsx --recalc
CSV → スタイル設定済み xlsx	csv_to_xlsx.py in.csv out.xlsx
xlsx → CSV	xlsx_to_csv.py f.xlsx out.csv --encoding utf-8

手順

1. 作成：JSON 仕様を記述します（スキーマは xlsx_create.py --help とその docstring に記載されています）。各シートでは rows（スカラー値またはスタイル付きセルオブジェクト）、疎な cells オーバーライド、 column_widths、row_heights、merges、freeze_panes、 autofilter、conditional_formats（cell_is ルールとカラー スケール）、charts（セル範囲を使用した棒・折れ線・円グラフ）、 validations（リストのドロップダウン）、tables（スタイル名を指定した Excel ネイティブのテーブル）、protection を設定できます。ブックレベルの defined_names では、名前と参照を対応付けます。セルオブジェクトには hyperlink と note も指定できます。 型付きの値：JSON の数値／ブール値はそのまま使用できます。日付には {"value": "2026-01-31", "type": "date"} を使用します。 数値形式には Excel の書式文字列を使用します：通貨は "$#,##0.00"、 パーセントは "0.0%"、日付は "yyyy-mm-dd" です。
2. 数式：仕様では "formula": "SUM(B2:B9)"、エディターでは --set "C1==SUM(A:A)" を使って設定します。数式を書き込む場合は、 "full_calc_on_load": true（仕様）または --recalc（エディター）を指定します。 これにより、ブックの fullCalcOnLoad フラグが設定され、Excel／LibreOffice が ファイルを開いたときにすべてを再計算します。openpyxl 自体は数式を 評価しません。
3. 読み取り：--sheets はシート一覧（名前、サイズ、結合範囲、 グラフ数、テーブル、保護、定義名）を表示します。 --json／--csv はデータ用、--formulas は各数式文字列と キャッシュ済みの結果のペア用、--notes はセルのコメント用、 --names は定義名用です。キャッシュ済みの結果が存在するのは、 ファイルが最後に実際のスプレッドシートアプリで保存された場合に限られます。 openpyxl で新規作成したファイルでは、ここに null が返されます。 結果をヘッドレスで確定するには xlsx_recalc.py file.xlsx を実行します （LibreOffice を使用します。soffice がない場合は {"recalculated": false, ...} を出力して終了コード 0 で終了します）。 その後、--data-only を付けて再読み込みします。
4. 編集：xlsx_edit.py は、まず名前変更／コピーを適用し、次に 行／列の構造変更を行い、その後 --set／--append を適用します。 --out を指定しない限り、インプレースで編集します。元のファイルが必要な場合は、 先にファイルをコピーしてください。
5. 再構成：数式、結合セル、テーブル、フィルターを含むシートに行／列の挿入や 削除を行う場合は、xlsx_edit.py ではなく xlsx_restructure.py を 使用します。すべてのシートの数式参照（絶対 $ 参照、範囲、別シートへの参照）を 書き換え、結合セル、autofilter、freeze panes、検証と条件付き書式の 範囲、テーブル参照、定義名、行／列の寸法を移動した後、 not_shifted リストを含む JSON レポートを出力します。 ルールと制限事項：references/restructuring.md。
6. CSV の相互運用：csv_to_xlsx.py はセルごとに int／float／bool／ISO 日付を 推定し、ヘッダー行にスタイルを適用します。xlsx_to_csv.py は ISO 日付と、 空のセルには空文字列を書き込みます。どちらもデフォルトで UTF-8 を使用し、 --encoding を受け付けます（例：Excel で扱いやすい BOM 付きの utf-8-sig、 従来の Windows エクスポート用の cp1252）。

PDF への変換

LibreOffice はヘッドレスで変換できます（単一シートの CSV エクスポートにも対応しています）。

soffice --headless --convert-to pdf report.xlsx --outdir out/
soffice --headless --convert-to csv report.xlsx --outdir out/  # 1st sheet only

CSV に出力されるのは最初のシートのみです。他のシートを出力するには xlsx_to_csv.py --sheet NAME を使用します。soffice がない場合は、 LibreOffice をインストールするか、変換せずにファイルをユーザーに渡してください。

注意点

• openpyxl は計算を行いません。 数式の結果を取得できるのは、load_workbook(path, data_only=True) を使った場合に限られ、さらに、ファイルが事前に Excel／LibreOffice で保存されている必要があります。そうでない場合は None が返されます。
• xlsx_edit.py の挿入／削除では参照は移動しません（openpyxl の標準動作です）。参照を移動する xlsx_restructure.py を使ってください。ただし、このスクリプトでもグラフのアンカー、画像、条件付き書式の RULE 数式は移動できません。JSON レポートの not_shifted リストと references/restructuring.md を確認してください。
• シートの保護はセキュリティではありません。 --protect は標準の xlsx シート保護ハッシュを設定します。これは、適切に動作するアプリに「編集しないでください」と伝えるだけで、それ以上の効果はありません。zip 内の XML を編集するか、LibreOffice でチェックを外せば、誰でも解除できます。機密性や完全性の確保に決して頼らないでください。何も暗号化されません。
• data_only=True で読み込んでから保存すると、すべての数式が気付かないうちに破棄されます（数式の代わりにキャッシュ値が保存されます）。それが目的でない限り、この方法で読み込んだブックを保存しないでください。
• 読み込み時にグラフ／画像が削除されます：openpyxl はグラフを往復処理できないため、グラフを含むブックを編集して保存すると、グラフが削除されます。編集後にグラフを再追加するか、グラフを含むファイルの再保存を避けてください。
• CSV のロケールに関する注意点：必ずエンコーディングを明示してください（スクリプトではすでに指定しています）。また、ヨーロッパの CSV では区切り文字に ;、小数点にカンマを使うことがよくあります。--delimiter ';' を指定し、"12,5" のような値は文字列のまま扱われることを想定してください。
• 日付は datetime です：Excel では日付をシリアル値として保存しますが、openpyxl は datetime／date オブジェクトを返します。ダンプでは ISO 形式の文字列が出力されます。
• シート名は最大 31 文字で、[ ] : * ? / \ は使用できません。

検証

• 作成後に xlsx_read.py out.xlsx --sheets を実行し、シート名、サイズ、結合範囲、グラフの数が意図どおりであることを確認してください。
• --json でデータをダンプし、元の値と比較してください。
• 編集後に、変更した範囲を再度ダンプしてください。数式を書き込んだ場合は、--formulas に数式が一覧表示され、--recalc が適用されていることを確認してください。
• xlsx_restructure.py の実行後は、JSON レポートを読み、--formulas と --sheets を再実行して、参照と範囲が想定どおりに配置されたことを確認してください。
• 全体を目視で確認するには、LibreOffice で開いてください： soffice --headless --convert-to pdf out.xlsx を実行し、PDF を確認します。