engine

The workbook model: a Grid of Sheets, each a sparse dict[(col, row)] -> Cell, plus the array type ranges evaluate to, the reference parsing and adjustment rules, and JSON load/save.

engine

Mode

Bases: IntEnum

Grid

Grid()

Source code in src/gridcalc/engine.py

def __init__(self) -> None:
    self.sheets: list[Sheet] = [Sheet()]
    self.active: int = 0
    self.vc: int = 0
    self.vr: int = 0
    self.tc: int = 0
    self.tr: int = 0
    self.fmt: str = ""
    self.dirty: int = 0
    self.cw: int = CW_DEFAULT
    self.filename: str | None = None
    self.names: list[NamedRange] = []
    # Named ranges bound into the PYTHON-mode eval globals on the last
    # recalc, so a name that disappears can be unbound again.
    # Workbook-persistent LP model definitions. Maps a user-chosen
    # name (or "default" for the convention slot) to an OptModel
    # holding the spec strings the user typed for sense/objective/
    # vars/constraints/bounds. Loaded from "models" in the JSON;
    # serialized back on jsonsave; consumed by the `:opt` dispatcher.
    self.models: dict[str, Any] = {}
    self.code: str = ""
    # A file's code block that the load policy refused. Never executed;
    # jsonsave writes it back so saving does not delete it.
    self.withheld_code: str = ""
    # Why the last load or save returned -1, and what the last load dropped.
    self.io_error: str | None = None
    self.load_warnings: list[str] = []
    self.mc: int = -1
    self.mr: int = -1
    self._eval_globals: dict[str, Any] = _make_eval_globals()
    self.requires: list[str] = []
    self.libs: list[str] = []
    self._module_errors: list[str] = []
    self.code_error: str | None = None
    self._mode: Mode = Mode.PYTHON
    # Topological recalc bookkeeping. Workbook-wide dep graph keyed by
    # (sheet, c, r) 3-tuples; `sheet` is the sheet name, never None for
    # entries that _refresh_deps installs (only `extract_refs` may emit
    # None transiently for unsheeted refs, but `_refresh_deps` always
    # passes a concrete sheet via formula_sheet).
    self._dep_of: dict[tuple[str | None, int, int], set[tuple[str | None, int, int]]] = {}
    self._subscribers: dict[tuple[str | None, int, int], set[tuple[str | None, int, int]]] = {}
    self._volatile: set[tuple[str | None, int, int]] = set()
    # Anchors currently rejected with #SPILL!. A blocked anchor has no
    # dependency on the cell blocking it, so any edit re-attempts every
    # blocked anchor -- cheap, since the set is normally empty.
    self._spill_blocked: set[tuple[str | None, int, int]] = set()
    # True means the graph matches the cells. Set by `_rebuild_dep_graph`,
    # kept by `_refresh_deps`/`_clear_deps`; cleared by any change the
    # incremental path misses (mode, `clear_all`, sheet rename/removal).
    # While False, the next recalc is a full one, which always rebuilds.
    self._dep_graph_built: bool = False

add_sheet

add_sheet(name: str) -> Sheet

Append a new sheet. Returns the sheet.

NOTE (phase 1): the dep graph keys are still (c, r) tuples and do not carry sheet identity. Until phase 2 (sheet-qualified references) lands, formulas on different sheets that touch the same (c, r) collide in the dep graph. Treat multi-sheet workbooks as preview-only until then.

Source code in src/gridcalc/engine.py

def add_sheet(self, name: str) -> Sheet:
    """Append a new sheet. Returns the sheet.

    NOTE (phase 1): the dep graph keys are still ``(c, r)`` tuples
    and do not carry sheet identity. Until phase 2 (sheet-qualified
    references) lands, formulas on different sheets that touch the
    same ``(c, r)`` collide in the dep graph. Treat multi-sheet
    workbooks as preview-only until then.
    """
    if any(s.name == name for s in self.sheets):
        raise ValueError(f"sheet {name!r} already exists")
    sh = Sheet(name=name)
    self.sheets.append(sh)
    return sh

move_sheet

move_sheet(name: str, new_idx: int) -> None

Reorder name to new_idx (zero-based).

Active-sheet identity is preserved: if the active sheet is the one being moved, it follows; if some other sheet is active, its index is recomputed so the same sheet stays active.

