Python API

Python パッケージは、formulon_capi.wasm にコンパイルされた Formulon C ABI を呼ぶ Python 向けラッパーです。公開 wheel は py3-none-any 形式で、pip が実行環境に合う wasmtime wheel をインストールします。

用語: py3-none-any wheel

Python ABI タグ・プラットフォームタグ・ネイティブコードのいずれも持たない wheel。互換する wasmtime wheel が利用できる CPython 3.9 以降で動作します。プラットフォーム依存部分は wasmtime が担い、formulon 自体には含まれません。

トップレベル API

モジュール関数（formulon.eval_formula、formulon.error_display_name、formulon.merge_function_metadata、formulon.library_version、その別名の formulon.version_string、formulon.set_log_min_level）は、ワークブックのメソッドと一緒に 関数とメソッド に載せています。formulon.__version__ はインストール済みパッケージのバージョンです。set_log_min_level() はプロセス全体に効きます。既定の LogLevel.OFF では何も出力せず、WARN 以下にすると 1 行 1 件の JSON を stderr に書きます。Python にはログの受け取り先を渡すコールバックはありません。主な型は、ワークブックのハンドル Workbook、セル値のレコード Value とその種類を表す enum ValueKind、ホスト側の失敗を表す例外 FormulonError です。

パッケージは、ワークブックのメソッドが使う enum とデータクラスのレコード（Cell、Comment、ConditionalFormat、DataValidation、PaginationResult、PivotLayout、Theme など。一覧は formulon.__all__）も公開します。

分野	enum
値	ErrorCode（NULL = 0、DIV0 = 1、… UNKNOWN = 16）
寸法と表示	GeometryMode（DISPLAY = 0、PRINT = 1）、DisplayStatus（OK = 0、OVERFLOW = 1、INVALID_FORMAT = 2）
AutoFilter	FilterKind、FilterOperator、DynamicFilterType、SortBy、SortMethod、DateTimeGrouping
入力規則	ValidationErrorStyle（STOP = 0、WARNING = 1、INFORMATION = 2）
テーマとスタイル	ColorContext、ColorResolution、ThemeSource、EffectiveStyleSource
画像と描画	ImageFormat、DrawingObjectKind、AnchorKind、AnchorEditAs
ピボットテーブル	PivotAxis、PivotAggregation、PivotShowValuesAs、PivotFilterType、PivotFilterValueKind、PivotDateGrouping、PivotCalendar、PivotReportLayout、PivotCellKind
テキスト照合	CollationStrength（COMPARE = 0、DYNAMIC = 1、CLASSIC_EXACT = 2）
ワークブック状態	CalcMode、SheetVisibility、WorkbookFormat、ExternalLinkKind
ログ	LogLevel（DEBUG = 0、INFO = 1、WARN = 2、ERROR = 3、OFF = 4）

関数カタログは役割ごとに分かれています。Workbook.function_metadata(name) は正規名、引数数、利用可能性などの構造フィールドだけを返し、人間向けのシグネチャと説明は None です。Excel の表示名と数式テキストはプロファイル単位のヘルパーで変換し、説明文の翻訳はホスト側の BCP-47 UI ロケールを指定して merge_function_metadata() に渡してください。

Workbook クラス

from formulon import Workbook

with Workbook.create_default() as wb:
    wb.set_formula(0, 0, 0, "=SUM(1,2,3)")
    wb.recalc()
    print(wb.get_value(0, 0, 0).to_python())

create_default() は Calibri 11 を含む通常の 1 シートワークブックを作成します。create_for_profile(profile_id) は選択したプロファイルを記録し、本文用フォントと必要なロケールのふりがな用フォント、ローカライズされた Normal スタイルと最初のシート名、セル XF の配置、ふりがな設定、ページ余白、Mac の行の高さと基本列幅を設定します。テーマパートは書き出さないため、新しいワークブックは既定の Office テーマとして読み取られます。Windows の行と列の寸法はエンジンの既定値を使います。

プロファイルと数式テキストのヘルパーは、ワークブックに依存しない静的メソッドです。

from formulon import Workbook

profile = "mac-365-de_DE"
shown = Workbook.localize_formula("=SUM(1.5,TRUE)", profile)
stored = Workbook.canonicalize_formula(shown, profile)
facts = Workbook.locale_facts(profile)
print(shown, stored, facts.decimal_separator, facts.true_name)

localize_function_name() / canonicalize_function_name() は 1 つの関数名を変換します。localize_formula() は関数名、リスト / 配列区切り、小数点、真偽値名、エラー名を変換し、文字列、引用符付きシート名、外部修飾子、構造化参照の角括弧を保持します。canonicalize_formula() はこの変換を戻します。これらは数値ロケールコードではなく完全なプロファイル ID を受け取り、数式の検証や登録は行いません。プロファイルは 28 個あり、ロケール情報はすべての mac-* と win-365-ja_JP で Excel の実測値、残り 13 個の Windows プロファイルは推定値です。LocaleFacts.collation_measured は別の項目で、テキスト照合の実測値を持つのは mac-* だけです。

Workbook.compare_text(a, b, strength, profile_id) は -1、0、1 のいずれかを返します。Workbook.collation_classes(values, strength, profile_id) は CollationClasses(class_ids, class_count) を返します。ID は Value ごとに 1 つ、SORT の順序で昇順に振られ、その呼び出しの中だけで意味を持ちます。CollationStrength ごとの比較規則とクラスの規則は テキスト照合 を参照してください。

from formulon import CollationStrength, Value, ValueKind, Workbook

profile = "mac-365-en_US"
order = Workbook.compare_text("a", "b", CollationStrength.COMPARE, profile)
values = [Value(kind=ValueKind.TEXT, text="A"), Value(kind=ValueKind.TEXT, text="a")]
classes = Workbook.collation_classes(values, CollationStrength.DYNAMIC, profile)
print(order, classes.class_ids, classes.class_count)

関数とメソッド

パッケージの type stub（formulon/__init__.pyi）と formulon ソースの docstring から生成した一覧です。formulon. で始まる名前はモジュール関数、Workbook. で始まる名前はクラスメソッドまたは静的メソッドで、それ以外はすべて Workbook インスタンスのメソッドです。is_valid はプロパティです。= ... は stub と同じく既定値のある引数を表します。説明列は docstring の最初の 1 文で、API 自身の英語のテキストをそのまま載せています。Workbook はコンテキストマネージャーでもあり、with ブロックを抜けると close() が呼ばれます。

参照元

この一覧は、ドキュメント対象 0.18.0 のコアソースから生成しています。取得元のコミットを固定し、WASM・Python・C の宣言を同じリビジョンで照合しています。デモは公開済みパッケージを使い、実行バージョンを別に表示します。

ライブラリ、診断、ログ

名前	シグネチャ	説明
formulon.library_version	library_version() -> str	Return the version string baked into the loaded WASM module.
formulon.version_string	version_string() -> str	Alias of library_version().
formulon.error_display_name	error_display_name(error_code: int) -> str	Return an Excel literal such as "#DIV/0!" for an error code.
formulon.set_log_min_level	set_log_min_level(level: Union[LogLevel, int]) -> None	Set the engine's minimum structured-log severity.

ワークブックのライフサイクルと入出力

名前	シグネチャ	説明
Workbook.create_default	create_default() -> Workbook	Build a default workbook (a single sheet named Sheet1).
Workbook.create_for_profile	create_for_profile(profile_id: str) -> Workbook	Build a new workbook with the defaults of an Excel profile.
Workbook.create_empty	create_empty() -> Workbook	Build an empty workbook (no sheets).
Workbook.load	load(data: Union[bytes, bytearray, memoryview]) -> Workbook	Load a workbook from an in-memory byte buffer.
close	close() -> None	Release the underlying handle.
is_valid	is_valid: bool	True while the handle is still alive.
memory_usage	memory_usage() -> int	Return an estimate of the workbook's heap footprint, in bytes.
save	save() -> bytes	Serialise the workbook to an in-memory .xlsx byte stream.
save_as	save_as(fmt: Union[WorkbookFormat, int]) -> bytes	Serialise the workbook to an in-memory byte stream in fmt.
save_with_diagnostics	save_with_diagnostics(fmt: Union[WorkbookFormat, int]) -> SaveDiagnostics	Serialise the workbook and return what the save cost.
read_diagnostics	read_diagnostics() -> ReadDiagnostics	Return the loss counters captured when this workbook was loaded.
iter_passthrough	iter_passthrough() -> Iterator[PassthroughPart]	Iterate over passthrough OOXML part paths.

シートと構造

名前	シグネチャ	説明
sheet_count	sheet_count() -> int	Number of sheets in the workbook.
active_sheet	active_sheet() -> int	Index of the active sheet (activeTab of the first workbook view).
set_active_sheet	set_active_sheet(index: int) -> None	Mark the sheet at index active so save records it.
sheet_name	sheet_name(index: int) -> str	Display name (UTF-8) of the sheet at index.
add_sheet	add_sheet(name: str) -> None	Append a new sheet with the given UTF-8 display name.
move_sheet	move_sheet(from_index: int, to_index: int) -> None	Move the sheet at from_index to to_index (post-removal).
remove_sheet	remove_sheet(index: int) -> None	Remove the sheet at index.
rename_sheet	rename_sheet(index: int, new_name: str) -> None	Rename the sheet at index to new_name.
insert_rows	insert_rows(sheet: int, row: int, count: int) -> None	Insert count rows at row on sheet.
delete_rows	delete_rows(sheet: int, row: int, count: int) -> None	Delete count rows starting at row on sheet.
insert_cols	insert_cols(sheet: int, col: int, count: int) -> None	Insert count columns at col on sheet.
delete_cols	delete_cols(sheet: int, col: int, count: int) -> None	Delete count columns starting at col on sheet.

セル

