libreoffice-calc

LibreOffice Calc

UNO を利用した Calc のスプレッドシート操作には、同梱の calc モジュールを使用します。 すべてのパスは絶対パスである必要があります。同梱モジュールは、このスキルのディレクトリ内にある scripts/ に配置されているため、PYTHONPATH=<skill_base_dir>/scripts を設定してください。 セットアップや実行時に問題が発生した場合は、references/troubleshooting.md を確認してください。

API の概要

# Non-session utilities
create_spreadsheet(path, source=None)              # source: path to .json or .xml file to import
export_spreadsheet(path, output_path, export_format)   # formats: "pdf", "xlsx", "csv"
snapshot_area(doc_path, output_path, sheet="Sheet1", row=0, col=0, width=None, height=None, dpi=150)

# Session (primary editing API)
CalcSession(path) -> context manager

CalcSession methods:
  read_cell(target: CalcTarget) -> dict[str, object]
  write_cell(target: CalcTarget, value, value_type="auto")
  read_range(target: CalcTarget) -> list[list[dict[str, object]]]
  write_range(target: CalcTarget, data)
  format_range(target: CalcTarget, formatting: CellFormatting)
  list_sheets() -> list[dict[str, object]]
  add_sheet(name, index=None)
  rename_sheet(target: CalcTarget, new_name)
  delete_sheet(target: CalcTarget)
  define_named_range(name, target: CalcTarget)
  get_named_range(target: CalcTarget) -> dict[str, object]
  delete_named_range(target: CalcTarget)
  set_validation(target: CalcTarget, rule: ValidationRule)
  clear_validation(target: CalcTarget)
  create_chart(target: CalcTarget, spec: ChartSpec)
  update_chart(target: CalcTarget, spec: ChartSpec)
  delete_chart(target: CalcTarget)
  recalculate()
  patch(patch_text, mode="atomic") -> PatchApplyResult
  export(output_path, export_format)
  reset()
  close(save=True)

# Standalone patch utility
patch(path, patch_text, mode="atomic") -> PatchApplyResult

構造化ターゲット：CalcTarget

from calc import CalcTarget

CalcTarget(
    kind="cell" | "range" | "sheet" | "named_range" | "chart",
    sheet=None,
    sheet_index=None,
    row=None,
    col=None,
    end_row=None,
    end_col=None,
    name=None,
    index=None,
)

ターゲットの種類

種類	対応フィールド	用途
cell	sheet または sheet_index、row、col	1 つのセルの読み取りまたは書き込み
range	sheet または sheet_index、row、col、end_row、end_col	矩形範囲の読み取り、書き込み、書式設定、検証、またはグラフ作成
sheet	sheet または sheet_index	1 つのシートの名前変更または削除
named_range	name	1 つの名前付き範囲の確認または削除
chart	sheet または sheet_index、および name または index	1 つのグラフの更新または削除

解決ルール

• 座標は 0 から始まり、0 以上である必要があります。
• sheet と sheet_index は相互に排他的です。
• name と index は相互に排他的です。
• 範囲ターゲットでは、end_row >= row かつ end_col >= col を満たす必要があります。
• グラフターゲットでは、1 つのシートと 1 つのグラフセレクターを指定する必要があります。
• Calc は 1 セルの範囲をセルターゲットに自動変換しません。これらの形式は明示的に指定してください。

セル読み取り結果

read_cell() と read_range() は、同じ形式のセル辞書を返します。

{
    "value": 100.0,
    "formula": None,
    "error": None,
    "type": "number",
    "raw": 100.0,
}

空のセルは type="empty"、value=None を返します。

{"value": None, "formula": None, "error": None, "type": "empty", "raw": None}

数式セルの type は "formula" です。Calc が数式エラーを報告した場合は、error が設定され、value は None になります。

ブール値（True／False）は、数値の 1.0／0.0 として保存されます。Python のブール値を書き込んだセルを読み取ると、テキスト文字列ではなく、type="number"、value=1.0 または value=0.0 が返されます。

書式設定ペイロード：CellFormatting

from calc import CellFormatting