Dep graph keys carry sheet names rather than indices, so reordering doesn't invalidate the graph -- no rebuild needed.

Source code in src/gridcalc/engine.py

def move_sheet(self, name: str, new_idx: int) -> None:
    """Reorder ``name`` to ``new_idx`` (zero-based).

    Active-sheet identity is preserved: if the active sheet is the
    one being moved, it follows; if some other sheet is active, its
    index is recomputed so the same sheet stays active.

    Dep graph keys carry sheet names rather than indices, so
    reordering doesn't invalidate the graph -- no rebuild needed.
    """
    if not (0 <= new_idx < len(self.sheets)):
        raise IndexError(new_idx)
    cur_idx = next((i for i, s in enumerate(self.sheets) if s.name == name), -1)
    if cur_idx < 0:
        raise KeyError(name)
    if cur_idx == new_idx:
        return
    active_sheet = self._active
    sh = self.sheets.pop(cur_idx)
    self.sheets.insert(new_idx, sh)
    # Restore active by identity.
    self.active = self.sheets.index(active_sheet)

rename_sheet

rename_sheet(old: str, new: str) -> None

Rename a sheet and rewrite formula text that references the old name.

Walks every formula cell on every sheet and rewrites any <old>! sheet prefix to <new>!. Skips matches inside double-quoted string literals so a user formula like ="Other!A1" is left untouched. Named ranges bound to old follow it. The dep graph is marked stale; the caller recalcs.

Source code in src/gridcalc/engine.py

def rename_sheet(self, old: str, new: str) -> None:
    """Rename a sheet and rewrite formula text that references the old name.

    Walks every formula cell on every sheet and rewrites any
    ``<old>!`` sheet prefix to ``<new>!``. Skips matches inside
    double-quoted string literals so a user formula like
    ``="Other!A1"`` is left untouched. Named ranges bound to ``old``
    follow it. The dep graph is marked stale; the caller recalcs.
    """
    if old == new:
        return
    if any(s.name == new for s in self.sheets):
        raise ValueError(f"sheet {new!r} already exists")
    target = next((s for s in self.sheets if s.name == old), None)
    if target is None:
        raise KeyError(old)
    target.name = new
    # Rewrite formula text that references the old sheet name.
    for sh in self.sheets:
        for cl in sh._cells.values():
            if cl.type != FORMULA:
                continue
            rewritten = _rewrite_sheet_prefix(cl.text, old, new)
            if rewritten != cl.text:
                cl.text = rewritten
                cl.ast = None
                cl.ast_text = ""
    for nr in self.names:
        if nr.sheet == old:
            nr.sheet = new
    self._dep_graph_built = False

next_sheet

next_sheet() -> None

Advance the active sheet by one, wrapping at the end. No-op on a single-sheet workbook.

Source code in src/gridcalc/engine.py

def next_sheet(self) -> None:
    """Advance the active sheet by one, wrapping at the end. No-op
    on a single-sheet workbook."""
    n = len(self.sheets)
    if n <= 1:
        return
    self.active = (self.active + 1) % n

prev_sheet

prev_sheet() -> None

Retreat the active sheet by one, wrapping at the start. No-op on a single-sheet workbook.

Source code in src/gridcalc/engine.py

def prev_sheet(self) -> None:
    """Retreat the active sheet by one, wrapping at the start.
    No-op on a single-sheet workbook."""
    n = len(self.sheets)
    if n <= 1:
        return
    self.active = (self.active - 1) % n

load_lib

load_lib(name: str) -> None

Load a formula lib's builtins into the eval namespace.

Source code in src/gridcalc/engine.py

def load_lib(self, name: str) -> None:
    """Load a formula lib's builtins into the eval namespace."""
    if not name:
        return
    from .libs import get_lib_builtins

    self._eval_globals.update(get_lib_builtins(name))

load_requires

load_requires(
    modules: list[str], allow_unknown: bool = False
) -> None

Load required modules into the eval namespace.

allow_unknown passes through to load_modules: unclassified modules are refused unless the caller has explicitly approved them.

Source code in src/gridcalc/engine.py

def load_requires(self, modules: list[str], allow_unknown: bool = False) -> None:
    """Load required modules into the eval namespace.

    ``allow_unknown`` passes through to ``load_modules``: unclassified
    modules are refused unless the caller has explicitly approved them.
    """
    if not modules:
        return
    mods, errors = load_modules(modules, allow_unknown=allow_unknown)
    self._eval_globals.update(mods)
    self._module_errors = errors

