Staged Worksheet Layout Builder

Prepare a helper that stages multiple worksheet layout changes offline, then applies them in a single commit to minimize network calls.

Capabilities

Stage layout without live writes

• Accept a sheet-like object plus header titles, column widths, and body rows; queue merges, freezes, widths, and value updates without changing the live worksheet yet. @test

Commit staged plan once

• Applying the commit performs all queued operations in one sync: merged header across all provided columns, header row populated and frozen, column widths set, and body rows written. @test

Cancel staged changes

• Cancelling before commit clears staged operations and leaves the worksheet exactly as it was prior to staging. @test

Implementation

@generates

API

from typing import Sequence, Any

class WorksheetLayoutPlanner:
    def __init__(self, sheet: Any):
        """Initialize in staging mode against the provided worksheet handle without issuing network calls."""

    def queue_layout(self, headers: Sequence[str], rows: Sequence[Sequence[Any]], column_widths: Sequence[int], freeze_rows: int = 1) -> None:
        """Queue merges, freezes, column widths, and value placement for the provided data without applying them yet."""

    def commit(self) -> None:
        """Apply all staged structural and value updates to the live worksheet in a single sync."""

    def cancel(self) -> None:
        """Drop any staged changes so the worksheet remains unchanged."""

Dependencies { .dependencies }

pygsheets { .dependency }

Provides worksheet staging and bulk update support. @satisfied-by