CellFormatting(
    bold=None,
    italic=None,
    font_name=None,
    font_size=None,
    color=None,          # named color or integer
    number_format=None,  # "currency" | "percentage" | "date" | "time"
)

注意事項：

• 少なくとも 1 つの書式設定フィールドを設定する必要があります。
• color には、色名または 0xRRGGBB 整数を指定できます。
• format_range() は、cell ターゲットと矩形の range ターゲットの両方で機能します。

検証ペイロード：ValidationRule

from calc import ValidationRule

ValidationRule(
    type="whole",
    condition="between",
    value1=1,
    value2=10,
    show_error=True,
    error_message="Enter a value from 1 to 10.",
    show_input=True,
    input_title="Allowed values",
    input_message="Only integers from 1 to 10 are valid.",
    ignore_blank=True,
    error_style=0,
)

対応する type の値：

• any
• whole
• decimal
• date
• time
• text_length
• list

対応する condition の値：

• between
• not_between
• equal
• not_equal
• greater_than
• less_than
• greater_or_equal
• less_or_equal

グラフペイロード：ChartSpec

from calc import CalcTarget, ChartSpec

ChartSpec(
    chart_type="line",
    data_range=CalcTarget(
        kind="range",
        sheet="Data",
        row=0,
        col=0,
        end_row=5,
        end_col=1,
    ),
    anchor_row=7,
    anchor_col=0,
    width=10000,
    height=7000,
    title="Revenue Trend",
)

注意事項：

• chart_type には、bar、line、pie、scatter のいずれかを指定する必要があります。
• width と height には、Calc のグラフ矩形単位（パッケージ化された API がすでに受け付けるものと同じ単位）を使用します。
• グラフはシートをターゲットとして作成します。更新または削除する場合は、グラフをターゲットとして指定します。

パッチ DSL

patch() または session.patch() を使用して、順序付きのスプレッドシート操作を適用します。

[operation]
type = write_range
target.kind = range
target.sheet = Revenue Data
target.row = 0
target.col = 0
target.end_row = 2
target.end_col = 1
data <<JSON
[["Label", "Value"], ["Revenue", 100], ["Cost", 80]]
JSON

[operation]
type = format_range
target.kind = range
target.sheet = Revenue Data
target.row = 1
target.col = 1
target.end_row = 2
target.end_col = 1
format.number_format = currency
format.bold = true

[operation]
type = create_chart
target.kind = sheet
target.sheet = Revenue Data
chart.chart_type = line
chart.data_range.kind = range
chart.data_range.sheet = Revenue Data
chart.data_range.row = 0
chart.data_range.col = 0
chart.data_range.end_row = 2
chart.data_range.end_col = 1
chart.anchor_row = 5
chart.anchor_col = 0
chart.width = 9000
chart.height = 6000
chart.title = Revenue Trend

対応する操作の種類

• write_cell
• write_range
• format_range
• add_sheet
• rename_sheet
• delete_sheet
• define_named_range
• delete_named_range
• set_validation
• clear_validation
• create_chart
• update_chart
• delete_chart
• recalculate

パッチ値のルール

• 主なターゲットには target.* フィールドを使用します。
• CellFormatting には format.* フィールドを使用します。
• ValidationRule には rule.* フィールドを使用します。
• ChartSpec には chart.* フィールドを使用します。グラフのソース範囲には chart.data_range.* を使用します。
• data は有効な JSON である必要があります。
• 複数行の JSON またはテキストには、<<TAG ... TAG 形式のヒアドキュメントブロックを使用できます。

モード

• atomic は最初の失敗時に停止し、セッションをリセットして、何も永続化しません。
• best_effort は先行する操作の成功結果を保持し、失敗を記録します。

PatchApplyResult のフィールド：

• mode
• overall_status = "ok" | "partial" | "failed"
• operations = PatchOperationResult のリスト
• document_persisted

スタンドアロンの patch(path, ...) では、document_persisted は変更がディスクに保存されたことを意味します。session.patch(...) では、現在開いているセッションの状態で、パッチが成功した変更を生成したことを意味します。