clear_all

clear_all() -> None

Remove all cells from the active sheet.

Source code in src/gridcalc/engine.py

def clear_all(self) -> None:
    """Remove all cells from the active sheet."""
    self._cells.clear()
    self._dep_graph_built = False

setcells_bulk

setcells_bulk(
    cells: Iterable[tuple[int, int, str]],
) -> None

Set many cells, deferring recalc until all are written.

Each tuple is (col, row, text). Out-of-bounds entries are ignored. Roughly N x faster than calling setcell() N times because recalc() runs once instead of after every cell.

Source code in src/gridcalc/engine.py

def setcells_bulk(self, cells: Iterable[tuple[int, int, str]]) -> None:
    """Set many cells, deferring recalc until all are written.

    Each tuple is (col, row, text). Out-of-bounds entries are ignored.
    Roughly N x faster than calling setcell() N times because recalc()
    runs once instead of after every cell.
    """
    changed: set[tuple[int, int]] = set()
    for c, r, text in cells:
        changed |= self._spill_predirty(c, r)
        if self._setcell_no_recalc(c, r, text):
            changed.add((c, r))
    if changed:
        self.recalc(changed | self._blocked_anchors_active())

can_insert

can_insert(axis: str, at: int, count: int = 1) -> bool

True when inserting count lines at at would lose no data.

The sheet is a fixed NROW x NCOL grid, so an insert near the end pushes the last lines past the edge. Silently dropping them is data loss the user never asked for and cannot see, so callers check first and refuse. axis is "R" for rows or "C" for columns.

Source code in src/gridcalc/engine.py

def can_insert(self, axis: str, at: int, count: int = 1) -> bool:
    """True when inserting ``count`` lines at ``at`` would lose no data.

    The sheet is a fixed NROW x NCOL grid, so an insert near the end pushes
    the last lines past the edge. Silently dropping them is data loss the
    user never asked for and cannot see, so callers check first and refuse.
    ``axis`` is "R" for rows or "C" for columns.
    """
    limit = NROW if axis == "R" else NCOL
    edge = limit - count  # a line at or past this is pushed off the end
    for (c, r), cl in self._cells.items():
        if cl.type == EMPTY:
            continue
        pos = r if axis == "R" else c
        if pos >= at and pos >= edge:
            return False
    return True

insertrow

insertrow(at: int) -> bool

Insert one row at at. False, without mutating, if that would push a populated row off the bottom of the sheet.

Source code in src/gridcalc/engine.py

def insertrow(self, at: int) -> bool:
    """Insert one row at ``at``. False, without mutating, if that would push
    a populated row off the bottom of the sheet."""
    if not self.can_insert("R", at):
        return False
    self._drop_all_spills()
    new_cells: dict[tuple[int, int], Cell] = {}
    for (c, r), cl in self._cells.items():
        if r >= at:
            new_cells[(c, r + 1)] = cl
        else:
            new_cells[(c, r)] = cl
    self._cells = new_cells
    self._shiftrefs("R", at, +1)
    self._shift_names("R", at, +1)
    self._rebuild_dep_graph()
    self.dirty = 1
    return True

insertcol

insertcol(at: int) -> bool

Insert one column at at. False, without mutating, if that would push a populated column off the right edge of the sheet.

Source code in src/gridcalc/engine.py

def insertcol(self, at: int) -> bool:
    """Insert one column at ``at``. False, without mutating, if that would
    push a populated column off the right edge of the sheet."""
    if not self.can_insert("C", at):
        return False
    self._drop_all_spills()
    new_cells: dict[tuple[int, int], Cell] = {}
    for (c, r), cl in self._cells.items():
        if c >= at:
            new_cells[(c + 1, r)] = cl
        else:
            new_cells[(c, r)] = cl
    self._cells = new_cells
    self._shiftrefs("C", at, +1)
    self._shift_names("C", at, +1)
    self._shift_widths(at, +1)
    self._rebuild_dep_graph()
    self.dirty = 1
    return True

csvsave

csvsave(filename: str) -> int

Export evaluated cell values to CSV.

Source code in src/gridcalc/engine.py

