概要

numbers2xlsx.py は、Apple Numbers 形式 (.numbers) のドキュメントを Microsoft Excel ワークブック形式 (.xlsx) に変換するためのコマンドラインツールです。

動作原理

本スクリプトは、Numbers のデータ構造を解析し、Excel 互換の形式に再構築します。 Numbers は1つのシート内に複数の表を独立して配置できる仕様を持っていますが、Excel では1つのシートが1つの大きなグリッドとして扱われます。このレイアウトの曖昧さを回避するため、本スクリプトは Numbers の「1つのテーブル（表）」を、Excel の「1つのワークシート」として1対1で変換します。

データの変換処理では以下の調整が行われます。

  • ワークシート名に使用できない文字 (\, /, *, ?, :, [, ]) を _ に置換し、Excel の上限である31文字以内に切り詰めます。

  • セルの文字列長が Excel の上限である32767文字を超える場合は切り詰めます。

  • NaN や Infinity などの浮動小数点数の特殊値、およびタイムゾーン付きの日時データを、Excel で扱える形式に正規化します。

  • セルの書式（フォント、塗りつぶし、配置、罫線）、行の高さ、列の幅、結合セル、ハイパーリンクを可能な限り再現します。

依存ライブラリ

標準ライブラリに加えて、以下の非標準ライブラリに依存しています。

  • numbers-parser (Numbers ファイルの読み込みとパースに使用)

  • openpyxl (Excel ファイルの構築と保存に使用)

入出力仕様

  • 入力: Apple Numbers ファイル (.numbers)

  • 出力: Microsoft Excel ワークブック (.xlsx)

出力先のファイルパスを明示的に指定しない場合、入力ファイルと同じディレクトリに拡張子を .xlsx に変更したファイルが出力されます。 ファイル保存時は、Python の tempfile を使用して一時ファイルに書き出してから対象パスをリプレイス操作で上書きすることで、変換途中の破損したデータが保存されるのを防ぐ安全な保存処理を行います。

コマンドラインオプション

以下は本スクリプトで利用可能な引数およびオプションです。

  • input

    • 必須。変換元の入力 .numbers ファイルのパスを指定します。

  • output_positional または -o, --output

    • 任意。出力先の .xlsx ファイルのパスを指定します。第2引数として指定するか、オプションで指定するかのどちらか一方のみを利用できます。

  • --formulas

    • 数式を含むセルの変換方法を指定します。

    • values : 計算結果のみを値として出力します（既定動作）。

    • comments : 計算結果を値として出力し、セルのコメントとして元の数式を書き込みます。

    • formulas : 数式そのものを Excel の関数・数式として書き込みます。

  • --formatted-values

    • 数値や日時データを Numbers 上での表示文字列として書き出します。このオプションを使用した場合、Excel 上でのデータ型は文字列になります。

    • 注意: --formulas formulas と同時には指定できません。

  • --no-styles

    • セルの基本書式（フォント、色、罫線など）を変換しません。

  • --no-merges

    • セルの結合を変換しません。

  • --no-freeze

    • Numbers で設定されているヘッダー行・ヘッダー列を、Excel のウィンドウ枠の固定として適用しません。

  • --overwrite

    • 出力先ファイルが既に存在する場合に上書きを許可します。

実行例

基本的な変換（入力ファイルと同じディレクトリに変換結果を出力する）:

python numbers2xlsx.py sample.numbers

出力先のファイル名を明示的に指定して変換する:

python numbers2xlsx.py sample.numbers converted.xlsx

出力先のファイル名をオプションで指定し、既存ファイルを上書きする:

python numbers2xlsx.py sample.numbers -o converted.xlsx --overwrite

数式をそのままExcelの数式として変換する:

python numbers2xlsx.py sample.numbers --formulas formulas

計算結果の値を出力しつつ、元の数式をセルのコメントに残す:

python numbers2xlsx.py sample.numbers --formulas comments

Numbersでの表示通りの文字列としてデータを出力する:

python numbers2xlsx.py sample.numbers --formatted-values