例：セッション内でスプレッドシートを作成する

from pathlib import Path

from calc import (
    CalcSession,
    CalcTarget,
    CellFormatting,
    ChartSpec,
    ValidationRule,
)
from calc.core import create_spreadsheet

output = str(Path("test-output/revenue-report.ods").resolve())
create_spreadsheet(output)

with CalcSession(output) as session:
    session.rename_sheet(CalcTarget(kind="sheet", sheet="Sheet1"), "Revenue Data")
    session.add_sheet("Summary")
    session.write_range(
        CalcTarget(kind="range", sheet="Revenue Data", row=0, col=0, end_row=2, end_col=1),
        [["Label", "Value"], ["Revenue", 100], ["Cost", 80]],
    )
    session.format_range(
        CalcTarget(kind="range", sheet="Revenue Data", row=1, col=1, end_row=2, end_col=1),
        CellFormatting(number_format="currency", bold=True),
    )
    session.define_named_range(
        "RevenueValues",
        CalcTarget(kind="range", sheet="Revenue Data", row=1, col=1, end_row=2, end_col=1),
    )
    session.set_validation(
        CalcTarget(kind="range", sheet="Revenue Data", row=1, col=1, end_row=2, end_col=1),
        ValidationRule(type="whole", condition="greater_than", value1=0),
    )
    session.create_chart(
        CalcTarget(kind="sheet", sheet="Revenue Data"),
        ChartSpec(
            chart_type="line",
            data_range=CalcTarget(
                kind="range",
                sheet="Revenue Data",
                row=0,
                col=0,
                end_row=2,
                end_col=1,
            ),
            anchor_row=5,
            anchor_col=0,
            width=9000,
            height=6000,
            title="Revenue Trend",
        ),
    )
    session.recalculate()

例：既存のスプレッドシートにパッチを適用する

from calc import patch

result = patch(
    "/abs/path/revenue-report.ods",
    """
    [operation]
    type = write_cell
    target.kind = cell
    target.sheet = Summary
    target.row = 1
    target.col = 1
    value = Ready
    value_type = text

    [operation]
    type = format_range
    target.kind = cell
    target.sheet = Summary
    target.row = 1
    target.col = 1
    format.bold = true

    [operation]
    type = recalculate
    """,
    mode="best_effort",
)

print(result.overall_status)

スナップショット

from pathlib import Path
from calc import snapshot_area

result = snapshot_area(doc_path, "/tmp/revenue.png", sheet="Revenue Data", row=0, col=0, dpi=150)
print(result.file_path, result.width, result.height)
Path(result.file_path).unlink(missing_ok=True)   # clean up used snapshots

納品前に、スナップショットを使ってグラフの配置、書式、シートのレイアウトを確認します。

• snapshot_area() の出力サイズは、要求したサイズとわずかに異なる場合があります。数ピクセル程度の差は正常なものとして扱ってください。

よくある間違い

• 相対パスを渡してしまうこと。UNO と連携する Calc API では、絶対ファイルパスが必要です。
• cell と range の対象を混同してしまうこと。Calc では、1 つのセルの選択であっても両者は区別されます。
• 座標を 1 始まりで指定してしまうこと。行と列のインデックスは 0 始まりです。
• create_chart() が後続の任意の名前を対象にすると想定してしまうこと。title が設定されている場合、同じ名前でグラフを指定するのが最も安全な後続処理のパターンです。
• パッケージ化された API には、グラフ一覧の取得や検証内容の確認を行うヘルパーがありません。高度なワークフローでは、より詳細な検証に UNO を直接確認する必要がある場合があります。
• グラフ操作を修正する際に、chart.data_range.* フィールドを忘れてしまうこと。
• snapshot_area() で要求した PNG の寸法が完全に一致すると想定してしまうこと。Calc のエクスポートでは、わずかな差が生じる場合があります。
• 確認後に、取得したスナップショットを削除し忘れること。
• session.close() の後にセッションメソッドを呼び出すこと。
• JSON / XML のインポートには、LibreOffice 26.2+ が必要です。