def csvsave(self, filename: str) -> int:
    """Export evaluated cell values to CSV."""
    maxr = -1
    maxc = -1
    for (c, r), sc in self._cells.items():
        if sc.type != EMPTY:
            if r > maxr:
                maxr = r
            if c > maxc:
                maxc = c

    def value(cl: Cell | None) -> str:
        if not cl or cl.type == EMPTY:
            return ""
        if cl.type == LABEL:
            return cl.text[1:] if cl.text.startswith('"') else cl.text
        if cl.err is not None:
            return ""
        if cl.sval is not None:
            return cl.sval  # a text or boolean result
        v = cl.val
        if isinstance(v, float) and math.isnan(v):
            return ""
        return str(int(v)) if abs(v) < 1e15 and v == int(v) else repr(float(v))

    def write(path: str) -> None:
        with open(path, "w", newline="", encoding="utf-8") as f:
            writer = csv.writer(f)
            for r in range(maxr + 1):
                writer.writerow([value(self._cells.get((c, r))) for c in range(maxc + 1)])

    return self._save_via(filename, write)

csvload

csvload(filename: str) -> int

Import cells from a CSV file. Numbers become NUM cells, rest become LABELs.

Source code in src/gridcalc/engine.py

def csvload(self, filename: str) -> int:
    """Import cells from a CSV file. Numbers become NUM cells, rest become LABELs."""
    self.io_error = None
    try:
        with open(filename, newline="", encoding="utf-8") as f:
            content = f.read()
    except (OSError, UnicodeDecodeError) as exc:
        self.io_error = str(exc)
        return -1

    reader = csv.reader(StringIO(content))
    cells: list[tuple[int, int, str]] = []
    for r_idx, row in enumerate(reader):
        if r_idx >= NROW:
            break
        for c_idx, val in enumerate(row):
            if c_idx >= NCOL:
                break
            val = val.strip()
            if val:
                cells.append((c_idx, r_idx, val))
    # One recalc: a PYTHON-mode recalc per setcell made this quadratic.
    self.setcells_bulk(cells)
    return 0

pdload

pdload(filename: str, header: bool = True) -> int

Load a CSV, TSV or JSON file into grid cells using pandas.

CSV and TSV fields are parsed as typed input, as csvload does. JSON values keep their type: a string stays a label, a boolean becomes =TRUE/=FALSE. header writes JSON column names into row 0. Returns -1 if pandas is not installed or the file type is unsupported.

Source code in src/gridcalc/engine.py

def pdload(self, filename: str, header: bool = True) -> int:
    """Load a CSV, TSV or JSON file into grid cells using pandas.

    CSV and TSV fields are parsed as typed input, as ``csvload`` does. JSON
    values keep their type: a string stays a label, a boolean becomes
    ``=TRUE``/``=FALSE``. ``header`` writes JSON column names into row 0.
    Returns -1 if pandas is not installed or the file type is unsupported.
    """
    try:
        import pandas as pd  # noqa: I001
    except ImportError:
        return -1

    self.io_error = None
    ext = os.path.splitext(filename)[1].lower()
    if ext not in _PD_EXTS:
        self.io_error = f"unsupported file type: {ext}"
        return -1
    try:
        if ext == ".json":
            df = pd.read_json(filename, dtype=False, convert_dates=False, precise_float=True)
        else:
            # All fields as text: pandas' NA markers and float parser would
            # drop "NA" labels and round 0.30000000000000004. Fixed `names`
            # pad short rows and cut long ones at NCOL, as `csvload` does.
            sep = "\t" if ext in (".tsv", ".tab") else ","
            with warnings.catch_warnings():
                warnings.simplefilter("ignore", pd.errors.ParserWarning)
                df = pd.read_csv(
                    filename,
                    sep=sep,
                    header=None,
                    names=range(NCOL),
                    index_col=False,
                    dtype=str,
                    keep_default_na=False,
                )
    except Exception as exc:  # noqa: BLE001
        self.io_error = str(exc) or type(exc).__name__
        return -1

    def label(v: object) -> str:
        t = str(v)
        return '"' + t if t.startswith("=") or parse_number(t.rstrip()) is not None else t

    def json_text(v: object) -> str:
        if isinstance(v, bool):
            t = "TRUE" if v else "FALSE"
            return "=" + (t.title() if self.mode == Mode.PYTHON else t)
        if isinstance(v, int):
            return str(v)
        if isinstance(v, float):
            return _number_text(v) if math.isfinite(v) else ""
        return label(v)

    rows: list[tuple[Any, ...]] = list(df.itertuples(index=False, name=None))
    if ext == ".json" and header:
        rows.insert(0, tuple(df.columns))
    cells: list[tuple[int, int, str]] = []
    for r, row in enumerate(rows[:NROW]):
        for c, v in enumerate(row[:NCOL]):
            if v is None or (isinstance(v, float) and math.isnan(v)):
                continue
            text = json_text(v) if ext == ".json" else str(v).strip()
            if text:
                cells.append((c, r, text))
    self.setcells_bulk(cells)
    return 0

