datalayer-cells 0.0.2__py3-none-any.whl

datalayer_cells/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2022-2026 Datalayer, Inc.
+#
+# MIT License
+
+"""Datalayer Cells for Python: read and write Cells workbooks, as agents do.
+
+The ``CellsWorkbook`` JSON format with the same validation as
+``@datalayer/cells``, and the ``datalayer cells`` command. Live rooms
+(the Loro schema) come with the collaboration milestone.
+"""
+
+from .__version__ import __version__
+from .format import CELL_ERRORS, FORMAT_VERSION, FormatError, validate_workbook
+from .workbook import Workbook, column_index, column_letters, parse_a1, parse_input, parse_zone
+
+__all__ = [
+    "CELL_ERRORS",
+    "FORMAT_VERSION",
+    "FormatError",
+    "Workbook",
+    "__version__",
+    "column_index",
+    "column_letters",
+    "parse_a1",
+    "parse_input",
+    "parse_zone",
+    "validate_workbook",
+]

datalayer_cells/__version__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2022-2026 Datalayer, Inc.
+#
+# MIT License
+
+"""The version of datalayer_cells; dev/bump_version.py moves it with package.json."""
+
+__version__ = "0.0.2"

datalayer_cells/cli.py

@@ -0,0 +1,167 @@
+# Copyright (c) 2022-2026 Datalayer, Inc.
+#
+# MIT License
+
+"""``datalayer cells``: read and write Cells workbooks from a terminal.
+
+Two doors to the same commands, as Datalayer's other packages have:
+installed beside the Datalayer CLI, the ``cells`` group joins the
+``datalayer`` command through the ``datalayer.cli`` entry point; on its own,
+``datalayer-cells`` runs it.
+
+    datalayer cells show budget.cells.json            # the sheets and their used ranges
+    datalayer cells get budget.cells.json 'Summary!A1:C4'
+    datalayer cells set budget.cells.json B2 12 '=B1*2'
+    datalayer cells export budget.cells.json --sheet Summary --format csv
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from pathlib import Path
+from typing import Any, List, Optional
+
+import typer
+from reactor import PluginManifest
+
+from .__version__ import __version__
+from .format import FormatError
+from .workbook import Workbook, column_letters, parse_input
+
+app = typer.Typer(
+    name="cells",
+    help="Read and write Datalayer Cells workbooks (.cells.json).",
+    no_args_is_help=True,
+)
+
+
+def _load(path: Path) -> Workbook:
+    try:
+        return Workbook.load(path)
+    except (OSError, FormatError) as error:
+        typer.echo(f"Cannot read {path}: {error}", err=True)
+        raise typer.Exit(1) from error
+
+
+def _show(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, dict):
+        return str(value.get("error"))
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    return str(value)
+
+
+@app.command()
+def show(path: Path) -> None:
+    """The sheets of a workbook, and the range each one uses."""
+    wb = _load(path)
+    for sheet in wb.to_json()["sheets"]:
+        rows = [int(r) for r in sheet["rows"]]
+        cols = [int(c) for row in sheet["rows"].values() for c in row["cells"]]
+        used = f"A1:{column_letters(max(cols))}{max(rows) + 1}" if rows and cols else "empty"
+        count = sum(len(row["cells"]) for row in sheet["rows"].values())
+        typer.echo(f"{sheet['name']}\t{used}\t{count} cells")
+
+
+@app.command()
+def get(path: Path, ref: str, formulas: bool = typer.Option(False, "--formulas", help="Show formulas as typed.")) -> None:
+    """The values (or formulas) of a range, tab-separated."""
+    wb = _load(path)
+    try:
+        rows = wb.read(ref)
+        typed = wb.formulas(ref) if formulas else None
+    except (KeyError, ValueError) as error:
+        typer.echo(str(error).strip('"'), err=True)
+        raise typer.Exit(1) from error
+    for r, row in enumerate(rows):
+        typer.echo("\t".join(typed[r][c] or _show(v) if typed else _show(v) for c, v in enumerate(row)))
+
+
+@app.command(name="set")
+def set_(
+    path: Path,
+    ref: str,
+    values: List[str] = typer.Argument(..., help="Values for a row from REF, typed as in a cell: 12, TRUE, =A1*2, 'text."),
+) -> None:
+    """Write a row of values from a cell, as typing them would, and save."""
+    wb = _load(path)
+    row: list[Any] = []
+    for text in values:
+        parsed = parse_input(text)
+        row.append(f"={parsed['f']}" if "f" in parsed else parsed.get("v"))
+    try:
+        wb.write(ref, [row])
+    except (KeyError, ValueError) as error:
+        typer.echo(str(error).strip('"'), err=True)
+        raise typer.Exit(1) from error
+    wb.save(path)
+    typer.echo(f"Wrote {len(row)} cell(s) from {ref}.")
+
+
+@app.command()
+def export(
+    path: Path,
+    sheet: Optional[str] = typer.Option(None, help="The sheet to export (the first by default)."),
+    format: str = typer.Option("csv", help="csv or json."),
+) -> None:
+    """A sheet as CSV (values) or the workbook as canonical JSON, on standard output."""
+    wb = _load(path)
+    if format == "json":
+        typer.echo(json.dumps(wb.to_json(), indent=2))
+        return
+    if format != "csv":
+        typer.echo(f"No export format '{format}': csv or json.", err=True)
+        raise typer.Exit(1)
+    data = wb.to_json()
+    names = [s["name"] for s in data["sheets"]]
+    chosen = sheet or names[0]
+    match = [s for s in data["sheets"] if s["name"].lower() == chosen.lower()]
+    if not match:
+        typer.echo(f"No sheet '{chosen}'; the workbook has {', '.join(names)}.", err=True)
+        raise typer.Exit(1)
+    rows = match[0]["rows"]
+    if not rows:
+        return
+    height = max(int(r) for r in rows) + 1
+    width = max(int(c) for row in rows.values() for c in row["cells"]) + 1
+    quoted = "'" + match[0]["name"].replace("'", "''") + "'"
+    values = wb.read(f"{quoted}!A1:{column_letters(width - 1)}{height}")
+    out = io.StringIO()
+    csv.writer(out, lineterminator="\n").writerows([[_show(v) for v in row] for row in values])
+    typer.echo(out.getvalue(), nl=False)
+
+
+@app.command()
+def version() -> None:
+    """The version of datalayer_cells."""
+    typer.echo(__version__)
+
+
+class CellsCliExtension:
+    """The plugin: registers the ``cells`` group into the host CLI."""
+
+    def provide_cli(self, cli: "typer.Typer") -> None:
+        cli.add_typer(app, name="cells")
+
+
+manifest = PluginManifest(
+    name="cells-cli",
+    version=__version__,
+    description="The `cells` command group: show, get, set, export.",
+    author="Datalayer",
+    tags=["cli", "cells"],
+)
+
+
+def plugin() -> tuple[PluginManifest, CellsCliExtension]:
+    """What the ``datalayer.cli`` entry point resolves to."""
+    return manifest, CellsCliExtension()
+
+
+def main() -> None:
+    """The ``datalayer-cells`` console script: the same group, on its own."""
+    app()

datalayer_cells/format.py

@@ -0,0 +1,260 @@
+# Copyright (c) 2022-2026 Datalayer, Inc.
+#
+# MIT License
+
+"""The ``CellsWorkbook`` format: validation with the TypeScript loader's refusals.
+
+A file that does not match is refused with a sentence naming the path of the
+first bad field, the same sentence ``@datalayer/cells`` gives; both read the
+shared corpus under ``tests/format`` to keep it so.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from typing import Any
+
+FORMAT_VERSION = 1
+
+#: The errors a cell can hold, as Excel spells them (``#CYCLE!`` and ``#BUSY!`` are Cells').
+CELL_ERRORS = (
+    "#DIV/0!",
+    "#REF!",
+    "#NAME?",
+    "#VALUE!",
+    "#N/A",
+    "#NUM!",
+    "#NULL!",
+    "#CYCLE!",
+    "#BUSY!",
+    "#SPILL!",
+)
+
+STYLE_KEYS = (
+    "font",
+    "size",
+    "bold",
+    "italic",
+    "underline",
+    "strike",
+    "color",
+    "fill",
+    "align",
+    "valign",
+    "wrap",
+    "borders",
+    "format",
+)
+
+#: The number formats Cells shows today; a style with another is refused, as in TypeScript.
+BUILT_IN_FORMATS = (
+    "General",
+    "0",
+    "0.00",
+    "#,##0",
+    "#,##0.00",
+    "0%",
+    "0.00%",
+    "yyyy-mm-dd",
+    "hh:mm",
+    "yyyy-mm-dd hh:mm",
+    "@",
+)
+
+#: Excel's grid, as the TypeScript model's default limits.
+DEFAULT_LIMITS = {"rows": 1_048_576, "cols": 16_384}
+
+_INDEX = re.compile(r"^(0|[1-9][0-9]*)$")
+
+
+class FormatError(ValueError):
+    """A file refused: the message names the path of the first bad field."""
+
+
+def _fail(path: str, message: str) -> None:
+    raise FormatError(f"{path}: {message}")
+
+
+def _js(value: Any) -> str:
+    """What JavaScript's JSON.stringify prints, for messages that quote a value."""
+    if isinstance(value, float) and value.is_integer() and not isinstance(value, bool):
+        return str(int(value))
+    if value is None:
+        return "undefined"
+    return json.dumps(value, separators=(",", ":"))
+
+
+def _is_object(x: Any) -> bool:
+    return isinstance(x, dict)
+
+
+def _is_int(x: Any) -> bool:
+    return (isinstance(x, int) and not isinstance(x, bool)) or (isinstance(x, float) and x.is_integer())
+
+
+def _is_number(x: Any) -> bool:
+    return isinstance(x, (int, float)) and not isinstance(x, bool)
+
+
+def _is_index(key: str, maximum: int) -> bool:
+    return bool(_INDEX.match(key)) and int(key) < maximum
+
+
+def check_style(style: Any, where: str = "style") -> None:
+    if not _is_object(style):
+        _fail(where, "a style is an object.")
+    for key in style:
+        if key not in STYLE_KEYS:
+            raise FormatError(f"{where}: '{key}' is not a style property ({', '.join(STYLE_KEYS)}).")
+    for key in ("bold", "italic", "underline", "strike", "wrap"):
+        if key in style and not isinstance(style[key], bool):
+            raise FormatError(f"{where}.{key}: true or false.")
+    for key in ("font", "color", "fill", "format"):
+        if key in style and not isinstance(style[key], str):
+            raise FormatError(f"{where}.{key}: a string.")
+    if "format" in style and style["format"] not in BUILT_IN_FORMATS:
+        raise FormatError(
+            f"{where}.format: '{style['format']}' is not one of the built-in formats "
+            f"({', '.join(BUILT_IN_FORMATS)}); the full grammar is not built yet."
+        )
+    if "size" in style and not (_is_number(style["size"]) and style["size"] > 0):
+        raise FormatError(f"{where}.size: a positive number.")
+    if "align" in style and style["align"] not in ("left", "center", "right"):
+        raise FormatError(f"{where}.align: left, center or right.")
+    if "valign" in style and style["valign"] not in ("top", "middle", "bottom"):
+        raise FormatError(f"{where}.valign: top, middle or bottom.")
+
+
+def _check_value(v: Any, path: str) -> None:
+    if v is None or isinstance(v, (str, bool)):
+        return
+    if _is_number(v):
+        if not math.isfinite(v):
+            _fail(path, f"{v} is not a value")
+        return
+    if _is_object(v) and isinstance(v.get("error"), str) and len(v) == 1:
+        if v["error"] not in CELL_ERRORS:
+            _fail(path, f"'{v['error']}' is not an error code")
+        return
+    _fail(path, f"{_js(v)} is not a value (a number, a string, a boolean, null or {{ error }})")
+
+
+def _check_zone(z: Any, path: str, limits: dict[str, int]) -> None:
+    if not _is_object(z):
+        _fail(path, "a zone is { top, left, bottom, right }")
+    for k in ("top", "left", "bottom", "right"):
+        if not _is_int(z.get(k)) or z[k] < 0:
+            _fail(f"{path}.{k}", "a non-negative integer")
+    if z["top"] > z["bottom"] or z["left"] > z["right"]:
+        _fail(path, "top-left after bottom-right")
+    if z["bottom"] >= limits["rows"] or z["right"] >= limits["cols"]:
+        _fail(path, "outside the sheet")
+
+
+def validate_workbook(data: Any, limits: dict[str, int] | None = None) -> dict[str, Any]:
+    """Return ``data`` when it is a valid CellsWorkbook; raise :class:`FormatError` otherwise."""
+    limits = limits or DEFAULT_LIMITS
+    if not _is_object(data):
+        _fail("workbook", "a CellsWorkbook is a JSON object")
+    if data.get("version") != FORMAT_VERSION or isinstance(data.get("version"), bool):
+        _fail("version", f"this is format version {_js(data.get('version'))}; Cells reads version {FORMAT_VERSION}")
+    styles = data.get("styles", [])
+    if not isinstance(styles, list):
+        _fail("styles", "a list")
+    for i, s in enumerate(styles):
+        check_style(s, f"styles[{i}]")
+    if styles and len(styles[0]) > 0:
+        _fail("styles[0]", "style 0 is the default: {}")
+    sheets = data.get("sheets")
+    if not isinstance(sheets, list) or not sheets:
+        _fail("sheets", "a non-empty list")
+    ids: set[str] = set()
+    names: set[str] = set()
+    for i, sheet in enumerate(sheets):
+        p = f"sheets[{i}]"
+        if not _is_object(sheet):
+            _fail(p, "a sheet is an object")
+        sid = sheet.get("id")
+        if not isinstance(sid, str) or sid == "":
+            _fail(f"{p}.id", "a non-empty string")
+        if sid in ids:
+            _fail(f"{p}.id", f"'{sid}' is used twice")
+        ids.add(sid)
+        name = sheet.get("name")
+        if not isinstance(name, str) or name.strip() == "":
+            _fail(f"{p}.name", "a non-empty string")
+        if name.lower() in names:
+            _fail(f"{p}.name", f"'{name}' is used twice")
+        names.add(name.lower())
+        rows = sheet.get("rows")
+        if not _is_object(rows):
+            _fail(f"{p}.rows", "an object keyed by row index")
+        for r, row in rows.items():
+            rp = f'{p}.rows["{r}"]'
+            if not _is_index(r, limits["rows"]):
+                _fail(rp, f"'{r}' is not a row index below {limits['rows']}")
+            if not _is_object(row) or not _is_object(row.get("cells")):
+                _fail(rp, "a row is { cells: { … } }")
+            for c, cell in row["cells"].items():
+                cp = f'{rp}.cells["{c}"]'
+                if not _is_index(c, limits["cols"]):
+                    _fail(cp, f"'{c}' is not a column index below {limits['cols']}")
+                if not _is_object(cell):
+                    _fail(cp, "a cell is { v?, f?, s? }")
+                for k in cell:
+                    if k not in ("v", "f", "s"):
+                        _fail(f"{cp}.{k}", "a cell has v, f and s only")
+                if "v" in cell:
+                    _check_value(cell["v"], f"{cp}.v")
+                if "f" in cell and (not isinstance(cell["f"], str) or cell["f"] == ""):
+                    _fail(f"{cp}.f", "a formula without the =")
+                if "s" in cell:
+                    s = cell["s"]
+                    if not _is_int(s) or s < 0 or s >= max(1, len(styles)):
+                        _fail(f"{cp}.s", f"no style {_js(s)}")
+        sizes = sheet.get("sizes")
+        if sizes is not None:
+            if not _is_object(sizes):
+                _fail(f"{p}.sizes", "{ rows?, cols? }")
+            for axis in ("rows", "cols"):
+                if axis not in sizes:
+                    continue
+                if not _is_object(sizes[axis]):
+                    _fail(f"{p}.sizes.{axis}", "an object keyed by index")
+                for k, v in sizes[axis].items():
+                    if not _is_index(k, limits[axis]):
+                        _fail(f'{p}.sizes.{axis}["{k}"]', "not an index of the sheet")
+                    if not (_is_number(v) and v > 0 and math.isfinite(v)):
+                        _fail(f'{p}.sizes.{axis}["{k}"]', "a positive size")
+        hidden = sheet.get("hidden")
+        if hidden is not None:
+            if not _is_object(hidden):
+                _fail(f"{p}.hidden", "{ rows?, cols? }")
+            for axis in ("rows", "cols"):
+                if axis not in hidden:
+                    continue
+                if not isinstance(hidden[axis], list):
+                    _fail(f"{p}.hidden.{axis}", "a list of indexes")
+                for j, x in enumerate(hidden[axis]):
+                    if not _is_int(x) or x < 0 or x >= limits[axis]:
+                        _fail(f"{p}.hidden.{axis}[{j}]", "not an index of the sheet")
+        merges = sheet.get("merges")
+        if merges is not None:
+            if not isinstance(merges, list):
+                _fail(f"{p}.merges", "a list of zones")
+            for j, z in enumerate(merges):
+                _check_zone(z, f"{p}.merges[{j}]", limits)
+        frozen = sheet.get("frozen")
+        if frozen is not None:
+            ok = (
+                _is_object(frozen)
+                and _is_int(frozen.get("rows"))
+                and _is_int(frozen.get("cols"))
+                and frozen["rows"] >= 0
+                and frozen["cols"] >= 0
+            )
+            if not ok:
+                _fail(f"{p}.frozen", "{ rows, cols }, non-negative integers")
+    return data

