Metadata-Version: 2.5
Name: datalayer_cells
Version: 0.0.5
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.

Formulas: 117 functions, each checked against what LibreOffice computes; the
list is in [docs/functions.md](docs/functions.md).

## 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
```

## License

MIT, see [LICENSE](LICENSE).