pdsave

pdsave(filename: str) -> int

Export grid values to a CSV, TSV or JSON file, with row 0 as headers.

Returns -1 if pandas is not installed, the file type is unsupported, or JSON headers repeat.

Source code in src/gridcalc/engine.py

def pdsave(self, filename: str) -> int:
    """Export grid values to a CSV, TSV or JSON file, with row 0 as headers.

    Returns -1 if pandas is not installed, the file type is unsupported, or
    JSON headers repeat.
    """
    try:
        import pandas as pd  # noqa: I001
    except ImportError:
        return -1

    self.io_error = None
    ext = os.path.splitext(filename)[1].lower()
    if ext not in _PD_EXTS:
        self.io_error = f"unsupported file type: {ext}"
        return -1

    maxr = -1
    maxc = -1
    for (c, r), sc in self._cells.items():
        if sc.type != EMPTY:
            if r > maxr:
                maxr = r
            if c > maxc:
                maxc = c

    if maxr < 0:
        return -1

    def value(cl: Cell | None) -> Any:
        if not cl or cl.type == EMPTY:
            return None
        if cl.type == LABEL:
            return cl.text[1:] if cl.text.startswith('"') else cl.text
        if cl.err is not None:
            return None
        if isinstance(cl.val, bool):
            return cl.val if ext == ".json" else ("TRUE" if cl.val else "FALSE")
        if cl.sval is not None:
            return cl.sval  # a text result; val is a 0 placeholder
        v = float(cl.val)
        if not math.isfinite(v):
            return None
        return int(v) if v.is_integer() and abs(v) < 1e15 else v

    columns = [
        str(h) if (h := value(self._cells.get((c, 0)))) is not None else col_name(c)
        for c in range(maxc + 1)
    ]
    data = [
        [value(self._cells.get((c, r))) for c in range(maxc + 1)] for r in range(1, maxr + 1)
    ]

    if ext == ".json" and len(set(columns)) < len(columns):
        self.io_error = "JSON export needs unique headers in row 1"
        return -1

    def write(path: str) -> None:
        if ext == ".json":
            # pandas' to_json rounds floats to at most 15 digits.
            with open(path, "w", encoding="utf-8") as f:
                records = [dict(zip(columns, row, strict=True)) for row in data]
                json.dump(records, f, indent=2, allow_nan=False)
        else:
            sep = "\t" if ext in (".tsv", ".tab") else ","
            df = pd.DataFrame(data, columns=columns, dtype=object)
            df.to_csv(path, sep=sep, index=False)

    return self._save_via(filename, write)

Sheet

Sheet(name: str = 'Sheet1')

A single named sheet's cell store, cycle set, and cursor.

Workbook-level state (mode, code, named ranges, dep graph, etc.) lives on Grid; each Sheet only owns the data that varies per-tab. Grid exposes _cells / cells / cc / cr / _circular as properties that delegate to sheets[active] so existing single-sheet code keeps working unchanged.

Source code in src/gridcalc/engine.py

def __init__(self, name: str = "Sheet1") -> None:
    self.name: str = name
    self._cells: dict[tuple[int, int], Cell] = {}
    self._circular: set[tuple[int, int]] = set()
    self.cc: int = 0
    self.cr: int = 0
    # Per-column display widths in pixels, keyed by column index; absent
    # columns use the frontend's default. A *pixel* map is deliberately
    # not the same thing as `Grid.cw`, which is a uniform width in
    # character cells: the curses renderer lays columns out by multiplying
    # that one number and has no notion of a per-column size, so it
    # ignores this. Written by the web view, which does, and carried
    # through save/load so a resize survives the session.
    self.widths: dict[int, int] = {}

Cell

Cell()

Source code in src/gridcalc/engine.py

