headless-spreadsheets 0.1.0__py3-none-any.whl

headless_spreadsheets/__init__.py

@@ -0,0 +1,14 @@
+"""Spreadsheet-native tables and portable interchange for ordinary Python."""
+
+from .core import Cell, CellInput, DataType, Limits, Scalar, Sheet, Workbook, column_name, split_address
+from .errors import AddressError, FormatError, ShapeError, SpreadsheetError
+from .table import Column, Row, Table, TableView
+from .rendering import TableDocument
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AddressError", "Cell", "CellInput", "DataType", "FormatError", "Limits",
+    "Scalar", "ShapeError", "Sheet", "SpreadsheetError", "Workbook",
+    "Column", "Row", "Table", "TableDocument", "TableView", "column_name", "split_address",
+]

headless_spreadsheets/core.py

@@ -0,0 +1,225 @@
+"""Typed cells, rectangular grids and ordered workbooks."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Literal
+
+from .errors import AddressError, ShapeError, SpreadsheetError
+from .formats import NativeJSON
+
+type Scalar = None | bool | int | float | str | Decimal | date | datetime
+type CellInput = Scalar | Cell
+type DataType = Literal["blank", "boolean", "integer", "number", "text", "decimal", "date", "datetime"]
+
+_TYPES: dict[type, DataType] = {
+    type(None): "blank", bool: "boolean", int: "integer", float: "number",
+    str: "text", Decimal: "decimal", date: "date", datetime: "datetime",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Cell:
+    """A literal or an opaque formula with an unverified cached scalar result.
+
+    A string beginning with '=' is literal unless supplied as ``formula``.
+    Formula results are never calculated or marked fresh in this release.
+    ``number_format`` is an inert presentation hint.
+    """
+
+    value: Scalar = None
+    formula: str | None = None
+    number_format: str | None = None
+
+    def __post_init__(self) -> None:
+        if type(self.value) not in _TYPES:
+            raise SpreadsheetError(f"Unsupported cell type: {type(self.value).__name__}")
+        if type(self.value) is float and not math.isfinite(self.value):
+            raise SpreadsheetError("Cell numbers must be finite.")
+        if type(self.value) is Decimal and not self.value.is_finite():
+            raise SpreadsheetError("Cell decimals must be finite.")
+        if self.formula is not None and (
+            not isinstance(self.formula, str)
+            or not self.formula.startswith("=")
+            or not self.formula[1:].strip()
+        ):
+            raise SpreadsheetError("A formula must start with '=' and contain an expression.")
+        if self.number_format is not None and not isinstance(self.number_format, str):
+            raise SpreadsheetError("A number-format hint must be text or None.")
+
+    @property
+    def data_type(self) -> DataType:
+        return _TYPES[type(self.value)]
+
+    @property
+    def cache_status(self) -> Literal["value", "missing", "stale"]:
+        if self.formula is None:
+            return "value"
+        return "missing" if self.value is None else "stale"
+
+
+def as_cell(value: CellInput) -> Cell:
+    return value if isinstance(value, Cell) else Cell(value)
+
+
+@dataclass(frozen=True, slots=True)
+class Limits:
+    """Finite application guardrails, not a hard memory or CPU sandbox."""
+
+    max_rows: int = 100_000
+    max_columns: int = 1_024
+    max_cells: int = 1_000_000
+    max_input_bytes: int = 16_000_000
+    max_sheets: int = 256
+
+    def __post_init__(self) -> None:
+        for name in self.__dataclass_fields__:
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ShapeError(f"{name} must be a positive integer.")
+
+    def check(self, rows: int, columns: int) -> None:
+        if rows > self.max_rows or columns > self.max_columns or rows * columns > self.max_cells:
+            raise ShapeError("Grid dimensions exceed the configured limits.")
+
+
+DEFAULT_LIMITS = Limits()
+
+
+def column_name(index: int) -> str:
+    """Convert a zero-based column index to its A1 name."""
+    if type(index) is not int or index < 0:
+        raise AddressError("A column index must be a nonnegative integer.")
+    result = ""
+    index += 1
+    while index:
+        index, remainder = divmod(index - 1, 26)
+        result = chr(65 + remainder) + result
+    return result
+
+
+def split_address(address: str) -> tuple[int, int]:
+    """Return zero-based (row, column) coordinates for an A1 address."""
+    if not isinstance(address, str) or len(address) > 64:
+        raise AddressError("Expected an A1 cell address.")
+    match = re.fullmatch(r"([A-Za-z]+)([1-9][0-9]*)", address)
+    if match is None:
+        raise AddressError(f"Invalid A1 address: {address!r}")
+    column = 0
+    for letter in match[1].upper():
+        column = column * 26 + ord(letter) - 64
+    return int(match[2]) - 1, column - 1
+
+
+def _collect_rows(
+    rows: Iterable[Iterable[CellInput]], *, width: int | None, limits: Limits
+) -> tuple[tuple[tuple[Cell, ...], ...], int]:
+    if width is not None and (type(width) is not int or width < 0):
+        raise ShapeError("Grid width must be a nonnegative integer.")
+    limits.check(0, width or 0)
+    collected = []
+    for row in rows:
+        limits.check(len(collected) + 1, width or 0)
+        if isinstance(row, (str, bytes)):
+            raise ShapeError("A row must be an iterable of cells, not text.")
+        cells = []
+        for value in row:
+            limits.check(len(collected) + 1, len(cells) + 1)
+            if width is not None and len(cells) >= width:
+                raise ShapeError("Rows must all have the declared width.")
+            cells.append(as_cell(value))
+        if width is None:
+            width = len(cells)
+        if len(cells) != width:
+            raise ShapeError("Rows must all have the declared width.")
+        collected.append(tuple(cells))
+    return tuple(collected), width or 0
+
+
+class Sheet(NativeJSON):
+    """An editable rectangular grid; edits never resize or calculate the grid."""
+
+    def __init__(
+        self, rows: Iterable[Iterable[CellInput]] = (), *, name: str = "Sheet1",
+        width: int | None = None, limits: Limits = DEFAULT_LIMITS,
+    ) -> None:
+        if not isinstance(name, str) or not name.strip():
+            raise ShapeError("A sheet name must be nonempty text.")
+        self._name = name
+        self._limits = limits
+        self._rows, self._width = _collect_rows(rows, width=width, limits=limits)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return len(self._rows), self._width
+
+    @property
+    def rows(self) -> tuple[tuple[Cell, ...], ...]:
+        return self._rows
+
+    def __len__(self) -> int:
+        return len(self._rows)
+
+    def _position(self, address: str) -> tuple[int, int]:
+        row, column = split_address(address)
+        if row >= len(self._rows) or column >= self._width:
+            raise AddressError(f"Address {address!r} is outside the existing grid.")
+        return row, column
+
+    def cell(self, address: str) -> Cell:
+        row, column = self._position(address)
+        return self._rows[row][column]
+
+    def set(self, address: str, value: CellInput) -> None:
+        row, column = self._position(address)
+        cell = as_cell(value)
+        changed = (*self._rows[row][:column], cell, *self._rows[row][column + 1:])
+        self._rows = (*self._rows[:row], changed, *self._rows[row + 1:])
+
+    def set_formula(self, address: str, formula: str, *, cached_value: Scalar = None) -> None:
+        self.set(address, Cell(cached_value, formula=formula))
+
+
+class Workbook(NativeJSON):
+    """Named sheets in insertion order, without a calculation scheduler."""
+
+    def __init__(self, sheets: Iterable[Sheet] = (), *, limits: Limits = DEFAULT_LIMITS) -> None:
+        self._limits = limits
+        self._sheets: dict[str, Sheet] = {}
+        for sheet in sheets:
+            self.add_sheet(sheet)
+
+    def add_sheet(self, sheet: Sheet) -> None:
+        if not isinstance(sheet, Sheet):
+            raise ShapeError("A workbook contains Sheet objects.")
+        if sheet.name in self._sheets:
+            raise ShapeError(f"Duplicate sheet name: {sheet.name!r}")
+        if len(self._sheets) >= self._limits.max_sheets:
+            raise ShapeError("Workbook sheet count exceeds the configured limit.")
+        self._limits.check(*sheet.shape)
+        total = sum(rows * columns for rows, columns in (item.shape for item in self._sheets.values()))
+        if total + sheet.shape[0] * sheet.shape[1] > self._limits.max_cells:
+            raise ShapeError("Workbook cell count exceeds the configured limit.")
+        self._sheets[sheet.name] = sheet
+
+    @property
+    def sheet_names(self) -> tuple[str, ...]:
+        return tuple(self._sheets)
+
+    def __getitem__(self, name: str) -> Sheet:
+        return self._sheets[name]
+
+    def __iter__(self) -> Iterator[Sheet]:
+        return iter(self._sheets.values())
+
+    def __len__(self) -> int:
+        return len(self._sheets)

headless_spreadsheets/errors.py

@@ -0,0 +1,17 @@
+"""Errors raised by the public spreadsheet interfaces."""
+
+
+class SpreadsheetError(ValueError):
+    """Base class for invalid spreadsheet data or operations."""
+
+
+class AddressError(SpreadsheetError):
+    """An A1 address is malformed or outside the existing grid."""
+
+
+class ShapeError(SpreadsheetError):
+    """A grid is ragged, has invalid labels or exceeds its limits."""
+
+
+class FormatError(SpreadsheetError):
+    """Serialized spreadsheet data does not satisfy the format contract."""

headless_spreadsheets/file_io.py

@@ -0,0 +1,60 @@
+"""Bounded UTF-8 reads and atomic text replacement."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .errors import FormatError
+
+if TYPE_CHECKING:
+    from .core import Limits
+
+type FilePath = str | os.PathLike[str]
+
+
+def check_text(text: str, limits: Limits) -> None:
+    if not isinstance(text, str):
+        raise FormatError("Expected serialized text, not a path or bytes.")
+    try:
+        if len(text) > limits.max_input_bytes or len(text.encode("utf-8")) > limits.max_input_bytes:
+            raise FormatError("Serialized input exceeds the configured byte limit.")
+    except UnicodeError as error:
+        raise FormatError("Serialized text must be valid UTF-8.") from error
+
+
+def read_text(path: FilePath, limits: Limits) -> str:
+    path = Path(path)
+    if path.stat().st_size > limits.max_input_bytes:
+        raise FormatError("Input file exceeds the configured byte limit.")
+    with path.open("rb") as stream:
+        raw = stream.read(limits.max_input_bytes + 1)
+    if len(raw) > limits.max_input_bytes:
+        raise FormatError("Input file exceeds the configured byte limit.")
+    try:
+        return raw.decode("utf-8-sig")
+    except UnicodeError as error:
+        raise FormatError("Input file must be UTF-8 text.") from error
+
+
+def write_text(text: str, path: FilePath | None) -> str:
+    if path is None:
+        return text
+    destination = Path(path)
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", newline="", dir=destination.parent,
+            prefix=f".{destination.name}.", suffix=".tmp", delete=False,
+        ) as stream:
+            temporary = Path(stream.name)
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, destination)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return text