名前	シグネチャ	説明
set_number	set_number(sheet: int, row: int, col: int, value: float) -> None	Store the number value at (sheet, row, col).
set_bool	set_bool(sheet: int, row: int, col: int, value: bool) -> None	Store the boolean value at (sheet, row, col).
set_error	set_error(sheet: int, row: int, col: int, error_code: int) -> None	Store an Excel cell error at (sheet, row, col).
set_text	set_text(sheet: int, row: int, col: int, value: str) -> None	Store the string value at (sheet, row, col).
set_blank	set_blank(sheet: int, row: int, col: int) -> None	Clear the cell at (sheet, row, col).
set_formula	set_formula(sheet: int, row: int, col: int, formula: str) -> None	Store the formula formula at (sheet, row, col).
set_phonetic	set_phonetic(sheet: int, row: int, col: int, text: str) -> None	Set the cell's phonetic guide (OOXML <rPh>, furigana).
set_phonetic_runs	set_phonetic_runs(sheet: int, row: int, col: int, runs: Sequence[PhoneticRun]) -> None	Set the cell's phonetic guide as one <rPh> block per run.
get_phonetic	get_phonetic(sheet: int, row: int, col: int) -> str	Return the cell's phonetic guide, or "" when it has none.
get_phonetic_runs	get_phonetic_runs(sheet: int, row: int, col: int) -> List[PhoneticRun]	Return the cell's <rPh> blocks, spans included.
set_phonetic_properties	set_phonetic_properties(sheet: int, row: int, col: int, properties: PhoneticProperties) -> None	Set how the cell's phonetic guide renders.
get_phonetic_properties	get_phonetic_properties(sheet: int, row: int, col: int) -> PhoneticProperties	Return how the cell's phonetic guide renders.
has_phonetic_properties	has_phonetic_properties(sheet: int, row: int, col: int) -> bool	Whether the cell's phonetic properties are explicit.
get_value	get_value(sheet: int, row: int, col: int) -> Value	Read the cached value at (sheet, row, col).
lambda_text_at	lambda_text_at(sheet: int, row: int, col: int) -> str	Render the lambda cached at (sheet, row, col) as text.
iter_cells	iter_cells(sheet: int) -> Iterator[Cell]	Iterate over every written coordinate on sheet.
get_formula	get_formula(sheet: int, row: int, col: int) -> Optional[str]	Return the stored A1 formula (leading = included), or None for a non-formula cell.
get_formula_r1c1	get_formula_r1c1(sheet: int, row: int, col: int) -> Optional[str]	Return the formula in R1C1 notation relative to the cell, or None for a non-formula cell.
get_cells_in_range	get_cells_in_range(sheet: int, cell_range: MergeRange, cursor: Optional[int] = ..., limit: Optional[int] = ...) -> Tuple[List[Cell], Optional[int]]	Return one page of the populated cells in cell_range (row-major).

再計算

名前	シグネチャ	説明
recalc	recalc() -> None	Drive a full incremental recalc.
set_iterative	set_iterative(enabled: bool, max_iterations: int, max_change: float) -> None	Configure iterative calculation.
set_iterative_enabled	set_iterative_enabled(enabled: bool) -> None	Toggle iterative calculation, keeping the cap and threshold.
get_iterative	get_iterative() -> IterativeSettings	Read back the iterative-calculation settings.
partial_recalc	partial_recalc(sheet: int, first_row: int, last_row: int, first_col: int, last_col: int) -> int	Recalc the dependency closure for a viewport; return cell count.
calc_mode	calc_mode() -> CalcMode	Return the workbook's calc mode (round-trip metadata).
full_precision	full_precision() -> bool	Return <calcPr fullPrecision>; false is "set precision as displayed" (metadata only).
set_full_precision	set_full_precision(full_precision: bool) -> None	Set <calcPr fullPrecision>.
calc_on_save	calc_on_save() -> bool	Return <calcPr calcOnSave> (default true).
set_calc_on_save	set_calc_on_save(calc_on_save: bool) -> None	Set <calcPr calcOnSave>.
ref_mode	ref_mode() -> RefMode	Return <calcPr refMode>: the reference notation formulas are shown in.
set_ref_mode	set_ref_mode(mode: Union[RefMode, int]) -> None	Set <calcPr refMode>.
date1904	date1904() -> bool	Return whether the workbook uses the 1904 date system.
set_date1904	set_date1904(date1904: bool) -> None	Switch the date system.
set_calc_mode	set_calc_mode(mode: Union[CalcMode, int]) -> None	Set the workbook's calc mode.
pinned_now	pinned_now() -> Optional[CivilTime]	Return the pinned wall-clock reading, or None when the
set_pinned_now	set_pinned_now(year: int, month: int, day: int, hour: int = ..., minute: int = ..., second: int = ...) -> None	Pin every clock-dependent result to one instant.
clear_pinned_now	clear_pinned_now() -> None	Release the pin so clock-dependent results follow the host clock
add_data_table	add_data_table(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int, *, row_input: Optional[Tuple[int, int]] = ..., col_input: Optional[Tuple[int, int]] = ...) -> None	Create a data table whose result range is first_row..last_col (0-based, inclusive).
get_data_table	get_data_table(sheet: int, row: int, col: int) -> Optional[DataTable]	Return the data table whose result range contains (row, col), or None.
remove_data_table	remove_data_table(sheet: int, row: int, col: int) -> None	Remove the data table containing (row, col) and blank its result cells.
recalc_data_tables	recalc_data_tables() -> None	Recompute every data table now, whatever the calc mode (the explicit calculation of AUTO_NO_TABLE).

読み取り専用の評価

名前	シグネチャ	説明
evaluate_formula_array	evaluate_formula_array(sheet: int, row: int, col: int, formula: str) -> List[List[Value]]	Evaluate formula as if entered at (sheet, row, col) and
evaluate_cf_formula	evaluate_cf_formula(sheet: int, row: int, col: int, anchor_row: int, anchor_col: int, formula: str) -> bool	Evaluate a conditional-format formula at one cell without mutation.
formulon.eval_formula	eval_formula(formula: str) -> Value	Evaluate a single formula against a fresh, default workbook.

プロファイル、ロケール、テキスト

名前	シグネチャ	説明
formulon.merge_function_metadata	merge_function_metadata(base: FunctionMetadata, entry: Optional[Mapping[str, object]], locale: str) -> Union[FunctionMetadata, MergedFunctionMetadata]	Merge a host-supplied entry over the engine result base.
excel_profile_id	excel_profile_id() -> ExcelProfileId	Return the active Excel formula profile id.
set_excel_profile_id	set_excel_profile_id(profile_id: ExcelProfileId) -> None	Set the workbook's Excel formula profile by id.
Workbook.function_count	function_count() -> int	Return the total number of registered Formulon functions.
Workbook.function_name_at	function_name_at(index: int) -> str	Return the canonical name of the index-th function.
Workbook.function_metadata	function_metadata(name: str) -> Optional[FunctionMetadata]	Return metadata for name or None when unknown.
Workbook.localize_function_name	localize_function_name(canonical_name: str, profile_id: ExcelProfileId) -> str	Return the display name of canonical_name under profile_id.
Workbook.canonicalize_function_name	canonicalize_function_name(localized_name: str, profile_id: ExcelProfileId) -> str	Return the canonical English name for localized_name under profile_id.
Workbook.localize_formula	localize_formula(formula: str, profile_id: ExcelProfileId) -> str	Rewrite stored (en-invariant) formula text into profile_id's spelling.
Workbook.canonicalize_formula	canonicalize_formula(formula: str, profile_id: ExcelProfileId) -> str	Rewrite profile_id-spelled formula text into the en-invariant form.
Workbook.locale_facts	locale_facts(profile_id: ExcelProfileId) -> LocaleFacts	Return the locale facts (separators, names, currency, error names) of profile_id.
Workbook.compare_text	compare_text(a: str, b: str, strength: CollationStrength, profile_id: ExcelProfileId) -> int	Compare two texts under the collation of profile_id.
Workbook.collation_classes	collation_classes(values: Sequence[Value], strength: CollationStrength, profile_id: ExcelProfileId) -> CollationClasses	Classify values into collation-ordered equivalence classes.

定義名

名前	シグネチャ	説明
set_defined_name	set_defined_name(name: str, formula: str) -> None	Set, append, or remove a workbook-scoped defined name.
set_defined_name_scoped	set_defined_name_scoped(name: str, formula: str, local_sheet_id: int) -> None	Set, append, or remove a defined name in workbook or sheet scope.
set_defined_name_attrs	set_defined_name_attrs(name: str, local_sheet_id: int = ..., *, comment: Optional[str] = ..., hidden: Optional[bool] = ...) -> None	Set the comment and / or hidden attribute of an existing defined name.
iter_defined_names	iter_defined_names() -> Iterator[DefinedName]	Iterate over every defined name in declaration order.

テーブル

名前	シグネチャ	説明
iter_tables	iter_tables() -> Iterator[Table]	Iterate over every table in declaration order.
table_create	table_create(sheet: int, ref: str, name: str, display_name: str, column_names: Sequence[str], style_name: str = ..., header_row: bool = ..., totals_row: bool = ..., *, show_first_column: Optional[bool] = ..., show_last_column: Optional[bool] = ..., show_row_stripes: Optional[bool] = ..., show_column_stripes: Optional[bool] = ...) -> int	Create a worksheet table and return its index.
table_set_style_info	table_set_style_info(index: int, style_name: Optional[str], show_first_column: bool = ..., show_last_column: bool = ..., show_row_stripes: bool = ..., show_column_stripes: bool = ...) -> None	Set the table's style name and toggles, making the style element present.
table_rename	table_rename(index: int, name: str, display_name: Optional[str] = ...) -> None	Rename table index; display_name=None uses name for both.
table_set_column_totals	table_set_column_totals(index: int, column: int, function: Optional[str] = ..., label: Optional[str] = ..., formula: Optional[str] = ...) -> None	Set column column's totals-row function and label.
table_update	table_update(index: int, ref: str, style_name: Optional[str] = ..., header_row: Optional[bool] = ..., totals_row: Optional[bool] = ..., *, name: Optional[str] = ..., display_name: Optional[str] = ..., show_first_column: Optional[bool] = ..., show_last_column: Optional[bool] = ..., show_row_stripes: Optional[bool] = ..., show_column_stripes: Optional[bool] = ...) -> None	Replace a table's range and optional visual style.
table_remove	table_remove(index: int) -> None	Remove the table at index.
table_style_count	table_style_count() -> int	Return the number of custom table / PivotTable styles.
get_table_style	get_table_style(index: int) -> TableStyle	Return the custom table style at index.
set_table_style	set_table_style(style: TableStyle) -> None	Add a custom table style, or replace the one with the same name.
remove_table_style	remove_table_style(name: str) -> None	Remove the custom table style name.
table_style_defaults	table_style_defaults() -> Tuple[str, str]	Return the default (table_style, pivot_style) names; empty when unset.
set_table_style_defaults	set_table_style_defaults(table_style: Optional[str] = ..., pivot_style: Optional[str] = ...) -> None	Set the default style names; None keeps one, "" removes it.

依存関係、スピル、外部リンク

名前	シグネチャ	説明
precedents	precedents(sheet: int, row: int, col: int, depth: int = ...) -> List[CellNode]	Return the cells (sheet, row, col) reads (up to depth).
dependents	dependents(sheet: int, row: int, col: int, depth: int = ...) -> List[CellNode]	Return the cells that read (sheet, row, col) (up to depth).
spill_info	spill_info(sheet: int, row: int, col: int) -> SpillInfo	Return dynamic-array spill info for (sheet, row, col).
external_link_count	external_link_count() -> int	Return the number of external-link records on the workbook.
get_external_link_at	get_external_link_at(index: int) -> ExternalLink	Read the index-th external-link record.
get_external_links	get_external_links() -> List[ExternalLink]	Return every external-link record in document order.

シートの表示と保護

