datalayer-cells 0.0.2__tar.gz

datalayer_cells-0.0.2/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+lib/
+dist/
+dist-npm/
+bench/results/*.json
+!bench/results/baselines.json
+test-results/
+playwright-report/
+*-lock.json
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist-py/

datalayer_cells-0.0.2/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.

datalayer_cells-0.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+[![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/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-0.0.2/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-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()