headless_spreadsheets/formats.py

@@ -0,0 +1,33 @@
+"""Lazy serialization interfaces shared by the document models."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self
+
+from .errors import FormatError
+from .file_io import FilePath, read_text, write_text
+
+if TYPE_CHECKING:
+    from .core import Limits
+
+
+class NativeJSON:
+    def to_json(self, path: FilePath | None = None, *, indent: int | None = 2) -> str:
+        """Serialize typed cells; optionally replace a UTF-8 destination atomically."""
+        from .serialization import dumps
+        return write_text(dumps(self, indent=indent), path)
+
+    @classmethod
+    def from_json(cls, text: str, *, limits: Limits | None = None) -> Self:
+        """Parse native JSON text of this model's kind, rejecting unknown schemas."""
+        from .serialization import loads
+        result = loads(text, limits=limits)
+        if not isinstance(result, cls):
+            raise FormatError(f"Expected a serialized {cls.__name__}.")
+        return result
+
+    @classmethod
+    def read_json(cls, path: FilePath, *, limits: Limits | None = None) -> Self:
+        from .core import DEFAULT_LIMITS
+        selected = DEFAULT_LIMITS if limits is None else limits
+        return cls.from_json(read_text(path, selected), limits=selected)

headless_spreadsheets/rendering.py