名前	シグネチャ	説明
get_show_phonetic	get_show_phonetic(sheet: int, row: int, col: int) -> bool	Whether the cell shows its phonetic guide (<c ph="1">).
set_show_phonetic	set_show_phonetic(sheet: int, row: int, col: int, show: bool) -> None	Set the cell's "Show Phonetic" display flag.
get_workbook_protection	get_workbook_protection() -> WorkbookProtection	Read the workbook's <workbookProtection>; every field is false, empty or zero when absent.
set_workbook_protection	set_workbook_protection(protection: WorkbookProtection) -> None	Replace the modelled <workbookProtection> attributes; an all-empty record removes the element.
protected_range_count	protected_range_count(sheet: int) -> int	Return the number of protected ranges on sheet.
get_protected_ranges	get_protected_ranges(sheet: int) -> List[ProtectedRange]	Return the protected ranges of sheet in file order.
add_protected_range	add_protected_range(sheet: int, protected: ProtectedRange) -> None	Append a protected range; name must be non-empty and unique on the sheet.
update_protected_range	update_protected_range(sheet: int, index: int, protected: ProtectedRange) -> None	Replace the index-th protected range of sheet.
remove_protected_range	remove_protected_range(sheet: int, index: int) -> None	Remove the index-th protected range of sheet.
get_sheet_protection	get_sheet_protection(sheet: int) -> SheetProtection	Read the sheet's <sheetProtection> flags.
set_sheet_protection	set_sheet_protection(sheet: int, protection: SheetProtection) -> None	Replace the sheet's <sheetProtection> flags wholesale.
get_sheet_view	get_sheet_view(sheet: int) -> SheetView	Read the full per-sheet view (zoom, freeze, tab-hidden, and the
set_sheet_zoom	set_sheet_zoom(sheet: int, zoom_scale: int) -> None	Set the sheet zoom percentage (clamped to [10, 400]).
set_sheet_freeze	set_sheet_freeze(sheet: int, freeze_rows: int, freeze_cols: int) -> None	Set the frozen pane in (rows, cols).
set_sheet_tab_hidden	set_sheet_tab_hidden(sheet: int, hidden: bool) -> None	Set the sheet tab's hidden flag.
set_sheet_visibility	set_sheet_visibility(sheet: int, visibility: Union[SheetVisibility, int]) -> None	Set the sheet tab's visibility to one of the three states.
set_sheet_show_grid_lines	set_sheet_show_grid_lines(sheet: int, show: bool) -> None	Set the sheet's showGridLines flag.
set_sheet_show_row_col_headers	set_sheet_show_row_col_headers(sheet: int, show: bool) -> None	Set the sheet's showRowColHeaders flag.
set_sheet_show_zeros	set_sheet_show_zeros(sheet: int, show: bool) -> None	Set the sheet's showZeros flag.
set_sheet_show_formulas	set_sheet_show_formulas(sheet: int, show: bool) -> None	Set the sheet's showFormulas flag.
set_sheet_show_outline_symbols	set_sheet_show_outline_symbols(sheet: int, show: bool) -> None	Set the sheet's showOutlineSymbols flag.
set_sheet_right_to_left	set_sheet_right_to_left(sheet: int, right_to_left: bool) -> None	Set the sheet's rightToLeft flag.
set_sheet_tab_selected	set_sheet_tab_selected(sheet: int, selected: bool) -> None	Set the sheet's tabSelected flag.
set_sheet_top_left	set_sheet_top_left(sheet: int, row: int, col: int) -> None	Set the sheet view's scroll origin (topLeftCell).
set_sheet_pane_top_left	set_sheet_pane_top_left(sheet: int, row: int, col: int) -> None	Set the first visible cell of a frozen or split view's lower-right pane.
set_sheet_split	set_sheet_split(sheet: int, x_twips: float, y_twips: float) -> None	Split the view at x_twips / y_twips (0 for none on that axis).
get_sheet_selection	get_sheet_selection(sheet: int) -> Tuple[Tuple[int, int], List[MergeRange]]	Return ((active_row, active_col), ranges) of the active pane's selection.
set_sheet_selection	set_sheet_selection(sheet: int, active_row: int, active_col: int, ranges: Sequence[MergeRange] = ...) -> None	Replace the active pane's selection; no ranges selects the active cell alone.
set_sheet_view_mode	set_sheet_view_mode(sheet: int, mode: str) -> None	Set the sheet's <sheetView view="..."> mode: "",

行、列、ジオメトリ

名前	シグネチャ	説明
get_sheet_columns	get_sheet_columns(sheet: int) -> List[ColumnLayout]	Return the column-layout overrides on sheet.
set_column_width	set_column_width(sheet: int, first: int, last: int, width: float) -> None	Set the column width override on [first, last].
set_column_hidden	set_column_hidden(sheet: int, first: int, last: int, hidden: bool) -> None	Set the column hidden flag on [first, last].
set_column_outline	set_column_outline(sheet: int, first: int, last: int, level: int) -> None	Set the column outline level (0-7) on [first, last].
set_column_collapsed	set_column_collapsed(sheet: int, first: int, last: int, collapsed: bool) -> None	Set or clear the collapsed flag on the columns [first, last].
get_sheet_row_overrides	get_sheet_row_overrides(sheet: int) -> List[RowLayout]	Return the row-layout overrides on sheet.
set_row_height	set_row_height(sheet: int, row: int, height: float) -> None	Set the row height override at row.
clear_row_height	clear_row_height(sheet: int, row: int) -> None	Remove the height override at row (back to the sheet default).
set_column_style	set_column_style(sheet: int, first: int, last: int, xf_index: int) -> None	Set the cell-style XF on [first, last], keeping the other column attributes.
clear_column_style	clear_column_style(sheet: int, first: int, last: int) -> None	Remove the cell-style XF on [first, last], keeping the other column attributes.
set_row_style	set_row_style(sheet: int, first: int, last: int, xf_index: int) -> None	Set the cell-style XF on the inclusive row span first..last, keeping the other row attributes.
clear_row_style	clear_row_style(sheet: int, first: int, last: int) -> None	Remove the cell-style XF on the inclusive row span first..last, keeping the other row attributes.
clear_column_width	clear_column_width(sheet: int, first: int, last: int) -> None	Remove the width override on [first, last] (back to the sheet default).
get_sheet_format_defaults	get_sheet_format_defaults(sheet: int) -> SheetFormatDefaults	Read the sheet's default column / row metrics (<sheetFormatPr>).
set_sheet_format_defaults	set_sheet_format_defaults(sheet: int, defaults: SheetFormatDefaults) -> None	Replace the sheet's default column / row metrics; a None flag keeps the stored one.
get_cell_rect_pt	get_cell_rect_pt(sheet: int, cell_range: MergeRange, mode: Union[GeometryMode, int] = ...) -> RectPt	Return the rectangle covering cell_range in points from the top-left of A1.
get_column_width_pt	get_column_width_pt(sheet: int, col: int, mode: Union[GeometryMode, int] = ...) -> float	Return the effective width of col in points (0 when hidden).
get_row_height_pt	get_row_height_pt(sheet: int, row: int) -> float	Return the effective height of row in points (0 when hidden).
get_width_model	get_width_model(sheet: int, mode: Union[GeometryMode, int] = ...) -> WidthModel	Return the character-unit to point conversion model in mode.
column_chars_to_pt	column_chars_to_pt(sheet: int, chars: float, mode: Union[GeometryMode, int] = ...) -> float	Convert a stored column width (padding included) to points, snapped to whole screen pixels.
column_pt_to_chars	column_pt_to_chars(sheet: int, pt: float, mode: Union[GeometryMode, int] = ...) -> float	Convert points to the stored column width Excel writes for that column.
set_row_hidden	set_row_hidden(sheet: int, row: int, hidden: bool) -> None	Set the row hidden flag at row.
set_row_outline	set_row_outline(sheet: int, row: int, level: int) -> None	Set the row outline level (0-7) at row.
set_row_collapsed	set_row_collapsed(sheet: int, row: int, collapsed: bool) -> None	Set or clear the collapsed flag at row.

表示テキスト

名前	シグネチャ	説明
get_display_text	get_display_text(sheet: int, row: int, col: int) -> Tuple[str, DisplayStatus]	Return the text Excel displays for the cell and the rendering outcome.
format_value	format_value(value: Value, format_code: str = ...) -> Tuple[str, DisplayStatus]	Render value under the number format format_code (empty means General).

スタイル

名前	シグネチャ	説明
range_style_bases	range_style_bases(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int) -> List[int]	List, ascending, every cell XF some cell of the selection resolves to.
remap_range_style	remap_range_style(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int, mapping: Dict[int, int]) -> None	Remap the XFs of a selection: a cell resolving to key k ends at mapping[k].
snapshot_range_style	snapshot_range_style(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int) -> bytes	Capture the style state of a selection as opaque bytes for restore_range_style.
restore_range_style	restore_range_style(sheet: int, data: Union[bytes, bytearray, memoryview]) -> None	Put a snapshot_range_style capture back on sheet.
get_cell_xf_index	get_cell_xf_index(sheet: int, row: int, col: int) -> int	Return the xf (style record) index attached to a cell.
set_cell_xf_index	set_cell_xf_index(sheet: int, row: int, col: int, xf_index: int) -> None	Store xf_index on the cell at (row, col).
clear_cell_xf_index	clear_cell_xf_index(sheet: int, row: int, col: int) -> None	Remove the direct style assignment from the cell at (row, col).
set_range_xf_index	set_range_xf_index(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int, xf_index: int) -> None	Store xf_index on every cell in the inclusive rectangle.
get_cell_xf	get_cell_xf(xf_index: int) -> CellXf	Return the resolved <xf> record at xf_index.
get_font	get_font(font_index: int) -> FontRecord	Return the font record at font_index.
get_fill	get_fill(fill_index: int) -> FillRecord	Return the fill record at fill_index.
get_border	get_border(border_index: int) -> Dict[str, object]	Return the border record at border_index.
get_dxf	get_dxf(dxf_index: int) -> DifferentialFormat	Read one differential format by its conditional-format dxfId.
get_num_fmt	get_num_fmt(num_fmt_id: int) -> str	Return the format code registered for num_fmt_id.
font_count	font_count() -> int	Return the number of font records registered.
fill_count	fill_count() -> int	Return the number of fill records registered.
border_count	border_count() -> int	Return the number of border records registered.
cell_xf_count	cell_xf_count() -> int	Return the number of <xf> records registered.
cell_style_count	cell_style_count() -> int	Return the number of named cell styles.
cell_style_xf_count	cell_style_xf_count() -> int	Return the number of <cellStyleXfs> records.
dxf_count	dxf_count() -> int	Return the number of differential formats available to CF rules.
add_font	add_font(record: FontRecord) -> int	Add (dedup) a font record; return its index.
set_font	set_font(font_index: int, record: FontRecord) -> None	Overwrite an existing font slot in place.
set_default_font	set_default_font(record: FontRecord) -> None	Declare the workbook's default font (font 0).
add_fill	add_fill(record: FillRecord) -> int	Add (dedup) a fill record; return its index.
add_border	add_border(sides: Dict[str, object]) -> int	Add (dedup) a border record; return its index.
add_num_fmt	add_num_fmt(format_code: str) -> int	Add (dedup) a number-format code; return its resolved id.
add_cell_xf	add_cell_xf(record: CellXf) -> int	Add (dedup) an <xf> record; return its index.
add_cell_style_xf	add_cell_style_xf(record: CellXf) -> int	Add (dedup) a named-style <xf>; return its <cellStyleXfs> id.
add_batch	add_batch(*, fonts: Optional[Sequence[FontRecord]] = ..., fills: Optional[Sequence[FillRecord]] = ..., borders: Optional[Sequence[Dict[str, object]]] = ..., num_fmts: Optional[Sequence[str]] = ..., cell_xfs: Optional[Sequence[CellXf]] = ...) -> StyleBatchIndices	Add (dedup) whole style tables in one call.
add_dxf	add_dxf(record: DifferentialFormat) -> int	Add (dedup) a differential format and return its dxfId.
set_cell_style	set_cell_style(record: CellStyle) -> None	Add or replace the named <cellStyle> record record.name.
remove_cell_style	remove_cell_style(name: str) -> None	Remove the named cell style name.
get_effective_style	get_effective_style(sheet: int, row: int, col: int) -> EffectiveStyle	Read the effective style of the cell at (row, col); the cell need not exist.
get_cell_style	get_cell_style(index: int) -> CellStyle	Return the named cell style at index.
get_cell_style_xf	get_cell_style_xf(index: int) -> CellXf	Return the named-style xf record at index.

テーマと色

名前	シグネチャ	説明
get_theme	get_theme() -> Theme	Read the theme's 12 scheme colours and typefaces.
set_theme_colors	set_theme_colors(colors: Sequence[int]) -> None	Replace the theme's 12 scheme colours (a:clrScheme order; alpha ignored).
set_theme_fonts	set_theme_fonts(fonts: ThemeFonts) -> None	Replace the theme's major and minor typefaces.
set_theme_script_font	set_theme_script_font(major: bool, script: str, typeface: str) -> None	Set the typeface of one script in the major (heading) or minor (body) font set.
reset_theme	reset_theme() -> None	Remove the theme part so the workbook reports the default theme.
resolve_color	resolve_color(spec: ColorSpec, context: Union[ColorContext, int] = ...) -> ResolvedColor	Resolve spec to the 0xAARRGGBB Excel renders.

セルの結合

名前	シグネチャ	説明
add_merge	add_merge(sheet: int, merge: MergeRange) -> None	Append a merge range to sheet.
remove_merge	remove_merge(sheet: int, merge: MergeRange) -> None	Remove every merge on sheet overlapping merge.
remove_merge_at	remove_merge_at(sheet: int, index: int) -> None	Remove the merge at index on sheet.
clear_merges	clear_merges(sheet: int) -> None	Drop every merge range on sheet.
merge_count	merge_count(sheet: int) -> int	Return the number of merge ranges on sheet.
get_merges	get_merges(sheet: int) -> List[MergeRange]	Return every merge range on sheet.
get_merges_in_range	get_merges_in_range(sheet: int, cell_range: MergeRange) -> List[MergeRange]	Return every merge range on sheet that intersects cell_range.

コメントとハイパーリンク

名前	シグネチャ	説明
add_hyperlink	add_hyperlink(sheet: int, row: int, col: int, target: str, display: str = ..., tooltip: str = ..., location: str = ...) -> None	Append a hyperlink to sheet.
add_hyperlink_range	add_hyperlink_range(sheet: int, row: int, col: int, last_row: int, last_col: int, target: str, display: str = ..., tooltip: str = ..., location: str = ...) -> None	Append a hyperlink covering the inclusive cell rectangle.
remove_hyperlink	remove_hyperlink(sheet: int, row: int, col: int) -> None	Remove every hyperlink anchored at (row, col) on sheet.
remove_hyperlink_at	remove_hyperlink_at(sheet: int, index: int) -> None	Remove the hyperlink at index on sheet.
clear_hyperlinks	clear_hyperlinks(sheet: int) -> None	Drop every hyperlink on sheet.
hyperlink_count	hyperlink_count(sheet: int) -> int	Return the number of hyperlinks on sheet.
get_hyperlinks	get_hyperlinks(sheet: int) -> List[Hyperlink]	Return every hyperlink on sheet.
get_comment	get_comment(sheet: int, row: int, col: int) -> Optional[Comment]	Return the comment at (sheet, row, col) or None if absent.
set_comment	set_comment(sheet: int, row: int, col: int, author: str, text: str) -> None	Set, replace, or (empty text) remove a cell comment.
get_comment_visible	get_comment_visible(sheet: int, row: int, col: int) -> Optional[bool]	Return whether the note at the cell is shown without hovering, or None if absent.
set_comment_visible	set_comment_visible(sheet: int, row: int, col: int, visible: bool) -> None	Show or hide the note at the cell; its box geometry is kept.
comment_count	comment_count(sheet: int) -> int	Return the number of comments on sheet.
get_comments	get_comments(sheet: int) -> List[CommentEntry]	Return every comment on sheet in storage order.

スレッド形式のコメントと人物

名前	シグネチャ	説明
get_threaded_comments	get_threaded_comments(sheet: int) -> List[ThreadedComment]	Return the sheet's threaded comments in file order (openers followed by their replies).
add_threaded_comment	add_threaded_comment(sheet: int, comment: ThreadedComment) -> None	Add a threaded comment: a new thread when parent_id is empty, else a reply.
edit_threaded_comment	edit_threaded_comment(sheet: int, comment_id: str, text: str, mentions: Sequence[Mention] = ...) -> None	Replace the text and mentions of the comment comment_id.
set_thread_resolved	set_thread_resolved(sheet: int, thread_id: str, done: bool) -> None	Set the resolved state of the thread opened by thread_id.
remove_threaded_comment	remove_threaded_comment(sheet: int, comment_id: str) -> None	Remove the comment comment_id; removing a thread opener removes its whole thread.
get_persons	get_persons() -> List[Person]	Return the workbook's person list in file order.
add_person	add_person(person: Person) -> None	Append a person to the workbook's person list.
remove_person	remove_person(person_id: str) -> None	Remove the person person_id (refused while a comment or mention still names them).

オートフィルター

名前	シグネチャ	説明
get_auto_filter_xml	get_auto_filter_xml(sheet: int) -> str	Return the sheet's <autoFilter> XML fragment, or "".
set_auto_filter_xml	set_auto_filter_xml(sheet: int, xml: str) -> None	Replace the sheet's <autoFilter> XML fragment.
get_auto_filter	get_auto_filter(sheet: int) -> Optional[AutoFilter]	Return the sheet AutoFilter, or None when the sheet has none.
set_auto_filter	set_auto_filter(sheet: int, auto_filter: AutoFilter) -> None	Replace the sheet AutoFilter.
remove_auto_filter	remove_auto_filter(sheet: int) -> None	Remove the sheet AutoFilter (no-op when absent).
apply_auto_filter	apply_auto_filter(sheet: int) -> None	Hide the body rows the sheet AutoFilter excludes and show the rest.
clear_auto_filter	clear_auto_filter(sheet: int) -> None	Drop every column criterion of the sheet AutoFilter and show all its body rows.
evaluate_auto_filter	evaluate_auto_filter(sheet: int) -> Tuple[int, List[bool]]	Evaluate the sheet AutoFilter without changing the sheet.
get_table_auto_filter	get_table_auto_filter(table_index: int) -> Optional[AutoFilter]	Return the AutoFilter of table table_index, or None when it has none.
set_table_auto_filter	set_table_auto_filter(table_index: int, auto_filter: AutoFilter) -> None	Replace the AutoFilter of table table_index.
remove_table_auto_filter	remove_table_auto_filter(table_index: int) -> None	Remove the AutoFilter of table table_index (no-op when absent).
apply_table_auto_filter	apply_table_auto_filter(table_index: int) -> None	Hide the body rows the table AutoFilter excludes and show the rest.
clear_table_auto_filter	clear_table_auto_filter(table_index: int) -> None	Drop every column criterion of the table AutoFilter and show all its body rows.
evaluate_table_auto_filter	evaluate_table_auto_filter(table_index: int) -> Tuple[int, List[bool]]	Evaluate the table AutoFilter; returns (first_row, match) as evaluate_auto_filter.

データの入力規則

名前	シグネチャ	説明
validation_count	validation_count(sheet: int) -> int	Return the number of data-validation rules on sheet.
get_validation_at	get_validation_at(sheet: int, index: int) -> DataValidation	Read the index-th data-validation rule on sheet.
get_validations	get_validations(sheet: int) -> List[DataValidation]	Return every data-validation rule on sheet.
add_validation	add_validation(sheet: int, validation: DataValidationInput) -> None	Append a data-validation rule to sheet.
remove_validation_at	remove_validation_at(sheet: int, index: int) -> None	Remove the validation rule at index on sheet.
clear_validations	clear_validations(sheet: int) -> None	Drop every validation rule on sheet.
validate_value	validate_value(sheet: int, row: int, col: int, value: Value) -> ValidationOutcome	Check value against the data-validation rule covering (row, col) without storing it.
list_invalid_cells	list_invalid_cells(sheet: int, cursor: Optional[int] = ..., limit: Optional[int] = ...) -> Tuple[List[Cell], Optional[int]]	Return one page of the populated cells failing their data-validation rule (row-major).

条件付き書式

名前	シグネチャ	説明
evaluate_cf_range	evaluate_cf_range(sheet: int, first_row: int, first_col: int, last_row: int, last_col: int, today_serial: float = ...) -> List[CfCellResult]	Evaluate every CF block on sheet against an inclusive range.
cf_count	cf_count(sheet: int) -> int	Return the number of CF rules on sheet (flattened).
get_conditional_format_at	get_conditional_format_at(sheet: int, index: int) -> ConditionalFormat	Read the index-th CF rule on sheet (flattened order).
get_conditional_formats	get_conditional_formats(sheet: int) -> List[ConditionalFormat]	Return every CF rule on sheet in flattened priority order.
add_conditional_format	add_conditional_format(sheet: int, rule: ConditionalFormatInput) -> int	Append a CF rule to sheet; return its index.
remove_conditional_format_at	remove_conditional_format_at(sheet: int, index: int) -> None	Remove the CF rule at index on sheet (flattened order).
clear_conditional_formats	clear_conditional_formats(sheet: int) -> None	Drop every CF block on sheet.

画像と描画オブジェクト

名前	シグネチャ	説明
probe_image	probe_image(data: Union[bytes, bytearray, memoryview]) -> ImageInfo	Sniff the format and pixel size of PNG, JPEG, GIF or BMP bytes without touching the workbook.
list_drawing_objects	list_drawing_objects(sheet: int) -> List[DrawingObject]	Return the anchored objects of the sheet's drawing in document order.
get_image	get_image(sheet: int, object_id: int) -> bytes	Return the bytes of the picture object_id (copied out of WASM memory).
insert_image	insert_image(sheet: int, data: Union[bytes, bytearray, memoryview], *, name: str = ..., descr: str = ..., anchor_kind: Union[AnchorKind, int] = ..., edit_as: Union[AnchorEditAs, int] = ..., row: int = ..., col: int = ..., row_off_emu: int = ..., col_off_emu: int = ..., width_emu: int = ..., height_emu: int = ...) -> int	Insert an image anchored at (row, col) and return its object id.
remove_drawing	remove_drawing(sheet: int, object_id: int) -> None	Remove the picture or chart object_id and the parts only it reaches; other drawing content is kept.
set_drawing_anchor	set_drawing_anchor(sheet: int, object_id: int, *, anchor_kind: Union[AnchorKind, int] = ..., edit_as: Union[AnchorEditAs, int] = ..., row: int = ..., col: int = ..., row_off_emu: int = ..., col_off_emu: int = ..., width_emu: int = ..., height_emu: int = ...) -> None	Move and resize the picture or chart object_id, keeping its id and every other element.
set_drawing_z_order	set_drawing_z_order(sheet: int, object_id: int, index: int) -> None	Make the picture or chart object_id item index of list_drawing_objects (0 is the back).
snapshot_drawing	snapshot_drawing(sheet: int, object_id: int) -> bytes	Capture the picture or chart object_id as opaque bytes for restore_drawing.
restore_drawing	restore_drawing(sheet: int, data: Union[bytes, bytearray, memoryview], *, new_id: bool = ...) -> int	Put a snapshot_drawing capture back and return the object's id.
list_shapes	list_shapes(sheet: int) -> List[Shape]	Return the shapes, connectors and groups of the sheet's drawing in z-order (back first).
insert_shape	insert_shape(sheet: int, *, anchor_kind: Union[AnchorKind, int], edit_as: Union[AnchorEditAs, int] = ..., from_row: int = ..., from_col: int = ..., from_row_off: int = ..., from_col_off: int = ..., to_row: int = ..., to_col: int = ..., to_row_off: int = ..., to_col_off: int = ..., cx: int = ..., cy: int = ..., name: Optional[str] = ..., prst: Optional[str] = ..., text: Optional[str] = ..., text_box: Optional[bool] = ..., fill_kind: Optional[Union[ShapePaint, int]] = ..., fill_rgb: int = ..., line_kind: Optional[Union[ShapePaint, int]] = ..., line_rgb: int = ..., line_width_emu: Optional[int] = ..., rotation: Optional[int] = ..., hidden: Optional[bool] = ...) -> int	Append a shape on top of the sheet's drawing and return its object id.
update_shape	update_shape(sheet: int, object_id: int, *, anchor_kind: Optional[Union[AnchorKind, int]] = ..., edit_as: Union[AnchorEditAs, int] = ..., from_row: int = ..., from_col: int = ..., from_row_off: int = ..., from_col_off: int = ..., to_row: int = ..., to_col: int = ..., to_row_off: int = ..., to_col_off: int = ..., cx: int = ..., cy: int = ..., name: Optional[str] = ..., prst: Optional[str] = ..., text: Optional[str] = ..., text_box: Optional[bool] = ..., fill_kind: Optional[Union[ShapePaint, int]] = ..., fill_rgb: int = ..., line_kind: Optional[Union[ShapePaint, int]] = ..., line_rgb: int = ..., line_width_emu: Optional[int] = ..., rotation: Optional[int] = ..., hidden: Optional[bool] = ...) -> None	Apply the arguments that are not None to the shape object_id; the rest of its XML is kept.
remove_shape	remove_shape(sheet: int, object_id: int) -> None	Remove the shape, connector or group object_id with its children.
list_slicers	list_slicers(sheet: int) -> List[Slicer]	Return the table slicers hosted by the sheet; slicers over a pivot cache are not listed.
add_slicer	add_slicer(sheet: int, table: int, column: int, *, anchor: Sequence[int], name: Optional[str] = ..., caption: Optional[str] = ..., style: Optional[str] = ..., column_count: Optional[int] = ..., row_height: Optional[int] = ..., sort_order: Optional[Union[SlicerSortOrder, int]] = ..., cross_filter: Optional[Union[SlicerCrossFilter, int]] = ...) -> int	Add a slicer over column column of table table and return its frame's object id.
update_slicer	update_slicer(sheet: int, index: int, *, anchor: Optional[Sequence[int]] = ..., caption: Optional[str] = ..., style: Optional[str] = ..., column_count: Optional[int] = ..., row_height: Optional[int] = ..., sort_order: Optional[Union[SlicerSortOrder, int]] = ..., cross_filter: Optional[Union[SlicerCrossFilter, int]] = ...) -> None	Apply the arguments that are not None to slicer index; the rest of its XML is kept.
remove_slicer	remove_slicer(sheet: int, index: int) -> None	Remove slicer index with its drawing frame, and its cache when no other slicer uses it.
list_sparkline_groups	list_sparkline_groups(sheet: int) -> List[SparklineGroup]	Return the sheet's sparkline groups in document order, each with its sparklines.
add_sparkline_group	add_sparkline_group(sheet: int, group: SparklineGroup) -> None	Append group with its sparklines (at least one) to the sheet's worksheet extension list.
update_sparkline_group	update_sparkline_group(sheet: int, index: int, group: SparklineGroup) -> None	Rewrite the modelled attributes, colours and date range of group index from group.
set_sparkline_group_sparklines	set_sparkline_group_sparklines(sheet: int, index: int, sparklines: Sequence[Sparkline]) -> None	Replace the sparklines of group index with sparklines (at least one).
remove_sparkline_group	remove_sparkline_group(sheet: int, index: int) -> None	Remove sparkline group index.

グラフ

名前	シグネチャ	説明
get_chart	get_chart(sheet: int, object_id: int) -> ChartInfo	Return the typed view of the chart object_id: plots, series, axes, legend and source.
get_chart_data	get_chart_data(sheet: int, object_id: int) -> ChartData	Resolve the chart's series against the current cell values by Excel's rules.
preview_chart_data	preview_chart_data(sheet: int, object_id: int, overrides: Optional[ChartPreviewOverrides] = ...) -> ChartData	Resolve the data of a copy of the chart with overrides applied; the workbook is unchanged.
insert_chart	insert_chart(sheet: int, kind: Union[ChartInsertKind, int], source: str, *, grouping: Union[ChartGrouping, int] = ..., direction: Union[ChartSeriesDirection, int] = ..., header_row: Optional[bool] = ..., header_column: Optional[bool] = ..., title: Optional[str] = ..., legend: Union[ChartLegendPosition, int] = ..., name: str = ..., description: str = ..., anchor_kind: Union[AnchorKind, int] = ..., edit_as: Union[AnchorEditAs, int] = ..., row: int = ..., col: int = ..., row_off_emu: int = ..., col_off_emu: int = ..., width_emu: int = ..., height_emu: int = ...) -> int	Create a chart over the A1 rectangle source and return its object id.
set_chart_type	set_chart_type(sheet: int, object_id: int, plot: int, kind: Union[ChartInsertKind, int], grouping: Union[ChartGrouping, int] = ...) -> None	Replace plot group plot with kind, keeping each series' references, idx, order and explicit colors.
set_chart_title	set_chart_title(sheet: int, object_id: int, title: Union[str, None, ChartTitleInfo]) -> None	Set the chart title to title; None removes it.
set_chart_legend	set_chart_legend(sheet: int, object_id: int, position: Union[ChartLegendPosition, int], overlay: bool = ..., *, hidden_series: Optional[Sequence[int]] = ...) -> None	Set the legend position (NONE removes it) and overlay.
set_chart_axis	set_chart_axis(sheet: int, object_id: int, axis_id: int, patch: ChartAxisPatch) -> None	Patch axis axis_id: an omitted key is kept, None removes the element.
set_chart_display	set_chart_display(sheet: int, object_id: int, blanks_as: Union[ChartBlanksAs, int], plot_visible_only: Optional[bool]) -> None	Write how blanks plot and whether hidden cells are skipped; ABSENT / None remove the element.
set_chart_series	set_chart_series(sheet: int, object_id: int, plot: int, series_idx: int, patch: ChartSeriesPatch) -> None	Patch the series with c:idx series_idx of plot group plot; a changed reference refreshes its cache.
set_chart_point	set_chart_point(sheet: int, object_id: int, plot: int, series_idx: int, point_idx: int, patch: Optional[ChartPointPatch]) -> None	Patch point point_idx of a series; None (or an empty patch) removes the point's formatting.
set_chart_plot	set_chart_plot(sheet: int, object_id: int, plot: int, patch: ChartPlotPatch) -> None	Patch plot group plot; a field the plot type does not have is rejected.
set_chart_filter	set_chart_filter(sheet: int, object_id: int, hidden_series: Sequence[int], hidden_categories: Sequence[int]) -> None	Replace the chart filter: the listed series (by c:idx) and category positions are hidden.
add_chart_series	add_chart_series(sheet: int, object_id: int, plot: int, patch: ChartSeriesPatch) -> int	Append a series to plot group plot and return its c:idx.
remove_chart_series	remove_chart_series(sheet: int, object_id: int, plot: int, series_idx: int) -> None	Remove the series with c:idx series_idx from plot group plot.
set_chart_source	set_chart_source(sheet: int, object_id: int, source: str, direction: Union[ChartSeriesDirection, int] = ..., header_row: Optional[bool] = ..., header_column: Optional[bool] = ...) -> None	Rebuild every series from source by the insert splitting rules.

印刷設定とページ分割

名前	シグネチャ	説明
paginate	paginate(sheet: int) -> PaginationResult	Resolve the worksheet's print area, page breaks, and page count.
get_page_setup_xml	get_page_setup_xml(sheet: int) -> str	Return the sheet's <pageSetup> fragment, or "".
set_page_setup_xml	set_page_setup_xml(sheet: int, xml: str) -> None	Replace the sheet's <pageSetup> fragment.
get_page_margins_xml	get_page_margins_xml(sheet: int) -> str	Return the sheet's <pageMargins> fragment, or "".
set_page_margins_xml	set_page_margins_xml(sheet: int, xml: str) -> None	Replace the sheet's <pageMargins> fragment.
get_print_options_xml	get_print_options_xml(sheet: int) -> str	Return the sheet's <printOptions> fragment, or "".
set_print_options_xml	set_print_options_xml(sheet: int, xml: str) -> None	Replace the sheet's <printOptions> fragment.
get_header_footer_xml	get_header_footer_xml(sheet: int) -> str	Return the sheet's <headerFooter> fragment, or "".
set_header_footer_xml	set_header_footer_xml(sheet: int, xml: str) -> None	Replace the sheet's <headerFooter> fragment.
get_sheet_pr_xml	get_sheet_pr_xml(sheet: int) -> str	Return the sheet's <sheetPr> fragment, or "".
set_sheet_pr_xml	set_sheet_pr_xml(sheet: int, xml: str) -> None	Replace the sheet's <sheetPr> fragment.
set_fit_to_page	set_fit_to_page(sheet: int, enabled: bool) -> None	Set or clear <sheetPr><pageSetUpPr fitToPage>.
get_print_area	get_print_area(sheet: int) -> str	Return the print area as comma-separated A1 ranges, or "".
set_print_area	set_print_area(sheet: int, ranges_a1: str) -> None	Write _xlnm.Print_Area from one or more A1 ranges.
get_print_titles	get_print_titles(sheet: int) -> tuple[str, str]	Return (repeat_rows, repeat_cols) as "1:2" / "A:A".
set_print_titles	set_print_titles(sheet: int, repeat_rows: str = ..., repeat_cols: str = ...) -> None	Write _xlnm.Print_Titles from a row span and a column span.
add_row_break	add_row_break(sheet: int, row: int, manual: bool = ...) -> None	Upsert a row break before row, spanning the whole sheet.
add_col_break	add_col_break(sheet: int, col: int, manual: bool = ...) -> None	Upsert a column break before col, spanning the whole sheet.
remove_row_break	remove_row_break(sheet: int, row: int) -> None	Remove the row break at row.
remove_col_break	remove_col_break(sheet: int, col: int) -> None	Remove the column break at col.
clear_breaks	clear_breaks(sheet: int) -> None	Remove every manual break on both axes.
get_row_breaks	get_row_breaks(sheet: int) -> List[PageBreak]	Return the row breaks, ascending by row.
get_col_breaks	get_col_breaks(sheet: int) -> List[PageBreak]	Return the column breaks, ascending by column.
set_page_setup	set_page_setup(sheet: int, *, orientation: Optional[int] = ..., paper_size: Optional[int] = ..., scale: Optional[int] = ..., fit_to_width: Optional[int] = ..., fit_to_height: Optional[int] = ..., fit_to_page: Optional[bool] = ...) -> None	Apply a partial <pageSetup> update.
set_page_margins	set_page_margins(sheet: int, *, left: Optional[float] = ..., right: Optional[float] = ..., top: Optional[float] = ..., bottom: Optional[float] = ..., header: Optional[float] = ..., footer: Optional[float] = ...) -> None	Apply a partial <pageMargins> update, in inches.
set_print_options	set_print_options(sheet: int, *, grid_lines: Optional[bool] = ..., headings: Optional[bool] = ..., horizontal_centered: Optional[bool] = ..., vertical_centered: Optional[bool] = ...) -> None	Apply a partial <printOptions> update.
set_header_footer	set_header_footer(sheet: int, *, odd_header: Optional[str] = ..., odd_footer: Optional[str] = ..., even_header: Optional[str] = ..., even_footer: Optional[str] = ..., first_header: Optional[str] = ..., first_footer: Optional[str] = ..., different_odd_even: Optional[bool] = ..., different_first: Optional[bool] = ..., scale_with_doc: Optional[bool] = ..., align_with_margins: Optional[bool] = ...) -> None	Apply a partial <headerFooter> update.
get_page_setup	get_page_setup(sheet: int) -> PageSetup	Read the effective page setup and which attributes state it.
get_page_margins	get_page_margins(sheet: int) -> PageMargins	Read the effective page margins in inches, with presence flags.

ピボットテーブル

名前	シグネチャ	説明
pivot_count	pivot_count(sheet: int) -> int	Return the number of PivotTables anchored on sheet.
pivot_layout	pivot_layout(sheet: int, pivot_index: int) -> PivotLayout	Evaluate and project a PivotTable into concrete grid cells.
get_pivot_report_layout	get_pivot_report_layout(sheet: int, pivot_index: int) -> PivotReportLayout	Return the pivot's compact, tabular, or outline report layout.
set_pivot_report_layout	set_pivot_report_layout(sheet: int, pivot_index: int, layout: Union[PivotReportLayout, int]) -> None	Set the pivot's compact, tabular, or outline report layout.
pivot_create	pivot_create(sheet: int, name: str, cache_id: int, anchor_row: int, anchor_col: int) -> int	Create a new empty pivot table; return its flat index.
pivot_remove	pivot_remove(sheet: int, pivot_index: int) -> None	Remove the pivot table at pivot_index.
pivot_set_name	pivot_set_name(sheet: int, pivot_index: int, name: str) -> None	Rename the pivot table.
pivot_set_anchor	pivot_set_anchor(sheet: int, pivot_index: int, anchor_row: int, anchor_col: int, span_rows: int, span_cols: int) -> None	Update the pivot's anchor cell and span.
pivot_set_grand_totals	pivot_set_grand_totals(sheet: int, pivot_index: int, rows_enabled: bool, cols_enabled: bool) -> None	Toggle the row / column grand-total bands.
pivot_set_style_info	pivot_set_style_info(sheet: int, pivot_index: int, name: Optional[str] = None, *, show_row_headers: bool = False, show_col_headers: bool = False, show_row_stripes: bool = False, show_col_stripes: bool = False, show_last_column: bool = False) -> None	Set the pivot's table style and toggles, making the style element present.
pivot_name	pivot_name(sheet: int, pivot_index: int) -> str	Return the pivot's name.
pivot_grand_totals	pivot_grand_totals(sheet: int, pivot_index: int) -> Tuple[bool, bool]	Return (rows, cols), the flags pivot_set_grand_totals writes.
pivot_style_info	pivot_style_info(sheet: int, pivot_index: int) -> PivotStyleInfo	Return the table style pivot_set_style_info writes.
pivot_row_field_order	pivot_row_field_order(sheet: int, pivot_index: int) -> List[int]	Return the row-axis field order (the list pivot_set_row_field_order takes).
pivot_col_field_order	pivot_col_field_order(sheet: int, pivot_index: int) -> List[int]	Return the column-axis field order.
pivot_field_at	pivot_field_at(sheet: int, pivot_index: int, field_idx: int) -> PivotFieldInfo	Read the definition of pivot field field_idx.
pivot_field_item_count	pivot_field_item_count(sheet: int, pivot_index: int, field_idx: int) -> int	Return the number of items in pivot field field_idx's item list.
pivot_field_item_at	pivot_field_item_at(sheet: int, pivot_index: int, field_idx: int, item_idx: int) -> PivotItemInfo	Read item item_idx of pivot field field_idx.
pivot_data_field_at	pivot_data_field_at(sheet: int, pivot_index: int, data_field_idx: int) -> PivotDataFieldSpec	Read data field data_field_idx in the shape pivot_data_field_add accepts.
pivot_field_count	pivot_field_count(sheet: int, pivot_index: int) -> int	Return the number of fields configured on the pivot.
pivot_field_add	pivot_field_add(sheet: int, pivot_index: int, spec: PivotFieldSpec) -> int	Place a field on the pivot; return its index.
pivot_field_clear	pivot_field_clear(sheet: int, pivot_index: int) -> None	Drop every field from the pivot.
pivot_field_set_axis	pivot_field_set_axis(sheet: int, pivot_index: int, field_idx: int, axis: Union[PivotAxis, int]) -> None	Set the axis of pivot field field_idx.
pivot_field_set_sort	pivot_field_set_sort(sheet: int, pivot_index: int, field_idx: int, order: Union[PivotSortOrder, int], by_field: str = ...) -> None	Set the sibling order of pivot field field_idx.
pivot_field_set_subtotal_top	pivot_field_set_subtotal_top(sheet: int, pivot_index: int, field_idx: int, top: bool) -> None	Set the subtotal_top flag on pivot field field_idx.
pivot_field_add_item	pivot_field_add_item(sheet: int, pivot_index: int, field_idx: int, name: str, visible: bool) -> None	Append a manual-filter item addressed by its label.
pivot_field_add_item_at	pivot_field_add_item_at(sheet: int, pivot_index: int, field_idx: int, cache_index: int, visible: bool) -> None	Append a manual-filter item addressed by its cache shared-item index.
pivot_field_clear_items	pivot_field_clear_items(sheet: int, pivot_index: int, field_idx: int) -> None	Drop every manual-filter item from pivot field field_idx.
pivot_field_set_item_visible	pivot_field_set_item_visible(sheet: int, pivot_index: int, field_idx: int, item_idx: int, visible: bool) -> None	Toggle the visibility of item item_idx on field field_idx.
pivot_field_add_subtotal_fn	pivot_field_add_subtotal_fn(sheet: int, pivot_index: int, field_idx: int, agg: Union[PivotAggregation, int]) -> None	Append a subtotal-fn entry to pivot field field_idx.
pivot_field_clear_subtotal_fns	pivot_field_clear_subtotal_fns(sheet: int, pivot_index: int, field_idx: int) -> None	Drop every subtotal-fn entry from pivot field field_idx.
pivot_field_set_date_group	pivot_field_set_date_group(sheet: int, pivot_index: int, field_idx: int, granularity: Union[PivotDateGrouping, int], calendar: Union[PivotCalendar, int], start_year: int = ..., end_year: int = ..., interval_days: int = ..., start_serial: float = ..., end_serial: float = ...) -> None	Configure date-grouping on pivot field field_idx.
pivot_field_clear_date_group	pivot_field_clear_date_group(sheet: int, pivot_index: int, field_idx: int) -> None	Remove the date-grouping config from pivot field field_idx.
pivot_field_set_number_format	pivot_field_set_number_format(sheet: int, pivot_index: int, field_idx: int, fmt: str) -> None	Set the numFmtId of pivot field field_idx.
pivot_set_row_field_order	pivot_set_row_field_order(sheet: int, pivot_index: int, indices: Sequence[int]) -> None	Replace the row-axis field order with indices.
pivot_set_col_field_order	pivot_set_col_field_order(sheet: int, pivot_index: int, indices: Sequence[int]) -> None	Replace the column-axis field order with indices.
pivot_data_field_count	pivot_data_field_count(sheet: int, pivot_index: int) -> int	Return the number of <dataField> entries on the pivot.
pivot_data_field_add	pivot_data_field_add(sheet: int, pivot_index: int, spec: PivotDataFieldSpec) -> int	Append a data-field entry; return its index.
pivot_data_field_set	pivot_data_field_set(sheet: int, pivot_index: int, data_field_idx: int, spec: PivotDataFieldSpec) -> None	Replace the data-field entry at data_field_idx in place.
pivot_data_field_clear	pivot_data_field_clear(sheet: int, pivot_index: int) -> None	Drop every data-field entry from the pivot.
pivot_filter_count	pivot_filter_count(sheet: int, pivot_index: int) -> int	Return the number of filters on the pivot; see pivot_filter_at.
pivot_filter_add	pivot_filter_add(sheet: int, pivot_index: int, spec: PivotFilterSpec) -> None	Append a filter to the pivot; it is saved with it.
pivot_filter_at	pivot_filter_at(sheet: int, pivot_index: int, filter_idx: int) -> PivotFilterSpec	Read the filter at filter_idx without mutating it.
pivot_filter_clear	pivot_filter_clear(sheet: int, pivot_index: int) -> None	Drop every listed filter from the pivot.
pivot_filter_remove_at	pivot_filter_remove_at(sheet: int, pivot_index: int, filter_idx: int) -> None	Remove the filter at filter_idx.

ピボットキャッシュ

名前	シグネチャ	説明
pivot_cache_count	pivot_cache_count() -> int	Return the number of pivot caches owned by the workbook.
pivot_cache_id_at	pivot_cache_id_at(index: int) -> int	Return the cache id at flat index.
pivot_cache_create	pivot_cache_create(requested_id: int = ...) -> int	Create a new empty pivot cache; return its assigned id.
get_pivot_cache_worksheet_source	get_pivot_cache_worksheet_source(cache_id: int) -> Optional[PivotWorksheetSource]	Return a cache's worksheet-source metadata, or None when absent.
set_pivot_cache_worksheet_source	set_pivot_cache_worksheet_source(cache_id: int, source: Optional[PivotWorksheetSource]) -> None	Set cache worksheet-source metadata; pass None to clear it.
pivot_cache_remove	pivot_cache_remove(cache_id: int) -> None	Remove the pivot cache with id cache_id.
pivot_cache_field_count	pivot_cache_field_count(cache_id: int) -> int	Return the number of fields on the cache.
pivot_cache_field_name	pivot_cache_field_name(cache_id: int, field_idx: int) -> str	Read the name of cache field field_idx.
pivot_cache_field_add	pivot_cache_field_add(cache_id: int, name: str) -> int	Append a field to the cache; return its index.
pivot_cache_field_clear	pivot_cache_field_clear(cache_id: int) -> None	Drop every field (and record) from the cache.
pivot_cache_field_shared_item_count	pivot_cache_field_shared_item_count(cache_id: int, field_idx: int) -> int	Return the shared-item count on cache field field_idx.
pivot_cache_field_add_shared_item_number	pivot_cache_field_add_shared_item_number(cache_id: int, field_idx: int, value: float) -> None	Append a numeric shared item to a cache field.
pivot_cache_field_add_shared_item_text	pivot_cache_field_add_shared_item_text(cache_id: int, field_idx: int, value: str) -> None	Append a text shared item to a cache field.
pivot_cache_field_add_shared_item_bool	pivot_cache_field_add_shared_item_bool(cache_id: int, field_idx: int, value: bool) -> None	Append a boolean shared item to a cache field.
pivot_cache_field_add_shared_item_blank	pivot_cache_field_add_shared_item_blank(cache_id: int, field_idx: int) -> None	Append a blank shared item to a cache field.
pivot_cache_field_add_shared_item_error	pivot_cache_field_add_shared_item_error(cache_id: int, field_idx: int, error_code: int) -> None	Append an Excel error shared item to a cache field.
pivot_cache_field_clear_shared_items	pivot_cache_field_clear_shared_items(cache_id: int, field_idx: int) -> None	Drop every shared item from a cache field.
pivot_cache_record_count	pivot_cache_record_count(cache_id: int) -> int	Return the number of records on the cache.
pivot_cache_record_add	pivot_cache_record_add(cache_id: int) -> int	Append an empty record to the cache; return its index.
pivot_cache_record_clear	pivot_cache_record_clear(cache_id: int) -> None	Drop every record from the cache.
pivot_cache_record_set_number	pivot_cache_record_set_number(cache_id: int, record_idx: int, field_idx: int, value: float) -> None	Set cache cell (record_idx, field_idx) to a number.
pivot_cache_record_set_text	pivot_cache_record_set_text(cache_id: int, record_idx: int, field_idx: int, value: str) -> None	Set cache cell (record_idx, field_idx) to text.
pivot_cache_record_set_bool	pivot_cache_record_set_bool(cache_id: int, record_idx: int, field_idx: int, value: bool) -> None	Set cache cell (record_idx, field_idx) to a boolean.
pivot_cache_record_set_blank	pivot_cache_record_set_blank(cache_id: int, record_idx: int, field_idx: int) -> None	Set cache cell (record_idx, field_idx) to blank.
pivot_cache_record_set_error	pivot_cache_record_set_error(cache_id: int, record_idx: int, field_idx: int, error_code: int) -> None	Set cache cell (record_idx, field_idx) to an Excel error.
pivot_cache_id	pivot_cache_id(sheet: int, pivot_index: int) -> int	Return the cache_id of the pivot cache the pivot draws from.

メソッドの補足

CellStyle は set_cell_style() と get_cell_style() が使う名前付きスタイルのレコードです。フィールドは name、xf_id、builtin_id、i_level、hidden、custom_builtin で、name と xf_id は必須です。それ以外はデータクラスの既定値を使います。カスタムスタイルでは builtin_id を既定値のままにしてください。xf_id は名前付きスタイルの XF テーブルを指し、セル単位の XF テーブルは指しません。

行と列のスタイル、clear_cell_xf_index() と set_cell_xf_index(..., 0) の違い、range_style_bases() → remap_range_style() による変更と、その取り消しに使う snapshot_range_style() / restore_range_style() は ワークブック操作 の規則に従います。get_theme() は major_scripts と minor_scripts を返します。スクリプト別フォントの規則は 表示とレイアウト を参照してください。

Python にはスカラーの evaluate_formula_text() がありません。evaluate_formula_array(sheet, row, col, formula) は結果全体を読み取り専用で返し、evaluate_cf_formula(sheet, row, col, anchor_row, anchor_col, formula) は条件付き書式の条件式を評価します。

get_iterative() は IterativeSettings(enabled, max_iterations, max_change) を返します。エンジンは max_iterations を 32767 までに制限し、制限後の値を返します。set_iterative_enabled(enabled) は保存済みの上限と閾値を保ったまま反復計算を切り替え、add_batch() はフォント、塗りつぶし、罫線、表示形式、XF を 1 回の呼び出しで登録します。

set_calc_mode(mode) は CalcMode を受け取ります。AUTO_NO_TABLE では、recalc_data_tables() を呼ぶまで recalc() はデータテーブルの結果を計算しません。full_precision()、calc_on_save()、ref_mode()、date1904() は対応する <calcPr> と <workbookPr> の設定を読み、それぞれに set_ 版があります。<calcPr> のその他の属性は再保存しても保持されます。

active_sheet() / set_active_sheet(sheet) はアクティブタブを読み書きします。設定すると tabSelected も移り、非表示シートは拒否されます。アクティブなシートを非表示にするか削除すると、右隣の次の表示シート、なければ左側で最も近い表示シートがアクティブになります。set_sheet_top_left() と set_sheet_pane_top_left() はビューと右下ペインのスクロール原点を設定し、get_sheet_selection() / set_sheet_selection() は各ペインの選択範囲を扱います。set_sheet_split(sheet, x_twips, y_twips) は、固定せずに twips 単位の位置でビューを分割します。分割は固定を置き換え、固定も分割を置き換え、0, 0 で分割を解除します。ビューに存在しないペインの選択は保存時に捨てられ、選択範囲のどれにも入らないアクティブセルは最初の範囲の左上へ移ります。get_sheet_view() は show_formulas と show_outline_symbols を返し、set_sheet_show_formulas() と set_sheet_show_outline_symbols() で設定できます。

set_row_collapsed() と set_column_collapsed() は、行・列の上書き設定の getter が返すアウトラインの collapsed フラグを設定します。outlineLevelRow と outlineLevelCol は、保存のたびに最も深いレベルから導出します。7 を超えるアウトラインレベルは FormulonError を送出します。

add_data_table()、get_data_table(sheet, row, col)、remove_data_table(sheet, row, col) は What-If データテーブル（<f t="dataTable">）を扱います。recalc() は、入力セルに値を順に代入し、それを読むセルを再計算して入力を元に戻すことで、1 変数（列入力または行入力）と 2 変数のテーブルを埋めます。結果セルへの書き込みは kPreconditionFailed の FormulonError になり、テーブルまたはその見出し行・列を横切る行・列の挿入と削除も同様です。結果セルは数式 getter で =TABLE(row_input,col_input) を返し、FORMULATEXT は {=TABLE(...)}、ISFORMULA は TRUE を返します。

list_shapes()、insert_shape()、update_shape()、remove_shape() は、シートの描画に含まれる xdr:sp の図形とテキストボックス、xdr:cxnSp のコネクタ、xdr:grpSp のグループを扱います。更新は指定したフィールドだけを書き換え、図形の残りの XML は保持します。レコードで表現できない図形は ShapePaint.OTHER または空のフィールドで列挙され、保存してもそのまま通過します。図形は画像と同様に行・列の編集に追従します。

list_sparkline_groups()、add_sparkline_group()、update_sparkline_group()、set_sparkline_group_sparklines()、remove_sparkline_group() は、シートの x14:sparklineGroups を扱います。更新しても、rightToLeft、uid、未知の拡張といったレコード外の属性と子要素は保持されます。

list_slicers()、add_slicer()、update_slicer()、remove_slicer() はテーブルスライサーを扱います。追加するとスライサーパーツ、キャッシュ、拡張エントリ、定義名、描画フレームが作られます。スライサーを削除すると、ほかに使うスライサーがなくなった時点でそのキャッシュも削除されます。テーブルやシートの削除、スライサーのフレーム下の行・列の削除では、それに結び付いたスライサーも削除されます。ピボットキャッシュ上のスライサーはそのまま通過し、列挙されません。テーブルスライサーの選択状態はテーブルの AutoFilter が保持します。

get_workbook_protection() / set_workbook_protection() は <workbookProtection> を読み書きし、get_protected_ranges()、add_protected_range()、update_protected_range()、remove_protected_range() はシートの <protectedRange> を扱います。保護範囲は行・列の編集に追従します。パスワードハッシュはホストが計算した値をそのまま保存し、レコードにない属性は保持します。どちらの保護もセル編集では強制されません。

table_rename(index, name, display_name=None) はテーブルの名前を変更し、セル、定義名、条件付き書式、入力規則、計算列と集計行の数式、グラフ系列にある構造化参照を書き換えます。そのテーブルを元にしたピボットキャッシュも追従します。table_set_style_info() はスタイル名と、最初の列・最後の列・行ストライプ・列ストライプの切り替えを設定し、table_set_column_totals() は 1 列の集計関数、ラベル、数式を設定します。集計行をオンにすると、各列の集計セルが書き込まれます。get_table_style()、set_table_style()、remove_table_style()、table_style_defaults()、set_table_style_defaults() は、カスタムの <tableStyles> と既定のテーブル・ピボットテーブルのスタイル名を扱い、pivot_style_info() / pivot_set_style_info() はピボットテーブルのスタイルを読み書きします。set_defined_name_attrs(name, local_sheet_id, ...) は名前のコメントと非表示フラグを設定し、名前の数式を置き換えても両方とも保持されます。

get_comment_visible() / set_comment_visible() は、従来のメモが表示状態かどうかを読み書きします。メモのボックス、表示状態、コメントパーツの作成者テーブルは再保存しても保持され、ボックスは行・列の編集でメモに追従します。get_show_phonetic() / set_show_phonetic() は、セルごとの「ふりがなを表示」フラグを読み書きします。保存ファイルでこのフラグを持つのは定数と空白セルだけで、数式セルには付きません。

add_sheet() と rename_sheet() は、空の名前、UTF-16 で 31 単位を超える名前、: \ / ? * [ ] を含む名前、アポストロフィで始まるまたは終わる名前、大文字小文字を同一視すると別のシート名と重なる名前を kInvalidSheetName の FormulonError で拒否します。win-* プロファイル（既定を含む）では、大文字小文字を問わず History も拒否し、mac-* プロファイルは受け付けます。表示中の唯一のシートを非表示にするか削除すると FormulonError を送出し、データテーブル、従来の配列ブロック、ピボットテーブルを横切る行・列の挿入と削除、またはそれらやテーブルをグリッドの端より先へ押し出す挿入も同様です。

set_sheet_visibility() は SheetVisibility.VISIBLE、HIDDEN、VERY_HIDDEN を受け取り、get_sheet_view() は tab_hidden に加えて解決済みの 3 状態を返します。set_range_xf_index() はセル書式（XF）インデックスを両端を含む矩形へ適用し、存在しないセルを書式付きの空セルとして作成します。

table_create() の column_names は ref の列数と一致させます。見出しセルは呼び出し側が書き込みます。table_update() は None を渡した項目を変更せず、既存テーブルの AutoFilter は範囲を変えても条件と拡張を保ちます。get_auto_filter_xml() / set_auto_filter_xml() はシートの AutoFilter を <autoFilter> の XML 断片のまま読み書きし、空文字列を渡すと削除します。行や列を挿入・削除すると、AutoFilter の ref と、モデル化した条件・並べ替えのオフセットもセルと一緒に移動します。解析しないワークシート XML はバイト列のまま保持します。

add_hyperlink_range() は両端を含む矩形に 1 つのハイパーリンクを追加し、読み出した Hyperlink には last_row と last_col が入ります。DataValidationInput で allow_blank を省略した場合の既定値は False です。空セルを許可する場合は allow_blank=True を指定してください。

条件付き書式の表示データは ColorScale、DataBar、IconSet で表します。DataBar は x14 の制御項目 gradient、axis_position（0 は自動、1 は中央、2 はなし）、negative_fill、border、negative_border、axis_color、direction（0 はシートの読み方向、1 は左から右、2 は右から左）を持ちます。省略した項目はモデルの既定値を使い、保存と読み込みをまたいで保持されます。

新しく作成したピボットキャッシュには、保存前にワークシートの参照元を設定してください。たとえば set_pivot_cache_worksheet_source(cache_id, PivotWorksheetSource(ref="A1:C10", sheet="Data")) です。参照元のない新規キャッシュは保存に失敗します。読み込んだキャッシュは参照元のメタデータを保持し、参照元がワークシート以外や外部データの場合もあります。pivot_field_add_item_at() はキャッシュの共有項目インデックスで手動フィルター項目を指定します。空白の項目を指定できるのはこの方法だけで、pivot_field_add_item() に空のラベルを渡しても指定できません。

get_cells_in_range(sheet, cell_range, cursor=None, limit=None) は、行・列の順序で (cells, next_cursor) を返します。各 Cell は row、col、formula、value を持ちます。next_cursor が None になるまで次の呼び出しへ渡してください。limit の省略または 0 は最大 65,536 件を選びます。数式セル、空白でない値、スピルの仮想セルを含み、スタイルだけを持つ空セルは含みません。list_invalid_cells() も同じページング規則に従います。

寸法メソッドは 96 DPI の画面向けモデルに GeometryMode.DISPLAY、ページ分割に使う DPI に依存しないモデルに GeometryMode.PRINT を指定します。get_display_text() と format_value() は、値が書式の表現可能な範囲を外れると DisplayStatus.OVERFLOW と ######## を返し、書式コードが不正な場合は DisplayStatus.INVALID_FORMAT として General 表示へフォールバックします。

probe_image() はワークブックを変更せず、PNG、JPEG、GIF、BMP の画像形式と寸法を読み取ります。list_drawing_objects() はシートのアンカー付きオブジェクトを文書順で返します。get_image() は画像バイト列をコピーし、insert_image() は既存の描画を保持します。remove_drawing() は画像またはグラフを削除し、他のオブジェクトがメディアを参照しなくなった場合にメディアも解放します。スレッドコメント API は返信と人物レコードを含み、コメントやメンションが参照している人物は削除できません。

AutoFilter の条件と行の表示状態は別に管理します。evaluate_auto_filter() で一致結果を確認し、apply_auto_filter() で非表示行を更新してください。clear_auto_filter() は範囲を残したまま条件を削除します。入力規則 API は値を保存せずに候補値を検証し、list_invalid_cells() は既存の違反を列挙します。

paginate(sheet) は page_count、print_area、horizontal_breaks、vertical_breaks、paper、margins、printable、scale、page_order、print_titles、pages、horizontal_break_manual、vertical_break_manual を持つ PaginationResult を返します。paper はポイント単位の寸法、向き、用紙コードを認識できたかを持ちます。pages の各 PageLayout は area_index、両端を含むセル範囲、原点、拡大縮小後の寸法を持ちます。印刷範囲の指定がない場合も print_area は空のままですが、ページ分割は使用範囲へフォールバックします。手動改ページのリストは対応する改ページリストと同じ順序です。

set_formula() は不正な数式を kParserUnexpectedToken として拒否し、既存の数式とキャッシュ値を変更しません。保存済みの XLSX / XLSB に不正な数式が含まれる場合は読み込みできますが、recalc() 後のセル値は #NAME? になります。単発の eval_formula() はアドホック評価のため、不正な入力を #NAME? の値として返します。

iter_cells(sheet) は、書式だけの空白セル、set_blank で書き込んだセル、スピル先のセルを含む書き込み済み座標を (row, col) の昇順で列挙します。未書き込みの隙間は含みません。列挙中はシートを変更しないでください。get_cells_in_range() とは異なり、明示的に書き込んだ空白セルも対象です。詳しくは ワークブック操作を参照してください。

保存時の診断

save_with_diagnostics(fmt) は、保存した bytes と書き出し側が検出した損失・保存時に出力されなかった機能のカウンターを持つ SaveDiagnostics を返します。read_diagnostics() は、ワークブックの読み込み時に取得したカウンターを持つ ReadDiagnostics を返します。カウンターの対象は一部の損失だけです。すべて 0 であることは、記載された損失が発生しなかったことを示しますが、パッケージをバイト単位で比較したことや、診断イベントが一切なかったことは示しません。

結果	フィールド	意味
SaveDiagnostics	downgraded_formula_count	キャッシュ済みリテラルとして出力された数式セルの数。XLSX では常に 0 です。
	deferred_feature_count	レコードへ変換されなかったシート機能の数。XLSX では常に 0 です。
	dropped_part_count	いずれかの書き出し側が破棄した、そのまま保持していたパートの数。
	dropped_relationship_count	対象パートの破棄に伴って破棄された関連付けの数。dropped_part_count と同じ損失を表す場合があります。
	renumbered_part_count	書き出し側が割り当てたパート ID で出力されたテーブルの数。XLSB では常に 0 です。
ReadDiagnostics	undecoded_formula_count	デコードできなかった保存済み数式の数。XLSB のみです。
	undecoded_defined_name_count	デコードできずにスキップされた定義名の数。XLSB のみです。
	undecoded_part_count	コンテンツタイプを解決できなかった XLSB パッケージパートの数。
	skipped_feature_count	参照が利用できずスキップされた OOXML の表示オーバーレイ項目の数。
	unknown_content_type_count	コンテンツタイプを認識できなかった OOXML ワークブックパートの数。

from formulon import Workbook, WorkbookFormat

with Workbook.create_default() as wb:
    saved = wb.save_with_diagnostics(WorkbookFormat.XLSB)
    print(saved.bytes, saved.downgraded_formula_count)
    loaded = Workbook.load(saved.bytes)
    try:
        print(loaded.read_diagnostics().undecoded_formula_count)
    finally:
        loaded.close()

dropped_part_count と dropped_relationship_count は、1 つのパートを破棄したときにどちらも増える場合があります。失われたオブジェクト数として合計しないでください。

時計の固定

ワークブックが固定されていない場合、NOW()、TODAY()、ピボットの相対期間フィルターはホストの時計を読み取ります。これらの結果を 1 回の再計算で一致させる場合や、ホストをまたいで再現する場合は、ワークブックを 1 つの年月日・時分秒の値に固定してください。

from formulon import Workbook

with Workbook.create_default() as wb:
    wb.set_pinned_now(2026, 8, 19, 12, 0, 0)
    print(wb.pinned_now())  # CivilTime(year, month, day, hour, minute, second)
    wb.recalc()
    wb.clear_pinned_now()

pinned_now() は CivilTime オブジェクトを返し、ワークブックがホストの時計に従う場合は None を返します。set_pinned_now() は year 1900–9999、month 1–12、月ごとの実在する日、hour 0–23、minute / second 0–59 を検証します。不正な値は正規化せず、FormulonError を送出します。値はタイムスタンプではなく、年月日・時分秒の値として保持するため、タイムゾーンの解釈はありません。固定の設定・解除ではキャッシュ済みの数式値を再計算しないため、必要に応じて recalc() を明示的に呼び出してください。固定はファイル状態ではなくワークブックのモデル状態です。保存時には記録されず、読み込み直後のワークブックは固定されていません。

値

Value.to_python() は空白、数値、真偽値、テキストを Python 型（None / float / bool / str）に変換します。エラー、配列、参照、ラムダは Value ラッパーのまま返るので、kind とデータを確認できます。

value = wb.get_value(0, 0, 0)
if value.kind is ValueKind.NUMBER:
    print(value.number)
elif value.kind is ValueKind.ERROR:
    print(formulon.error_display_name(value.error_code))

Value は構築時にペイロードを検証します。kind は ValueKind に変換され、その種類が取らないペイロードや欠けたペイロードは ValueError、型の違うペイロードは TypeError になります。そのため Value(ValueKind.NUMBER) や Value(ValueKind.BLANK, text="a") は失敗し、bool は数値として受け付けません。

Python の Value が持つのは error_code だけで、error_text というフィールドはありません。formulon.error_display_name(value.error_code) で #DIV/0! や #VALUE! の表示文字列を得られます。

エラー処理

FormulonError はホスト側の失敗を表します。不正なバイト列、範囲外のインデックス、set_formula() に渡した不正なテキスト、close() 後の呼び出し、エンジン内部の失敗が該当します。例外は status（数値の fm_status_t）、status_name（kParserUnexpectedToken など）、message、context を持ちます。小数であったり、負のシート番号のように C ABI の整数の幅に収まらなかったりする整数引数は、エンジンを呼ぶ前に ValueError を送出します。パックされた整数引数も同じ方法で範囲を検査します。Excel のセルエラーは例外ではなく値です。

import formulon
from formulon import Workbook, ValueKind, FormulonError

try:
    with Workbook.load(blob) as wb:
        wb.recalc()
        v = wb.get_value(0, 0, 0)
        if v.kind is ValueKind.ERROR:
            handle_cell_error(v)
except FormulonError as e:
    handle_host_failure(e)

次に読むもの

• ワークブックの流れ ─ 開く / 変更 / 再計算 / 保存
• 表示とレイアウト ─ 表示文字列、テーマ、スタイル、寸法、ページ分割
• フィルターと入力規則 ─ AutoFilter と候補値の検証
• コメントと画像 ─ スレッドコメント、人物、描画オブジェクト、画像
• Python で一括再計算 ─ 一連のパイプライン