def __init__(self) -> None:
    self.type: int = EMPTY
    # A bool for a boolean formula result (with `sval` "TRUE"/"FALSE"), so
    # a reader can tell it from the text "TRUE"; numerically still 1/0.
    self.val: float = 0.0
    self.sval: str | None = None
    self.arr: list[float] | None = None
    # When arr holds a 2D Vec result, arr_cols is the column count.
    # None means 1D (or no array).
    self.arr_cols: int | None = None
    self.matrix: Any = None
    # Spill bookkeeping. `spill_parent` is the (col, row) anchor of a
    # SPILL cell; None for every other cell. `spill_shape` is the
    # (rows, cols) rectangle a spilling anchor currently occupies;
    # None when the cell is not an anchor or is not spilling.
    self.spill_parent: tuple[int, int] | None = None
    self.spill_shape: tuple[int, int] | None = None
    self.text: str = ""
    self.fmt: str = ""
    self.bold: int = 0
    self.underline: int = 0
    self.italic: int = 0
    self.fmtstr: str = ""
    self.ast: Any = None
    self.ast_text: str = ""
    self.err: Any = None
    self.err_msg: str | None = None

Vec

Vec(data: Iterable[Any], cols: int | None = None)

Source code in src/gridcalc/engine.py

def __init__(self, data: Iterable[Any], cols: int | None = None) -> None:
    self.data: list[Any] = list(data)
    # Number of columns when this Vec materialises a 2D range (row-major).
    # None means shape is unknown / treat as 1D. Set by _eval_range when
    # building from a RangeRef so INDEX(rng, row, col) can re-index.
    self.cols: int | None = cols

rows property

rows: int

Row count. For 1D Vecs this is the flat length.

shape property

shape: tuple[int, int]

(rows, cols). 1D Vecs report (len, 1).

at

at(r: int, c: int) -> Any

1-based 2D access. Treats a 1D Vec as a column vector (n×1) so at(i, 1) walks the flat data.

Source code in src/gridcalc/engine.py

def at(self, r: int, c: int) -> Any:
    """1-based 2D access. Treats a 1D Vec as a column vector (n×1)
    so ``at(i, 1)`` walks the flat data."""
    rows, cols = self.shape
    if not 1 <= r <= rows or not 1 <= c <= cols:
        raise IndexError(f"Vec.at({r},{c}) out of range for shape {self.shape}")
    if not self.is_2d:
        return self.data[r - 1]
    assert self.cols is not None  # noqa: S101 -- type-narrowing after is_2d guard
    return self.data[(r - 1) * self.cols + (c - 1)]

row

row(i: int) -> Vec

1-based row extraction. Returns a 1D Vec.

A 1D Vec is treated as a column vector (n×1), so row(i) returns a 1-element Vec for valid i.

Source code in src/gridcalc/engine.py

def row(self, i: int) -> Vec:
    """1-based row extraction. Returns a 1D Vec.

    A 1D Vec is treated as a column vector (n×1), so ``row(i)``
    returns a 1-element Vec for valid ``i``.
    """
    rows, _ = self.shape
    if not 1 <= i <= rows:
        raise IndexError(f"Vec.row({i}) out of range for shape {self.shape}")
    if not self.is_2d:
        return Vec([self.data[i - 1]])
    assert self.cols is not None  # noqa: S101 -- type-narrowing after is_2d guard
    start = (i - 1) * self.cols
    return Vec(self.data[start : start + self.cols])

col

col(j: int) -> Vec

1-based column extraction. Returns a 1D Vec.

A 1D Vec is treated as a column vector (n×1), so col(1) returns the whole vec; other indices raise.

Source code in src/gridcalc/engine.py

def col(self, j: int) -> Vec:
    """1-based column extraction. Returns a 1D Vec.

    A 1D Vec is treated as a column vector (n×1), so ``col(1)``
    returns the whole vec; other indices raise.
    """
    _, cols = self.shape
    if not 1 <= j <= cols:
        raise IndexError(f"Vec.col({j}) out of range for shape {self.shape}")
    if not self.is_2d:
        return Vec(list(self.data))
    assert self.cols is not None  # noqa: S101 -- type-narrowing after is_2d guard
    return Vec([self.data[i * self.cols + (j - 1)] for i in range(self.rows)])

iter_rows

iter_rows() -> Iterator[list[Any]]

Iterate rows as plain lists. A 1D Vec is treated as column-shaped (n×1), so each element yields its own 1-element row.

