Excel Calculation Modes¶

calculation_mode controls automatic, manual, and semi-automatic recalculation (automatic except what-if data tables, not worksheet Tables). All actions require session_id.

Calculation after writes¶

Range value/formula writes temporarily suppress calculation when appropriate, then attempt to restore the prior mode. They do not unconditionally calculate after every write:

Restoration can fail without failing the write, leaving Excel in manual mode. Use calculation_mode(action: 'get-mode', session_id: id) when subsequent work depends on the mode.

A successful write does not guarantee that asynchronous refreshes or Python calculations have finished. Use the owning operation's completion checks and read back the calculated values needed for the task.

Use manual mode for bulk writes when repeated recalculation is costly. There is no universal cell-count threshold: one rectangular write is already batched. Reading formula text does not require changing the mode. Keep calculation available when intermediate formula results are needed.

Preserve the Workbook's Mode¶

1. Call get-mode and remember the returned mode.
2. Call set-mode with mode: 'manual'.
3. Write the requested values/formulas in rectangular blocks.
4. Call calculate with the appropriate scope.
5. Restore the prior mode, not necessarily automatic.

Treat restoration like a finally block: attempt it after success or failure. If cancellation or a timeout removed the session, inspect file list first and report that restoration could not be completed. Do not blindly reopen or repeat writes; cancellation is not undo.

previous = calculation_mode(action: 'get-mode', session_id: id).mode
try:
    calculation_mode(action: 'set-mode', session_id: id, mode: 'manual')
    range(action: 'set-values', session_id: id, sheet_name: 'Sales',
          range_address: 'A1:B2', values: [['Name', 'Amount'], ['Salary', 5000]])
    calculation_mode(action: 'calculate', session_id: id, scope: 'workbook')
finally:
    calculation_mode(action: 'set-mode', session_id: id, mode: previous)

The example is workflow notation, not executable code. Check each result before continuing and surface both the original failure and any restoration failure.

Actions¶

Sheet scope requires sheet_name. Range scope also requires range_address. Choose workbook scope when dependencies cross sheets; inspect calculated values when they are part of the requested result.