datalayer_cells/workbook.py

@@ -0,0 +1,308 @@
+# Copyright (c) 2022-2026 Datalayer, Inc.
+#
+# MIT License
+
+"""A workbook as an agent reads and writes it: values and formulas by A1 reference.
+
+    wb = Workbook.load("budget.cells.json")
+    wb.read("Summary!A1:C4")              # rows of values
+    wb.write("B2", [[12, "=B1*2"]])       # a block from B2
+    wb.save("budget.cells.json")
+
+Formulas are kept as typed and are not evaluated here, as in the TypeScript
+model until its formula engine lands: reading a formula cell gives its cached
+value, ``None`` when it has none.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from pathlib import Path
+from typing import Any, Union
+
+from .format import CELL_ERRORS, DEFAULT_LIMITS, FORMAT_VERSION, FormatError, check_style, validate_workbook
+
+Value = Union[float, int, str, bool, None, dict]
+
+_CELL = re.compile(r"^\$?([A-Za-z]{1,3})\$?([1-9][0-9]{0,6})$")
+
+
+def column_index(letters: str) -> int:
+    """``A`` → 0, ``AA`` → 26."""
+    if not re.fullmatch(r"[A-Za-z]{1,3}", letters):
+        raise ValueError(f"'{letters}' is not a column (A to XFD).")
+    n = 0
+    for ch in letters.upper():
+        n = n * 26 + (ord(ch) - 64)
+    return n - 1
+
+
+def column_letters(col: int) -> str:
+    """0 → ``A``, 26 → ``AA``."""
+    if col < 0:
+        raise ValueError(f"No column at index {col}.")
+    name = ""
+    n = col + 1
+    while n > 0:
+        n, rest = divmod(n - 1, 26)
+        name = chr(65 + rest) + name
+    return name
+
+
+def parse_a1(text: str) -> tuple[int, int]:
+    """``B3`` → (row 2, col 1)."""
+    m = _CELL.match(text.strip())
+    if not m:
+        raise ValueError(f"'{text}' is not a cell reference such as B3.")
+    return int(m.group(2)) - 1, column_index(m.group(1))
+
+
+def split_sheet(ref: str) -> tuple[str | None, str]:
+    """``'My sheet'!A1:B2`` → (``My sheet``, ``A1:B2``)."""
+    bang = ref.rfind("!")
+    if bang < 0:
+        return None, ref
+    sheet = ref[:bang]
+    if sheet.startswith("'"):
+        if not sheet.endswith("'") or len(sheet) < 2:
+            raise ValueError(f"'{ref}' has an unclosed sheet name.")
+        sheet = sheet[1:-1].replace("''", "'")
+    if sheet == "":
+        raise ValueError(f"'{ref}' names an empty sheet.")
+    return sheet, ref[bang + 1 :]
+
+
+def parse_zone(text: str) -> tuple[int, int, int, int]:
+    """``A1:C4`` → (top, left, bottom, right), 0-based and inclusive."""
+    parts = text.strip().split(":")
+    if len(parts) > 2 or parts[0] == "":
+        raise ValueError(f"'{text}' is not a range such as A1:C4.")
+    r0, c0 = parse_a1(parts[0])
+    r1, c1 = parse_a1(parts[1]) if len(parts) == 2 else (r0, c0)
+    return min(r0, r1), min(c0, c1), max(r0, r1), max(c0, c1)
+
+
+def is_error(value: Any) -> bool:
+    return isinstance(value, dict) and set(value) == {"error"} and value["error"] in CELL_ERRORS
+
+
+def parse_input(text: str) -> dict[str, Any]:
+    """What typing ``text`` into a cell means, as the TypeScript ``parseInput``: a cell's ``v`` or ``f``."""
+    if text.startswith("'"):
+        return {"v": text[1:]}
+    if text.startswith("=") and len(text) > 1:
+        return {"f": text[1:]}
+    t = text.strip()
+    if t and re.fullmatch(r"[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?", t):
+        n = float(t)
+        return {"v": int(n) if n.is_integer() and "." not in t and "e" not in t.lower() else n}
+    if t.lower() == "true":
+        return {"v": True}
+    if t.lower() == "false":
+        return {"v": False}
+    return {} if text == "" else {"v": text}
+
+
+class Workbook:
+    """A CellsWorkbook in memory: sheets of sparse cells, styles by index."""
+
+    def __init__(self, data: dict[str, Any]):
+        validate_workbook(data)
+        self._styles: list[dict[str, Any]] = [dict(s) for s in data.get("styles", [])] or [{}]
+        self._sheets: list[dict[str, Any]] = []
+        for s in data["sheets"]:
+            cells: dict[tuple[int, int], dict[str, Any]] = {}
+            for r, row in s["rows"].items():
+                for c, cell in row["cells"].items():
+                    kept = {k: v for k, v in cell.items() if not (k == "v" and v is None)}
+                    if kept.get("s") == 0:
+                        kept.pop("s")
+                    if kept:
+                        cells[(int(r), int(c))] = kept
+            sheet = {k: v for k, v in s.items() if k != "rows"}
+            sheet["cells"] = cells
+            self._sheets.append(sheet)
+
+    # ------------------------------------------------------------------ files
+
+    @classmethod
+    def load(cls, path: Union[str, Path]) -> "Workbook":
+        try:
+            data = json.loads(Path(path).read_text(encoding="utf-8"))
+        except json.JSONDecodeError as error:
+            raise FormatError(f"workbook: {path} is not JSON ({error})") from error
+        return cls(data)
+
+    @classmethod
+    def from_rows(cls, rows: list[list[Value]], name: str = "Sheet1") -> "Workbook":
+        """A workbook of one sheet from rows of values."""
+        out: dict[str, Any] = {}
+        for r, row in enumerate(rows):
+            for c, v in enumerate(row):
+                if v is not None:
+                    out.setdefault(str(r), {"cells": {}})["cells"][str(c)] = {"v": v}
+        return cls({"version": FORMAT_VERSION, "sheets": [{"id": "s1", "name": name, "rows": out}], "styles": []})
+
+    def save(self, path: Union[str, Path]) -> None:
+        Path(path).write_text(json.dumps(self.to_json(), indent=2) + "\n", encoding="utf-8")
+
+    def to_json(self) -> dict[str, Any]:
+        """The workbook as CellsWorkbook JSON, in the TypeScript model's canonical form."""
+        used: dict[int, int] = {0: 0}
+        styles: list[dict[str, Any]] = [{}]
+        sheets = []
+        for sheet in self._sheets:
+            rows: dict[str, Any] = {}
+            for (r, c) in sorted(sheet["cells"]):
+                cell = sheet["cells"][(r, c)]
+                out: dict[str, Any] = {}
+                if cell.get("v") is not None:
+                    out["v"] = cell["v"]
+                if "f" in cell:
+                    out["f"] = cell["f"]
+                s = cell.get("s", 0)
+                if s != 0:
+                    if s not in used:
+                        used[s] = len(styles)
+                        styles.append(self._styles[s])
+                    out["s"] = used[s]
+                rows.setdefault(str(r), {"cells": {}})["cells"][str(c)] = out
+            item: dict[str, Any] = {"id": sheet["id"], "name": sheet["name"], "rows": rows}
+            for key in ("sizes", "hidden", "merges", "frozen"):
+                if key in sheet and sheet[key]:
+                    if key == "frozen" and sheet[key] == {"rows": 0, "cols": 0}:
+                        continue
+                    item[key] = sheet[key]
+            sheets.append(item)
+        return {"version": FORMAT_VERSION, "sheets": sheets, "styles": styles}
+
+    # ------------------------------------------------------------------ reading
+
+    @property
+    def sheet_names(self) -> list[str]:
+        return [s["name"] for s in self._sheets]
+
+    def _sheet(self, name: str | None) -> dict[str, Any]:
+        if name is None:
+            return self._sheets[0]
+        for s in self._sheets:
+            if s["name"].lower() == name.lower():
+                return s
+        raise KeyError(f"No sheet '{name}'; the workbook has {', '.join(self.sheet_names)}.")
+
+    def _zone(self, ref: str) -> tuple[dict[str, Any], tuple[int, int, int, int]]:
+        name, a1 = split_sheet(ref)
+        sheet = self._sheet(name)
+        zone = parse_zone(a1)
+        if zone[2] >= DEFAULT_LIMITS["rows"] or zone[3] >= DEFAULT_LIMITS["cols"]:
+            raise ValueError(f"'{ref}' reaches outside the sheet.")
+        return sheet, zone
+
+    def cell(self, ref: str) -> dict[str, Any] | None:
+        """What a cell holds: ``{'v': …}``, ``{'f': …, 'v': cached}``, with ``'s'`` for a style; ``None`` when empty."""
+        sheet, (r, c, r1, c1) = self._zone(ref)
+        if (r, c) != (r1, c1):
+            raise ValueError(f"'{ref}' is a range; cell() takes one cell.")
+        found = sheet["cells"].get((r, c))
+        return dict(found) if found else None
+
+    def read(self, ref: str) -> list[list[Value]]:
+        """The values a range shows, as rows: a formula shows its cached value."""
+        sheet, (top, left, bottom, right) = self._zone(ref)
+        cells = sheet["cells"]
+        return [[(cells.get((r, c)) or {}).get("v") for c in range(left, right + 1)] for r in range(top, bottom + 1)]
+
+    def formulas(self, ref: str) -> list[list[str | None]]:
+        """The formulas of a range as typed (with ``=``), ``None`` where a cell holds none."""
+        sheet, (top, left, bottom, right) = self._zone(ref)
+        cells = sheet["cells"]
+        out = []
+        for r in range(top, bottom + 1):
+            row = []
+            for c in range(left, right + 1):
+                f = (cells.get((r, c)) or {}).get("f")
+                row.append(None if f is None else f"={f}")
+            out.append(row)
+        return out
+
+    # ------------------------------------------------------------------ writing
+
+    def write(self, ref: str, rows: list[list[Any]]) -> None:
+        """Write a block of rows from the top-left of ``ref``. A string starting with ``=`` is a formula;
+        ``None`` empties a cell's content and keeps its style."""
+        sheet, (top, left, _, _) = self._zone(ref)
+        if not isinstance(rows, list) or not rows or not all(isinstance(r, list) for r in rows):
+            raise ValueError("write takes a non-empty list of rows.")
+        width = max(len(r) for r in rows)
+        if top + len(rows) > DEFAULT_LIMITS["rows"] or left + width > DEFAULT_LIMITS["cols"]:
+            raise ValueError(f"The block at '{ref}' reaches outside the sheet.")
+        planned: dict[tuple[int, int], dict[str, Any] | None] = {}
+        for dr, row in enumerate(rows):
+            for dc, value in enumerate(row):
+                pos = (top + dr, left + dc)
+                previous = sheet["cells"].get(pos, {})
+                cell: dict[str, Any] = {"s": previous["s"]} if "s" in previous else {}
+                if isinstance(value, str) and value.startswith("=") and len(value) > 1:
+                    cell["f"] = value[1:]
+                elif value is not None:
+                    if isinstance(value, float) and not math.isfinite(value):
+                        raise ValueError(f"{value} is not a cell value.")
+                    if isinstance(value, dict) and not is_error(value):
+                        raise ValueError(f"{value!r} is not a cell value (an error is {{'error': '#N/A'}}).")
+                    if not isinstance(value, (int, float, str, bool, dict)):
+                        raise ValueError(f"{value!r} is not a cell value.")
+                    cell["v"] = value
+                planned[pos] = cell or None
+        for pos, cell in planned.items():
+            if cell is None:
+                sheet["cells"].pop(pos, None)
+            else:
+                sheet["cells"][pos] = cell
+
+    def clear(self, ref: str) -> None:
+        """Empty a range: values, formulas and styles."""
+        sheet, (top, left, bottom, right) = self._zone(ref)
+        for pos in [p for p in sheet["cells"] if top <= p[0] <= bottom and left <= p[1] <= right]:
+            del sheet["cells"][pos]
+
+    def style(self, ref: str, style: dict[str, Any] | None) -> None:
+        """Merge ``style`` into every cell of a range (``None`` resets to the default)."""
+        if style is not None:
+            check_style(style)
+        sheet, (top, left, bottom, right) = self._zone(ref)
+        for r in range(top, bottom + 1):
+            for c in range(left, right + 1):
+                cell = dict(sheet["cells"].get((r, c), {}))
+                if style is None:
+                    cell.pop("s", None)
+                else:
+                    merged = {**self._styles[cell.get("s", 0)], **style}
+                    merged = {k: v for k, v in merged.items() if v is not False}
+                    cell["s"] = self._intern(merged)
+                    if cell["s"] == 0:
+                        cell.pop("s")
+                if cell:
+                    sheet["cells"][(r, c)] = cell
+                else:
+                    sheet["cells"].pop((r, c), None)
+
+    def add_sheet(self, name: str) -> None:
+        if not name.strip() or len(name) > 31 or re.search(r"[\\/?*\[\]:]", name):
+            raise ValueError(f"'{name}' is not a sheet name.")
+        if any(s["name"].lower() == name.lower() for s in self._sheets):
+            raise ValueError(f"A sheet is called '{name}' already.")
+        ids = {s["id"] for s in self._sheets}
+        n = 1
+        while f"s{n}" in ids:
+            n += 1
+        self._sheets.append({"id": f"s{n}", "name": name, "cells": {}})
+
+    def _intern(self, style: dict[str, Any]) -> int:
+        canonical = {k: style[k] for k in sorted(style)}
+        for i, s in enumerate(self._styles):
+            if {k: s[k] for k in sorted(s)} == canonical:
+                return i
+        self._styles.append(canonical)
+        return len(self._styles) - 1