Source code in src/gridcalc/engine.py

def iter_rows(self) -> Iterator[list[Any]]:
    """Iterate rows as plain ``list``s. A 1D Vec is treated as
    column-shaped (n×1), so each element yields its own 1-element row."""
    if not self.is_2d:
        for v in self.data:
            yield [v]
        return
    assert self.cols is not None  # noqa: S101 -- type-narrowing after is_2d guard
    for i in range(self.rows):
        yield list(self.data[i * self.cols : (i + 1) * self.cols])

NamedRange

NamedRange(
    name: str = "",
    c1: int = 0,
    r1: int = 0,
    c2: int = 0,
    r2: int = 0,
    sheet: str | None = None,
)

Source code in src/gridcalc/engine.py

def __init__(
    self,
    name: str = "",
    c1: int = 0,
    r1: int = 0,
    c2: int = 0,
    r2: int = 0,
    sheet: str | None = None,
) -> None:
    self.name = name
    self.c1 = c1
    self.r1 = r1
    self.c2 = c2
    self.r2 = r2
    # Sheet the range lives on, or None for a sheet-agnostic name that
    # resolves against whichever sheet the referencing formula is on
    # (the historical gridcalc behaviour; xlsx imports set it explicitly).
    self.sheet = sheet

ref

ref(s: str) -> tuple[int, int, int] | None

Parse a cell reference. Returns (chars_consumed, col, row) or None.

Source code in src/gridcalc/engine.py

def ref(s: str) -> tuple[int, int, int] | None:
    """Parse a cell reference. Returns (chars_consumed, col, row) or None."""
    result = refabs(s)
    if result is None:
        return None
    n, col, row, _, _ = result
    return (n, col, row)

refabs

refabs(s: str) -> RefMatch | None

Parse a cell reference at the start of s.

Returns a RefMatch (still tuple-unpackable as n, col, row, abs_col, abs_row), or None if no ref matches.

Source code in src/gridcalc/engine.py

def refabs(s: str) -> RefMatch | None:
    """Parse a cell reference at the start of `s`.

    Returns a `RefMatch` (still tuple-unpackable as
    `n, col, row, abs_col, abs_row`), or None if no ref matches.
    """
    m = _REF_RE.match(s)
    if not m:
        return None
    absc = 1 if m.group(1) == "$" else 0
    letters = m.group(2).upper()
    absr = 1 if m.group(3) == "$" else 0
    rownum = int(m.group(4))
    if rownum <= 0:
        return None
    col = 0
    for ch in letters:
        col = col * 26 + (ord(ch) - ord("A") + 1)
    col -= 1
    row = rownum - 1
    return RefMatch(m.end(), col, row, absc, absr)

col_name

col_name(c: int) -> str

Source code in src/gridcalc/engine.py

def col_name(c: int) -> str:
    if c < 26:
        return chr(ord("A") + c)
    return chr(ord("A") + c // 26 - 1) + chr(ord("A") + c % 26)

cellname

cellname(c: int, r: int) -> str

Source code in src/gridcalc/engine.py

def cellname(c: int, r: int) -> str:
    return f"{col_name(c)}{r + 1}"

adjust_refs

adjust_refs(text: str, dcol: int, drow: int) -> str

Shift every relative cell reference in text by (dcol, drow).

Absolute ($-prefixed) columns/rows are left unchanged. Used both by replicate (copy a formula across the grid) and by the frontends' paste, so the two share one definition of reference adjustment.

Source code in src/gridcalc/engine.py

def adjust_refs(text: str, dcol: int, drow: int) -> str:
    """Shift every relative cell reference in ``text`` by ``(dcol, drow)``.

    Absolute (``$``-prefixed) columns/rows are left unchanged. Used both by
    replicate (copy a formula across the grid) and by the frontends' paste, so
    the two share one definition of reference adjustment.
    """
    out = []
    i = 0
    while i < len(text):
        end = _skip_quoted(text, i)
        if end is not None:
            out.append(text[i:end])  # a literal is copied through untouched
            i = end
            continue
        result = _ref_at(text, i)
        if result:
            n, rc, rr, ac, ar = result
            if not ac:
                rc += dcol
            if not ar:
                rr += drow
            out.append(_emitref(rc, rr, ac, ar))
            i += n
        else:
            out.append(text[i])
            i += 1
    return "".join(out)