@@ -0,0 +1,160 @@
+"""Immutable presentation documents and safe table-only renderers."""
+
+from __future__ import annotations
+
+import html
+import unicodedata
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from .core import DEFAULT_LIMITS
+from .errors import SpreadsheetError
+from .serialization import scalar_text
+
+if TYPE_CHECKING:
+    from .table import _Tabular
+
+type Alignment = Literal["left", "right", "center"]
+
+
+def _newlines(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _markdown(text: str) -> str:
+    text = html.escape(_newlines(text), quote=False)
+    return "".join("\\" + character if character in "\\`*_[]|~" else character for character in text).replace("\n", "<br>")
+
+
+def _html(text: str) -> str:
+    return html.escape(_newlines(text), quote=True).replace("\n", "<br>")
+
+
+def _terminal(text: str) -> str:
+    result = []
+    for character in text:
+        if character in {"\n", "\r", "\t"}:
+            result.append({"\n": r"\n", "\r": r"\r", "\t": r"\t"}[character])
+        elif unicodedata.category(character).startswith("C"):
+            number = ord(character)
+            result.append(f"\\x{number:02x}" if number < 256 else f"\\u{number:04x}")
+        else:
+            result.append(character)
+    return "".join(result)
+
+
+def _width(text: str) -> int:
+    return sum(0 if unicodedata.combining(character) else 2 if unicodedata.east_asian_width(character) in {"W", "F"} else 1 for character in text)
+
+
+def _truncate(text: str, maximum: int) -> str:
+    if _width(text) <= maximum:
+        return text
+    result = []
+    width = 0
+    for character in text:
+        size = _width(character)
+        if width + size > maximum - 1:
+            break
+        result.append(character)
+        width += size
+    return "".join(result) + "…"
+
+
+@dataclass(frozen=True, slots=True)
+class TableDocument:
+    """Display text detached from live cells; this is not a spreadsheet model.
+
+    Construct from tuples or use ``table.to_document()``. Number formats and
+    formulas are not interpreted. Rendering methods return text only.
+    """
+
+    headers: tuple[str, ...] = ()
+    rows: tuple[tuple[str, ...], ...] = ()
+    alignments: tuple[Alignment, ...] = ()
+
+    def __post_init__(self) -> None:
+        if type(self.headers) is not tuple or type(self.rows) is not tuple or type(self.alignments) is not tuple:
+            raise SpreadsheetError("A table document must use immutable tuples.")
+        if not self.alignments:
+            object.__setattr__(self, "alignments", ("left",) * len(self.headers))
+        if len(self.alignments) != len(self.headers) or any(value not in {"left", "right", "center"} for value in self.alignments):
+            raise SpreadsheetError("Each document column needs a left, right or center alignment.")
+        if not all(isinstance(value, str) for value in self.headers):
+            raise SpreadsheetError("Document headers must be strings.")
+        for row in self.rows:
+            if type(row) is not tuple or len(row) != len(self.headers) or not all(isinstance(value, str) for value in row):
+                raise SpreadsheetError("Document rows must be tuples of text matching the headers.")
+
+    @classmethod
+    def from_table(cls, table: _Tabular, *, formulas: bool = False) -> TableDocument:
+        if type(formulas) is not bool:
+            raise SpreadsheetError("Formula display must be Boolean.")
+        rows = []
+        numeric = [False] * len(table.columns)
+        other = [False] * len(table.columns)
+        for row in table:
+            values = []
+            for position, name in enumerate(table.columns):
+                cell = row.cell(name)
+                formula = cell.formula if formulas else None
+                values.append(formula if formula is not None else scalar_text(cell.value))
+                if formula is not None or (cell.value is not None and cell.data_type not in {"integer", "number", "decimal"}):
+                    other[position] = True
+                elif cell.value is not None:
+                    numeric[position] = True
+            rows.append(tuple(values))
+        alignments = tuple("right" if number and not text else "left" for number, text in zip(numeric, other, strict=True))
+        return cls(table.columns, tuple(rows), alignments)
+
+    def to_markdown(self) -> str:
+        if not self.headers:
+            return ""
+        def row(values):
+            return "| " + " | ".join(_markdown(value) for value in values) + " |"
+        markers = {"left": ":---", "right": "---:", "center": ":---:"}
+        lines = [row(self.headers), "| " + " | ".join(markers[value] for value in self.alignments) + " |"]
+        lines.extend(row(values) for values in self.rows)
+        return "\n".join(lines) + "\n"
+
+    def to_html(self) -> str:
+        if not self.headers:
+            return ""
+        def row(values, header=False):
+            tag = "th" if header else "td"
+            scope = ' scope="col"' if header else ""
+            cells = [f'<{tag}{scope} style="text-align: {alignment};">{_html(value)}</{tag}>' for value, alignment in zip(values, self.alignments, strict=True)]
+            return "<tr>" + "".join(cells) + "</tr>\n"
+        return "<table>\n<thead>\n" + row(self.headers, True) + "</thead>\n<tbody>\n" + "".join(row(values) for values in self.rows) + "</tbody>\n</table>\n"
+
+    def to_ansi(self, *, max_width: int = 32, color: bool = False) -> str:
+        """Render one physical line per row using approximate Unicode cell widths."""
+        if type(max_width) is not int or not 1 <= max_width <= DEFAULT_LIMITS.max_input_bytes:
+            raise SpreadsheetError("max_width must be a positive integer within the text size limit.")
+        if type(color) is not bool:
+            raise SpreadsheetError("Terminal color must be Boolean.")
+        if not self.headers:
+            return ""
+        all_rows = [tuple(_terminal(value) for value in row) for row in (self.headers, *self.rows)]
+        widths = [min(max_width, max(_width(row[index]) for row in all_rows)) for index in range(len(self.headers))]
+        border = "+" + "+".join("-" * (width + 2) for width in widths) + "+"
+
+        def row(values):
+            fields = []
+            for text, width, alignment in zip(values, widths, self.alignments, strict=True):
+                text = _truncate(text, width)
+                extra = width - _width(text)
+                left = extra if alignment == "right" else extra // 2 if alignment == "center" else 0
+                fields.append(" " * left + text + " " * (extra - left))
+            return "| " + " | ".join(fields) + " |"
+
+        header = row(all_rows[0])
+        if color:
+            header = "\x1b[1;36m" + header + "\x1b[0m"
+        return "\n".join([border, header, border, *(row(values) for values in all_rows[1:]), border]) + "\n"
+
+    def render(self, format: str, **options) -> str:
+        methods = {"markdown": self.to_markdown, "html": self.to_html, "ansi": self.to_ansi}
+        if format not in methods:
+            raise SpreadsheetError("Expected format='markdown', 'html' or 'ansi'.")
+        return methods[format](**options)

headless_spreadsheets/serialization.py

@@ -0,0 +1,222 @@
+"""Strict native JSON schema v1 and deliberately text-oriented CSV interchange."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+from .core import DEFAULT_LIMITS, Cell, Limits, Scalar, Sheet, Workbook
+from .errors import FormatError, SpreadsheetError
+from .file_io import check_text
+from .table import Table, TableView, _Tabular
+
+_FORMAT = "headless-spreadsheets"
+_VERSION = 1
+
+
+def scalar_text(value: Scalar) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return str(value)
+
+
+def _value_data(cell: Cell) -> dict[str, Any]:
+    value = cell.value
+    if cell.data_type in {"date", "datetime"}:
+        value = value.isoformat()
+    elif cell.data_type == "decimal":
+        value = str(value)
+    return {"type": cell.data_type, "value": value}
+
+
+def _cell_data(cell: Cell) -> dict[str, Any]:
+    return {
+        "value": _value_data(cell), "formula": cell.formula,
+        "number_format": cell.number_format, "cache_status": cell.cache_status,
+    }
+
+
+def _sheet_data(sheet: Sheet) -> dict[str, Any]:
+    return {"name": sheet.name, "width": sheet.shape[1], "rows": [[_cell_data(cell) for cell in row] for row in sheet.rows]}
+
+
+def dumps(document: Table | Sheet | Workbook, *, indent: int | None = 2) -> str:
+    if indent is not None and (type(indent) is not int or not 0 <= indent <= 8):
+        raise FormatError("JSON indent must be None or an integer from 0 to 8.")
+    if isinstance(document, Table):
+        kind = "table"
+        data = {"columns": list(document.columns), "rows": [[_cell_data(cell) for cell in row] for row in document._rows]}
+    elif isinstance(document, Sheet):
+        kind, data = "sheet", _sheet_data(document)
+    elif isinstance(document, Workbook):
+        # Recheck aggregate bounds before producing a persistent representation.
+        Workbook(document, limits=document._limits)
+        kind, data = "workbook", {"sheets": [_sheet_data(sheet) for sheet in document]}
+    else:
+        raise FormatError("Native JSON requires an original Table, Sheet or Workbook.")
+    try:
+        text = json.dumps(
+            {"format": _FORMAT, "schema_version": _VERSION, "kind": kind, "data": data},
+            ensure_ascii=False, allow_nan=False, indent=indent,
+        ) + "\n"
+    except (ValueError, OverflowError) as error:
+        raise FormatError("A cell cannot be represented in native JSON.") from error
+    check_text(text, document._limits)
+    return text
+
+
+def _fields(value: Any, expected: set[str]) -> dict[str, Any]:
+    if type(value) is not dict or set(value) != expected:
+        raise FormatError(f"Expected exactly these object fields: {', '.join(sorted(expected))}.")
+    return value
+
+
+def _decode_value(value: Any) -> Scalar:
+    data = _fields(value, {"type", "value"})
+    kind, scalar = data["type"], data["value"]
+    basic = {"blank": type(None), "boolean": bool, "integer": int, "number": float, "text": str}
+    if not isinstance(kind, str):
+        raise FormatError("A value type must be a string.")
+    if kind in basic and type(scalar) is basic[kind]:
+        return scalar
+    if type(scalar) is str:
+        if kind == "decimal":
+            return Decimal(scalar)
+        if kind == "date":
+            return date.fromisoformat(scalar)
+        if kind == "datetime":
+            return datetime.fromisoformat(scalar)
+    raise FormatError(f"Invalid scalar for native type {kind!r}.")
+
+
+def _decode_cell(value: Any) -> Cell:
+    data = _fields(value, {"value", "formula", "number_format", "cache_status"})
+    cell = Cell(_decode_value(data["value"]), formula=data["formula"], number_format=data["number_format"])
+    if data["cache_status"] != cell.cache_status:
+        raise FormatError("A formula cache cannot be marked fresh or contradict its value.")
+    return cell
+
+
+def _decode_rows(rows: Any, width: int, limits: Limits) -> list[list[Cell]]:
+    if type(rows) is not list or type(width) is not int or width < 0:
+        raise FormatError("Expected rows and a nonnegative integer width.")
+    limits.check(len(rows), width)
+    result = []
+    for row in rows:
+        if type(row) is not list or len(row) != width:
+            raise FormatError("Native rows must match the declared width.")
+        result.append([_decode_cell(cell) for cell in row])
+    return result
+
+
+def _decode_sheet(data: Any, limits: Limits) -> Sheet:
+    data = _fields(data, {"name", "width", "rows"})
+    return Sheet(_decode_rows(data["rows"], data["width"], limits), name=data["name"], width=data["width"], limits=limits)
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise FormatError(f"Duplicate JSON key: {key!r}")
+        result[key] = value
+    return result
+
+
+def _nonfinite(value: str) -> None:
+    raise FormatError("Native JSON numbers must be finite.")
+
+
+def loads(text: str, *, limits: Limits | None = None) -> Table | Sheet | Workbook:
+    selected = DEFAULT_LIMITS if limits is None else limits
+    check_text(text, selected)
+    try:
+        document = json.loads(text, object_pairs_hook=_unique_object, parse_constant=_nonfinite)
+        document = _fields(document, {"format", "schema_version", "kind", "data"})
+        if document["format"] != _FORMAT or type(document["schema_version"]) is not int or document["schema_version"] != _VERSION:
+            raise FormatError("Unsupported native JSON format or schema version.")
+        data = document["data"]
+        if document["kind"] == "table":
+            data = _fields(data, {"columns", "rows"})
+            if type(data["columns"]) is not list:
+                raise FormatError("Expected a list of column labels.")
+            rows = _decode_rows(data["rows"], len(data["columns"]), selected)
+            return Table(data["columns"], rows, limits=selected)
+        if document["kind"] == "sheet":
+            return _decode_sheet(data, selected)
+        if document["kind"] == "workbook":
+            data = _fields(data, {"sheets"})
+            if type(data["sheets"]) is not list or len(data["sheets"]) > selected.max_sheets:
+                raise FormatError("Expected a bounded list of sheets.")
+            return Workbook((_decode_sheet(sheet, selected) for sheet in data["sheets"]), limits=selected)
+        raise FormatError("Unknown native JSON document kind.")
+    except FormatError:
+        raise
+    except (ValueError, TypeError, ArithmeticError, RecursionError) as error:
+        raise FormatError(f"Invalid native JSON: {error}") from error
+
+
+def _delimiter(delimiter: str) -> None:
+    if not isinstance(delimiter, str) or len(delimiter) != 1 or delimiter in '\r\n\0"':
+        raise FormatError("A delimiter must be one character other than a newline, NUL or quote.")
+
+
+def _csv_text(text: str, escape_formulas: bool) -> str:
+    if escape_formulas and text and (
+        text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r", "\n"))
+    ):
+        return "'" + text
+    return text
+
+
+def to_csv(
+    table: _Tabular, *, delimiter: str = ",", formulas: bool = False, escape_formulas: bool = True,
+) -> str:
+    _delimiter(delimiter)
+    if type(formulas) is not bool or type(escape_formulas) is not bool:
+        raise FormatError("CSV formula options must be Boolean.")
+    if formulas and isinstance(table, TableView):
+        raise FormatError("Formula CSV export requires the original table so coordinates stay in place.")
+    stream = io.StringIO(newline="")
+    writer = csv.writer(stream, delimiter=delimiter, lineterminator="\r\n")
+    writer.writerow([_csv_text(name, escape_formulas) for name in table.columns])
+    for row in table:
+        fields = []
+        for name in table.columns:
+            cell = row.cell(name)
+            if formulas and cell.formula is not None:
+                fields.append(cell.formula)
+            else:
+                value = scalar_text(cell.value)
+                fields.append(_csv_text(value, escape_formulas) if type(cell.value) is str else value)
+        writer.writerow(fields)
+    return stream.getvalue()
+
+
+def from_csv(
+    text: str, *, delimiter: str = ",", formulas: bool = False, limits: Limits | None = None,
+) -> Table:
+    selected = DEFAULT_LIMITS if limits is None else limits
+    check_text(text, selected)
+    _delimiter(delimiter)
+    if type(formulas) is not bool:
+        raise FormatError("CSV formula interpretation must be Boolean.")
+    try:
+        reader = csv.reader(io.StringIO(text.removeprefix("\ufeff"), newline=""), delimiter=delimiter, strict=True)
+        columns = next(reader, [])
+        def rows():
+            for row in reader:
+                if len(row) != len(columns):
+                    raise FormatError("CSV rows must match the header width.")
+                yield [Cell(formula=value) if formulas and value.startswith("=") else Cell(value) for value in row]
+        return Table(columns, rows(), limits=selected)
+    except FormatError:
+        raise
+    except (csv.Error, SpreadsheetError) as error:
+        raise FormatError(f"Invalid CSV: {error}") from error

headless_spreadsheets/table.py

@@ -0,0 +1,414 @@
+"""Named tables and stable, read-only selections over source cells."""
+
+from __future__ import annotations
+
+import operator
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from .core import (
+    DEFAULT_LIMITS, Cell, CellInput, Limits, Scalar, Sheet, _collect_rows,
+    as_cell, column_name, split_address,
+)
+from .errors import AddressError, ShapeError, SpreadsheetError
+from .file_io import FilePath, read_text, write_text
+from .formats import NativeJSON
+
+if TYPE_CHECKING:
+    from .rendering import TableDocument
+
+
+def _columns(names: Iterable[str], limits: Limits) -> tuple[str, ...]:
+    if isinstance(names, str):
+        raise ShapeError("Column names must be an iterable of labels, not one string.")
+    result = []
+    seen = set()
+    for name in names:
+        limits.check(0, len(result) + 1)
+        if not isinstance(name, str) or not name.strip():
+            raise ShapeError("Column names must be nonempty strings.")
+        if name in seen:
+            raise ShapeError(f"Duplicate column name: {name!r}")
+        result.append(name)
+        seen.add(name)
+    return tuple(result)
+
+
+class Row(Mapping[str, Scalar]):
+    """A read-only mapping with live values and a zero-based source row index."""
+
+    def __init__(self, table: _Tabular, index: int) -> None:
+        self._table = table
+        self._index = index
+
+    @property
+    def index(self) -> int:
+        return self._index
+
+    def cell(self, column: str) -> Cell:
+        position = self._table._column_position(column)
+        return self._table._root._rows[self._index][position]
+
+    def __getitem__(self, column: str) -> Scalar:
+        return self.cell(column).value
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._table.columns)
+
+    def __len__(self) -> int:
+        return len(self._table.columns)
+
+
+class Column(Sequence[Scalar]):
+    """A read-only sequence; ``cells`` exposes immutable metadata snapshots."""
+
+    def __init__(self, table: _Tabular, name: str) -> None:
+        self._table = table
+        self._name = name
+        self._position = table._column_position(name)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def cells(self) -> tuple[Cell, ...]:
+        return tuple(self._table._root._rows[row][self._position] for row in self._table._row_positions)
+
+    def __len__(self) -> int:
+        return len(self._table._row_positions)
+
+    def __getitem__(self, index: int | slice) -> Scalar | tuple[Scalar, ...]:
+        if isinstance(index, slice):
+            return tuple(cell.value for cell in self.cells[index])
+        row = self._table._row_positions[index]
+        return self._table._root._rows[row][self._position].value
+
+
+_COMPARISONS = {
+    "eq": operator.eq, "ne": operator.ne, "gt": operator.gt, "gte": operator.ge,
+    "lt": operator.lt, "lte": operator.le,
+}
+_OPERATORS = {*_COMPARISONS, "in", "contains", "is_none"}
+
+
+class _Tabular:
+    @property
+    def _root(self) -> Table:
+        raise NotImplementedError
+
+    @property
+    def _row_positions(self) -> Sequence[int]:
+        raise NotImplementedError
+
+    @property
+    def _column_positions(self) -> Sequence[int]:
+        raise NotImplementedError
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return tuple(self._root._columns[column] for column in self._column_positions)
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return len(self._row_positions), len(self._column_positions)
+
+    @property
+    def rows(self) -> tuple[Row, ...]:
+        return tuple(self)
+
+    def __len__(self) -> int:
+        return len(self._row_positions)
+
+    def __iter__(self) -> Iterator[Row]:
+        return (Row(self, index) for index in self._row_positions)
+
+    def __getitem__(self, name: str) -> Column:
+        return Column(self, name)
+
+    def _column_position(self, name: str) -> int:
+        try:
+            return self._column_lookup[name]
+        except KeyError:
+            raise KeyError(f"Unknown column: {name!r}") from None
+
+    def _position(self, address: str) -> tuple[int, int]:
+        row, column = split_address(address)
+        if row > len(self) or column >= len(self.columns):
+            raise AddressError(f"Address {address!r} is outside the table (including its header).")
+        return row, column
+
+    def cell(self, address: str) -> Cell:
+        """Read a cell; header row 1 is followed by data rows starting at 2."""
+        row, column = self._position(address)
+        if row == 0:
+            return Cell(self.columns[column])
+        return self._root._rows[self._row_positions[row - 1]][self._column_positions[column]]
+
+    def source_address(self, address: str) -> str:
+        """Map a local view address to the original table, including its header."""
+        row, column = self._position(address)
+        original_row = 1 if row == 0 else self._row_positions[row - 1] + 2
+        return f"{column_name(self._column_positions[column])}{original_row}"
+
+    def to_records(self) -> list[dict[str, Scalar]]:
+        return [dict(row) for row in self]
+
+    def to_csv(
+        self, path: FilePath | None = None, *, delimiter: str = ",", formulas: bool = False,
+        escape_formulas: bool = True,
+    ) -> str:
+        """Export values, escaping spreadsheet-active text unless explicitly disabled."""
+        from .serialization import to_csv
+        return write_text(to_csv(self, delimiter=delimiter, formulas=formulas, escape_formulas=escape_formulas), path)
+
+    def to_document(self, *, formulas: bool = False) -> TableDocument:
+        """Capture display text independently of future source edits."""
+        from .rendering import TableDocument
+        return TableDocument.from_table(self, formulas=formulas)
+
+    def render(self, format: str, *, formulas: bool = False, **options) -> str:
+        return self.to_document(formulas=formulas).render(format, **options)
+
+    def to_markdown(self, path: FilePath | None = None, *, formulas: bool = False) -> str:
+        return write_text(self.render("markdown", formulas=formulas), path)
+
+    def to_html(self, path: FilePath | None = None, *, formulas: bool = False) -> str:
+        return write_text(self.render("html", formulas=formulas), path)
+
+    def to_ansi(
+        self, path: FilePath | None = None, *, formulas: bool = False,
+        max_width: int = 32, color: bool = False,
+    ) -> str:
+        return write_text(self.render("ansi", formulas=formulas, max_width=max_width, color=color), path)
+
+    def select(self, *columns: str) -> TableView:
+        names = _columns(columns, self._root._limits)
+        positions = tuple(self._column_position(name) for name in names)
+        return TableView(self._root, self._row_positions, positions)
+
+    def where(self, predicate: Callable[[Row], bool] | None = None, **conditions: Any) -> TableView:
+        """Combine a Python predicate and named conditions using AND."""
+        if predicate is not None and not callable(predicate):
+            raise TypeError("A row predicate must be callable.")
+        prepared = []
+        for key, expected in conditions.items():
+            if key in self.columns:
+                name, operation = key, "eq"
+            else:
+                name, separator, operation = key.rpartition("__")
+                if not separator:
+                    name, operation = key, "eq"
+                if operation not in _OPERATORS:
+                    raise SpreadsheetError(f"Unknown filter operator: {operation!r}")
+            position = self._column_position(name)
+            if operation == "is_none" and type(expected) is not bool:
+                raise SpreadsheetError("is_none expects True or False.")
+            # Membership uses a stable reusable collection, not a consumed generator.
+            if operation == "in" and not isinstance(expected, (Sequence, set, frozenset, Mapping)):
+                raise SpreadsheetError("in expects a reusable sequence, set or mapping.")
+            prepared.append((position, operation, expected))
+
+        def matches(index: int) -> bool:
+            for position, operation, expected in prepared:
+                value = self._root._rows[index][position].value
+                try:
+                    if operation == "is_none":
+                        match = (value is None) == expected
+                    elif operation == "in":
+                        match = value in expected
+                    elif operation == "contains":
+                        match = value is not None and expected in value
+                    elif operation in {"gt", "gte", "lt", "lte"} and (value is None or expected is None):
+                        match = False
+                    else:
+                        match = _COMPARISONS[operation](value, expected)
+                except (TypeError, ValueError) as error:
+                    raise SpreadsheetError(f"Cannot apply {operation!r} to column {self._root._columns[position]!r}.") from error
+                if not match:
+                    return False
+            return predicate is None or bool(predicate(Row(self, index)))
+
+        return TableView(self._root, (index for index in self._row_positions if matches(index)), self._column_positions)
+
+    def sort_by(self, *columns: str, reverse: bool = False, nulls: str = "last") -> TableView:
+        """Stable multi-column ordering; blank placement is independent of reverse."""
+        if not columns:
+            raise SpreadsheetError("sort_by requires at least one column.")
+        if type(reverse) is not bool or nulls not in {"first", "last"}:
+            raise SpreadsheetError("Expected a Boolean reverse and nulls='first' or 'last'.")
+        positions = [self._column_position(name) for name in columns]
+        indices = list(self._row_positions)
+        for position in reversed(positions):
+            present, missing = [], []
+            for index in indices:
+                (missing if self._root._rows[index][position].value is None else present).append(index)
+            try:
+                present.sort(key=lambda index: self._root._rows[index][position].value, reverse=reverse)
+            except TypeError as error:
+                raise SpreadsheetError(f"Column {self._root._columns[position]!r} contains incomparable values.") from error
+            indices = missing + present if nulls == "first" else present + missing
+        return TableView(self._root, indices, self._column_positions)
+
+    def to_table(self) -> Table:
+        """Materialize displayed values, dropping formulas rather than relocating them."""
+        return Table(self.columns, ([row[name] for name in self.columns] for row in self), limits=self._root._limits)
+
+
+class Table(_Tabular, NativeJSON):
+    """A standalone named table with explicit edits and immutable headers."""
+
+    def __init__(
+        self, columns: Iterable[str] = (), rows: Iterable[Iterable[CellInput]] = (),
+        *, limits: Limits = DEFAULT_LIMITS,
+    ) -> None:
+        self._limits = limits
+        self._columns = _columns(columns, limits)
+        self._column_lookup = {name: index for index, name in enumerate(self._columns)}
+        self._rows, _ = _collect_rows(rows, width=len(self._columns), limits=limits)
+
+    @classmethod
+    def from_records(
+        cls, records: Iterable[Mapping[str, CellInput]], *, columns: Iterable[str] | None = None,
+        limits: Limits = DEFAULT_LIMITS,
+    ) -> Table:
+        explicit = columns is not None
+        names = list(_columns(columns, limits)) if explicit else []
+        known = set(names)
+        collected = []
+        for record in records:
+            limits.check(len(collected) + 1, len(names))
+            if not isinstance(record, Mapping):
+                raise ShapeError("Each record must be a mapping of column names to cells.")
+            current = {}
+            for name, value in record.items():
+                if not isinstance(name, str) or not name.strip():
+                    raise ShapeError("Record keys must be nonempty column names.")
+                if name not in known:
+                    if explicit:
+                        raise ShapeError(f"Record contains undeclared column: {name!r}")
+                    limits.check(len(collected) + 1, len(names) + 1)
+                    names.append(name)
+                    known.add(name)
+                current[name] = as_cell(value)
+            collected.append(current)
+        return cls(names, ([record.get(name) for name in names] for record in collected), limits=limits)
+
+    @classmethod
+    def from_csv(
+        cls, text: str, *, delimiter: str = ",", formulas: bool = False,
+        limits: Limits | None = None,
+    ) -> Table:
+        """Parse CSV text; fields remain literal strings unless formula mode is explicit."""
+        from .serialization import from_csv
+        return from_csv(text, delimiter=delimiter, formulas=formulas, limits=limits)
+
+    @classmethod
+    def read_csv(
+        cls, path: FilePath, *, delimiter: str = ",", formulas: bool = False,
+        limits: Limits | None = None,
+    ) -> Table:
+        selected = DEFAULT_LIMITS if limits is None else limits
+        return cls.from_csv(read_text(path, selected), delimiter=delimiter, formulas=formulas, limits=selected)
+
+    @property
+    def _root(self) -> Table:
+        return self
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return self._columns
+
+    @property
+    def _row_positions(self) -> range:
+        return range(len(self._rows))
+
+    @property
+    def _column_positions(self) -> range:
+        return range(len(self._columns))
+
+    def set(self, address: str, value: CellInput) -> None:
+        row, column = self._position(address)
+        if row == 0:
+            raise AddressError("Table headers cannot be edited as cells.")
+        cell = as_cell(value)
+        index = row - 1
+        changed = (*self._rows[index][:column], cell, *self._rows[index][column + 1:])
+        self._rows = (*self._rows[:index], changed, *self._rows[index + 1:])
+
+    def set_formula(self, address: str, formula: str, *, cached_value: Scalar = None) -> None:
+        self.set(address, Cell(cached_value, formula=formula))
+
+    def add_column(
+        self, name: str, values: Iterable[CellInput] | Callable[[Row], CellInput] | None = None,
+    ) -> None:
+        """Append blanks, an iterable or per-row results after validating every value."""
+        names = _columns((*self._columns, name), self._limits)
+        self._limits.check(len(self), len(names))
+        if values is None:
+            cells = [Cell() for _ in self._rows]
+        elif callable(values):
+            cells = [as_cell(values(row)) for row in self]
+        else:
+            if isinstance(values, (str, bytes)):
+                raise ShapeError("Column values must be a sequence of cells, not text.")
+            cells = []
+            for value in values:
+                if len(cells) >= len(self):
+                    raise ShapeError("A new column needs exactly one value per row.")
+                cells.append(as_cell(value))
+            if len(cells) != len(self):
+                raise ShapeError("A new column needs exactly one value per row.")
+        changed = tuple((*row, cell) for row, cell in zip(self._rows, cells, strict=True))
+        self._rows, self._columns = changed, names
+        self._column_lookup = {name: index for index, name in enumerate(names)}
+
+    def to_sheet(self, *, name: str = "Sheet1") -> Sheet:
+        return Sheet((self._columns, *self._rows), name=name, width=len(self.columns), limits=self._limits)
+
+
+class TableView(_Tabular):
+    """Fixed source membership with live values; selections never move formulas.
+
+    Create views with ``where``, ``select`` and ``sort_by``. Materialize using
+    ``to_table`` when independent values are required.
+    """
+
+    def __init__(self, source: Table, rows: Iterable[int], columns: Iterable[int]) -> None:
+        if not isinstance(source, Table):
+            raise ShapeError("A view requires a source Table.")
+
+        def positions(values, size, maximum):
+            result = []
+            for value in values:
+                if len(result) >= maximum:
+                    raise ShapeError("View dimensions exceed the configured limits.")
+                if type(value) is not int or not 0 <= value < size:
+                    raise ShapeError("View positions must be valid zero-based source indices.")
+                result.append(value)
+            return tuple(result)
+
+        self._source = source
+        self._selected_rows = positions(rows, len(source), source._limits.max_rows)
+        self._selected_columns = positions(columns, len(source.columns), source._limits.max_columns)
+        source._limits.check(len(self._selected_rows), len(self._selected_columns))
+        if len(set(self._selected_columns)) != len(self._selected_columns):
+            raise ShapeError("View columns must be unique.")
+        self._names = tuple(source.columns[index] for index in self._selected_columns)
+        self._column_lookup = dict(zip(self._names, self._selected_columns, strict=True))
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return self._names
+
+    @property
+    def _root(self) -> Table:
+        return self._source
+
+    @property
+    def _row_positions(self) -> tuple[int, ...]:
+        return self._selected_rows
+
+    @property
+    def _column_positions(self) -> tuple[int, ...]:
+        return self._selected_columns

headless_spreadsheets-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: headless-spreadsheets
+Version: 0.1.0
+Summary: Spreadsheet-native tables with typed cells and portable, dependency-free interchange.
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Source, https://github.com/outside-labs/headless_spreadsheets
+Project-URL: Issues, https://github.com/outside-labs/headless_spreadsheets/issues
+Description-Content-Type: text/markdown
+
+# Headless Spreadsheets
+
+Spreadsheet-native tables for ordinary Python applications. Pure Python 3.14+,
+zero runtime dependencies, MIT licensed.
+
+Keep typed values, formula text and cached results together, work with named
+records, and move data between Python, CSV, native JSON and table displays.
+
+```sh
+pip install headless-spreadsheets
+```
+
+## A table without a workbook
+
+```python
+from headless_spreadsheets import Table
+
+sales = Table.from_records([
+    {"item": "Book", "price": 12, "quantity": 3},
+    {"item": "Pen", "price": 2, "quantity": 10},
+    {"item": "Bag", "price": 25, "quantity": 2},
+])
+sales.add_column("total", lambda row: row["price"] * row["quantity"])
+
+report = sales.where(total__gte=30).sort_by("total", reverse=True)
+print(report.select("item", "total").to_markdown())
+```
+
+```markdown
+| item | total |
+| :--- | ---: |
+| Bag | 50 |
+| Book | 36 |
+```
+
+Rows behave like read-only dictionaries; columns behave like read-only
+sequences. Filtering, sorting and selection return views with fixed source
+membership and live values. They keep the original cells in place.
+
+## Preserve spreadsheet expressions
+
+```python
+sales.set_formula("D2", "=B2*C2", cached_value=36)
+cell = sales.cell("D2")
+assert cell.formula == "=B2*C2"
+assert cell.value == 36
+assert cell.cache_status == "stale"
+
+restored = Table.from_json(sales.to_json())
+assert restored.cell("D2") == cell
+```
+
+Table addresses include a header at row 1; data begins at row 2. `Sheet` is a
+rectangular grid without an implicit header, and `Workbook` contains named
+sheets. Literal strings starting with `=` remain text unless explicitly supplied
+as formulas.
+
+**v0.1 preserves formulas and supplied cached results; it does not calculate
+them.** Formula caches are always `stale` or `missing`. Unknown formulas stay
+inspectable and exportable. Views expose `source_address()` and retain original
+formula text; `view.to_table()` deliberately creates an independent values-only
+copy. Number-format hints are stored without being applied.
+
+## Interchange and display
+
+```python
+sales.to_json("sales.json")             # Types, formulas, cache and hints
+sales = Table.read_json("sales.json")
+sales.to_csv("sales.csv")               # Values; active text escaped by default
+text_table = Table.read_csv("sales.csv") # All imported fields are text
+sales.to_csv("sales.tsv", delimiter="\t")
+
+sales.to_markdown("sales.md")
+sales.to_html("sales.html")
+print(sales.to_ansi(max_width=24, color=True))
+print(sales.render("markdown", formulas=True))
+```
+
+Each export returns text and optionally writes a UTF-8 file atomically. Text
+readers are `from_csv(text)` and `from_json(text)`; path readers are `read_csv`
+and `read_json`. CSV loses Python types and blank-versus-empty distinctions.
+Explicit CSV formula modes are available. Native JSON is the fidelity format.
+HTML/Markdown escape content; terminal output neutralizes input controls.
+
+## Scope
+
+Supported cell values are blank (`None`), Boolean, integer, finite float, text,
+`Decimal`, `date` and `datetime`. Configurable `Limits` bound rows, columns,
+cells, sheets and serialized input. The core has no custom C/Rust extensions and
+requires no third-party packages. It makes no pandas-scale performance claim.
+
+Formula calculation, `F` expressions, XLSX, Google Sheets, Markdown/HTML import,
+grouping/joins, async execution and undo/history are later milestones. The native
+table writer has no Pretty Notebook dependency; shared typed Markdown extraction
+is tracked separately.
+
+- [API and behavior](https://github.com/outside-labs/headless_spreadsheets/blob/main/docs/api.md)
+- [Interchange contracts](https://github.com/outside-labs/headless_spreadsheets/blob/main/docs/formats.md)
+- [Presentation and Unicode limits](https://github.com/outside-labs/headless_spreadsheets/blob/main/docs/presentation.md)
+- [Implementation plan](https://github.com/outside-labs/headless_spreadsheets/blob/main/IMPLEMENTATION_PLAN.md)
+- [Project and queue](https://github.com/orgs/outside-labs/projects/16)
+
+## Development
+
+```sh
+uv sync --locked
+uv run --frozen python -W error::ResourceWarning -m unittest discover -s tests -v
+uv run --frozen python examples/sales.py
+uv run --frozen python scripts/check_distribution.py
+```
+
+CI tests Python 3.14 on Linux, macOS and Windows. Distribution verification
+checks exact archive contents, metadata, source bytes, source rebuild parity and
+the complete suite in independent wheel/source installations. See
+[release procedures](https://github.com/outside-labs/headless_spreadsheets/blob/main/docs/releases.md)
+for the tag-driven Trusted Publishing workflow.

headless_spreadsheets-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+headless_spreadsheets/__init__.py,sha256=tFO-HQvWALirRtBn0EWh9m_gxv9eJCACwnjDvFYREYo,623
+headless_spreadsheets/core.py,sha256=J09404BykiTIOZJ5NRg1CvEYiP4_LxV7GDwLU5pDBLI,8416
+headless_spreadsheets/errors.py,sha256=24dmUq5_0p4xfqjhDO16Z7eg9RVMTlJpR37hsnyCc2k,491
+headless_spreadsheets/file_io.py,sha256=MsSFkjvDaj9puPplNN3ppnm8gu-ZCRXoew_vfjNFFQw,1993
+headless_spreadsheets/formats.py,sha256=ai-x0ve1ctGu7YhPeTttbfXcEOxhFLEGA1Gaj2qK26g,1249
+headless_spreadsheets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+headless_spreadsheets/rendering.py,sha256=p-qqIWTA1Ez0e6uUwQ_D0icvlY1vK6sbkqMuUFwG5as,7168
+headless_spreadsheets/serialization.py,sha256=cJmGr9IoPXImvHUcS385aAM5rDut7xvYImk4bAM5O70,9243
+headless_spreadsheets/table.py,sha256=airpeAdHfWTsdSjJo7WVBbCN_AB0_7nnlN3IsdVwBiA,17496
+headless_spreadsheets-0.1.0.dist-info/licenses/LICENSE,sha256=MJiaArfnOql8NJRA2TI9JIYDOoiis3Rh8xQruzBRXoU,1066
+headless_spreadsheets-0.1.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
+headless_spreadsheets-0.1.0.dist-info/METADATA,sha256=PL9ovVrAc2XEd1uealNkVM1oAGSZsEbD_SA1OcalHAo,5410
+headless_spreadsheets-0.1.0.dist-info/RECORD,,

headless_spreadsheets-0.1.0.dist-info/WHEEL

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

headless_spreadsheets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ella Inng
+
+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.