datalayer_cells-0.0.2.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: datalayer_cells
+Version: 0.0.2
+Summary: Datalayer Cells for Python: read and write Cells workbooks, as agents do, and the `datalayer cells` command
+Project-URL: Homepage, https://github.com/datalayer/cells
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: datalayer-reactor>=1.3.1
+Requires-Dist: typer>=0.12
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai)
+
+[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
+
+# ☰ 🦠 Datalayer Cells
+
+A spreadsheet drawn on canvas and exposed as a React component, over a
+headless model that also runs in Node and in workers. Cells is built on
+[Reactor](https://github.com/datalayer/reactor): every extension point (formula
+functions, cell types, commands, importers and exporters, data sources, the
+collaboration provider) is a Reactor contribution point, and the built-in
+features are Reactor plugins contributing through the same points.
+
+> Work in progress: nothing is published yet.
+
+## Packages
+
+| Import                    | What                                                    |
+| ------------------------- | ------------------------------------------------------- |
+| `@datalayer/cells`        | the React component and hooks; re-exports `./core`      |
+| `@datalayer/cells/core`   | the headless model: no React, no DOM                    |
+| `@datalayer/cells/csv`    | CSV and TSV in and out                                  |
+| `@datalayer/cells/xlsx`   | XLSX in and out, loaded lazily                          |
+| `@datalayer/cells/collab` | real-time collaboration over Loro                       |
+| `@datalayer/cells/chrome` | toolbar, formula bar and sheet tabs                     |
+| `@datalayer/cells/plugin` | views for a Reactor shell                               |
+
+## Python
+
+`datalayer_cells` reads and writes the same workbooks, with the same
+validation, for agents and scripts, and adds the `datalayer cells` command
+(also `datalayer-cells` on its own):
+
+```python
+from datalayer_cells import Workbook
+
+wb = Workbook.load("budget.cells.json")
+wb.read("Summary!A1:C4")            # rows of values
+wb.write("B2", [[12, "=B1*2"]])     # formulas are kept as typed
+wb.save("budget.cells.json")
+```
+
+```bash
+datalayer cells show budget.cells.json
+datalayer cells get budget.cells.json 'Summary!A1:C4'
+datalayer cells set budget.cells.json B2 12 '=B1*2'
+datalayer cells export budget.cells.json --format csv
+```
+
+## Examples
+
+```bash
+make examples       # http://127.0.0.1:3077/
+```
+
+A page with a menu of examples, from a few values to collaboration, each with
+its source. What is not built yet says so, and names the milestone that
+brings it.
+
+## Development
+
+`@datalayer/reactor` resolves as a package: from npm, or from the workspace in
+the Datalayer monorepo (install at its root).
+
+```bash
+npm install
+npm run lint        # Prettier and the licence header on every file
+npm run typecheck   # everything, tests and examples included
+npm test            # unit tests (vitest, two workers), the React tests under React 19 and 18.3
+npm run build       # lib/
+npm run bench       # Node benches into bench/results/
+python -m pytest    # the Python package (pip install -e ".[test]" first)
+npm run size        # bundle sizes against their budgets
+```
+
+Browser benches and end-to-end tests run on the system Chrome, headless:
+
+```bash
+env -u WAYLAND_DISPLAY -u DISPLAY node scripts/bench.mjs --browser
+```
+
+## Credits
+
+Cells was designed after reading [x-spreadsheet](https://github.com/myliang/x-spreadsheet)
+(MIT) and [o-spreadsheet](https://github.com/odoo/o-spreadsheet) (LGPLv3) for
+ideas; no code of either is included. See [THIRD_PARTY.md](THIRD_PARTY.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

datalayer_cells-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+datalayer_cells/__init__.py,sha256=8K2IBLkEl2tXFUf6p8hH6xUWvdyGrup1sa2w0Jq2wyw,774
+datalayer_cells/__version__.py,sha256=sTGaa9VpLhcTgVRnVMaZFmLqEQQrYHgrczyt8iGDnRY,168
+datalayer_cells/cli.py,sha256=qETUalhzQQUOToIJa7uVGroNCWN53OnWgsr907tR1Rw,5509
+datalayer_cells/format.py,sha256=dwFKmRrCz5OW7iqDsBPxyTjcg5wea8KyxfnJeYoptus,9753
+datalayer_cells/workbook.py,sha256=vPD8djBJKo5FgCiXSxwKW1PN_cAqvfIyvnGyCfNtsoY,13083
+datalayer_cells-0.0.2.dist-info/METADATA,sha256=DxA60evXvkrPQSx_yNn_-Ke0btVf_WyRF2_oSVcPlLs,4002
+datalayer_cells-0.0.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+datalayer_cells-0.0.2.dist-info/entry_points.txt,sha256=Kd3BrmhCPUOi686PQqDI6BnAkKUAtq4Kqf2kCcCalnU,113
+datalayer_cells-0.0.2.dist-info/licenses/LICENSE,sha256=X75wtNZtai3-uHnGrGP9sHazj_5k3WRbaNaZzdzj6Bk,1077
+datalayer_cells-0.0.2.dist-info/RECORD,,

datalayer_cells-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

datalayer_cells-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+datalayer-cells = datalayer_cells.cli:main
+
+[datalayer.cli]
+cells = datalayer_cells.cli:plugin

datalayer_cells-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 Datalayer, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.