headless-spreadsheets 0.1.0__tar.gz

headless_spreadsheets-0.1.0/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.

headless_spreadsheets-0.1.0/PKG-INFO

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

@@ -0,0 +1,116 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "headless-spreadsheets"
+version = "0.1.0"
+description = "Spreadsheet-native tables with typed cells and portable, dependency-free interchange."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.urls]
+Source = "https://github.com/outside-labs/headless_spreadsheets"
+Issues = "https://github.com/outside-labs/headless_spreadsheets/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

headless_spreadsheets-0.1.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "headless-spreadsheets"
+version = "0.1.0"
+description = "Spreadsheet-native tables with typed cells and portable, dependency-free interchange."
+readme = "README.md"
+authors = [
+    { name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/outside-labs/headless_spreadsheets"
+Issues = "https://github.com/outside-labs/headless_spreadsheets/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

headless_spreadsheets-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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