mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/spreadsheet.py

@@ -0,0 +1,803 @@
+"""The spreadsheet Reader: strict coordinates, cached formula values surfaced and flagged.
+
+A spreadsheet is not a table.  It is a drawing surface that usually has a table on it, and
+everything difficult about reading one follows from that sentence.  Two design decisions
+answer it, and both are unusual enough to be written down rather than left to be inferred.
+
+Strict coordinates
+------------------
+The recipe pins three things -- the sheet by name, the header row, and the cell range -- and
+every one of them is checked.  A workbook that grows a sheet, renames a tab, or shifts its
+table down two rows produces a named refusal rather than silently different data.  There is
+no sniffing, no "the first sheet", no "the first non-empty row", and no index-based sheet
+selection: sheet order changes without notice and an index would move a dataset from under a
+recipe whose digest never changed.
+
+The three coordinates are checked against each other as well as against the file.  The header
+row must be the range's first row, so every row inside the range is accounted for -- one
+header and the rest data -- and no row is silently neither.  A recipe whose range was edited
+without its header row is therefore a refusal that names the disagreement, rather than a
+dataset quietly missing its first records.
+
+Cached formula values, surfaced and flagged
+-------------------------------------------
+A formula's result is not in the file in any authoritative sense.  It is whatever the
+authoring application last cached, and nothing here recomputes it -- this is a Reader, not a
+spreadsheet engine.  Using the cached value is the only useful behaviour, and pretending it is
+the same as a typed value would be dishonest, so the decode reports ``contains_formula_cells``
+and the receipt carries it forward.  A reviewer looking at a dataset can then see that some of
+its numbers were somebody else's arithmetic.
+
+A formula with no cached value is refused rather than emitted as an empty cell.  An uncomputed
+formula is missing *information*; an empty cell is a stated absence of a value.  Collapsing
+the two would let a workbook that was never recalculated pass as a workbook full of blanks.
+
+That flag is read from evidence, which is what the two passes buy.  The workbook is loaded
+twice from the same bytes: once with ``data_only=True``, which yields the cached values, and
+once without, which yields each cell's type so a formula can be told from a string that merely
+begins with an equals sign.  Two bounded passes over an in-memory workbook is a fair price for
+a flag that is honest, and the price is stated here so it is not later optimised into a guess.
+
+The date rule, pinned
+---------------------
+Excel date handling is the single most common source of quiet corruption in spreadsheet
+ingestion, so the rule is stated with its examples rather than surrounded by caution.
+
+* The 1900 date system is the only one read.  A workbook declaring the 1904 system is refused
+  by name, because the two differ by four years and a day and the difference is invisible in
+  a recipe: the same coordinates would produce different dates with nothing to see.
+* A date or a datetime renders as ISO 8601 with a ``T`` separator and seconds always present:
+  ``2026-08-07T00:00:00`` for a date, ``2026-08-07T13:05:01`` for a datetime.  A date-only
+  cell is a datetime at midnight, because that is what the format stores.
+* A time-only cell renders as ``06:30:00``.
+* A duration is refused.  Excel stores one temporal type and a duration is a rendering of it
+  rather than a value in it, so there is no honest single text form.
+
+The float rule and the output encoding are not this module's to state.  Numbers reach the
+shared canonical emitter as binary64 values and are rendered there, by the one implementation
+every family emits through.  A spreadsheet is exactly where an engine's own string conversion
+would slip into the output unnoticed, so the engine's text never reaches it.
+
+Nothing on disk
+---------------
+The workbook is constructed from ``io.BytesIO`` with ``read_only=True``, never from a path.
+No API taking a filesystem path is named in this module, and a test observes two watched
+directories that are empty before and after a decode.
+
+The xlsx-is-a-zip boundary
+--------------------------
+An xlsx file is a zip of OOXML parts.  Those parts are the format's internal structure, not a
+user-visible container nesting, so the container families' "exactly one recipe-named member"
+rule does not apply to them and this family does not compose with ``archive.zip``.  What is
+shared with that module is the zip prefix table and the bounded read, because both modules are
+looking at the same bytes and a second copy of either would let them drift.  What is not
+shared is the member rule, and stating the difference here is cheaper than leaving a reader to
+wonder whether one was forgotten.
+
+A recipe wanting a zipped xlsx is therefore ``archive.zip`` naming the ``.xlsx`` member -- and
+the container family's nesting refusal will refuse it, because an xlsx is an archive by magic.
+That is a known limitation recorded in the Certification record with its reason, rather than a
+special case carved into the magic table.
+
+The engine, and why it is part of the pin
+-----------------------------------------
+``openpyxl`` at an exact version, with its XML backend checked at decode time.  ``openpyxl``
+chooses its parser at import from what it finds on the host, so a decoder whose parser depends
+on which other packages happen to be installed is a decoder that can answer differently on two
+hosts.  The pinned backend is the standard library's, and a host where the other one was
+selected is refused rather than decoded.  The full ruling, including why this family does not
+follow the design document's calamine pin, is in the Certification record.
+"""
+
+from __future__ import annotations
+
+import datetime
+import io
+import re
+import zipfile
+import zlib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import openpyxl.xml
+from openpyxl import load_workbook
+
+from mostlyright.data_harness.formats import (
+    FORMAT_MEDIA_TYPES,
+    FORMAT_SUFFIXES,
+    READER_CONTRACT_VERSION,
+    READER_OUTPUT_FORMATS,
+    READER_WORKER_MEMORY_BYTES,
+)
+from mostlyright.data_harness.readers.containers import (
+    ZIP_MAGICS,
+    read_bounded,
+    screen_zip_entry,
+)
+from mostlyright.data_harness.readers.contracts import (
+    DECODE_FLAGS,
+    ReaderBudgets,
+    ReaderError,
+    ReaderPin,
+    ReaderResult,
+)
+from mostlyright.data_harness.readers.registry import spreadsheet_default_budgets
+from mostlyright.data_harness.readers.tabular import (
+    check_declared_size,
+    encode_canonical_csv,
+    sealed_filename,
+)
+
+__all__ = [
+    "SPREADSHEET_MAX_DECLARED_CELLS",
+    "SPREADSHEET_MEDIA_TYPE",
+    "SPREADSHEET_WORST_CASE_BYTES",
+    "SpreadsheetReader",
+]
+
+# The one encoding a Reader may seal, unpacked rather than restated.
+(_OUTPUT_FORMAT,) = READER_OUTPUT_FORMATS
+_OUTPUT_MEDIA_TYPE = sorted(FORMAT_MEDIA_TYPES[_OUTPUT_FORMAT])[0]
+_OUTPUT_SUFFIX = sorted(FORMAT_SUFFIXES[_OUTPUT_FORMAT])[0]
+
+# The one media type this family admits as input.  Public because the acquisition layer asks
+# the Toolbox which media types a pinned fetch may accept, and a re-spelled literal at that
+# call site would be a second declaration of the same fact.
+SPREADSHEET_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+# Spreadsheet decoding retains the first pass's values while a second read-only pass identifies
+# formula cells.  The generic Reader ceiling of ten million cells permits Python-object overhead
+# to approach or exceed the Linux child boundary even when the compressed workbook is small.  This
+# family therefore admits a quarter-million cells.  The accounting deliberately charges 512 bytes
+# per retained cell plus four copies of the admitted expanded package and both byte envelopes; it
+# is conservative rather than self-calibrating and remains below the sandbox's exact process cap.
+SPREADSHEET_MAX_DECLARED_CELLS = spreadsheet_default_budgets().max_declared_cells
+_SPREADSHEET_MAX_UNCOMPRESSED_BYTES = spreadsheet_default_budgets().max_uncompressed_bytes
+_SPREADSHEET_CELL_MEMORY_ALLOWANCE = 512
+SPREADSHEET_WORST_CASE_BYTES = (
+    SPREADSHEET_MAX_DECLARED_CELLS * _SPREADSHEET_CELL_MEMORY_ALLOWANCE
+    + 4 * _SPREADSHEET_MAX_UNCOMPRESSED_BYTES
+    + 2 * 16 * 1024 * 1024
+)
+if SPREADSHEET_WORST_CASE_BYTES >= READER_WORKER_MEMORY_BYTES:
+    raise ReaderError(
+        "READER_BUDGET",
+        "reader.spreadsheet.memory",
+        "certified spreadsheet admission exceeds the Reader worker memory boundary",
+    )
+# The fact this family reports about itself, taken from the closed vocabulary rather than
+# spelled as a literal at the raise site.  A build in which the two have drifted apart fails at
+# import, which is the loudest and earliest place it can fail.
+_FORMULA_FLAG = "contains_formula_cells"
+if _FORMULA_FLAG not in DECODE_FLAGS:  # pragma: no cover - a contradiction caught at import
+    raise ReaderError(
+        "READER_OUTPUT",
+        "reader.spreadsheet.flags",
+        f"{_FORMULA_FLAG} is not in the closed decode-flag vocabulary",
+    )
+
+# The closed option set.  All three are required and there is no fourth: an option that was
+# accepted and ignored would be an unreviewable difference between two recipes that read
+# identically to everyone who looks at them.
+_OPTION_KEYS = ("header_row", "range", "sheet")
+
+# The parts every workbook package carries.  Checked by name so a zip that is not a workbook is
+# refused with a sentence rather than escaping as whichever exception the engine happened to
+# raise while looking for them.
+_REQUIRED_PARTS = ("[Content_Types].xml", "xl/workbook.xml")
+
+# Which parts are scanned before the engine sees them.  Text parts only: a binary part that
+# happened to contain these bytes is not a declaration, and refusing on one would be a false
+# refusal with no fix a person could apply.
+_TEXT_PART_SUFFIXES = (".xml", ".rels")
+
+# An XML document type may define an entity that names a resource outside the file, which is
+# the external-entity class.  The pinned backend refuses one on its own -- a test proves that
+# rather than assuming it -- and this is the layer in front of the engine, so the file is
+# refused before the engine is handed it at all.
+_DOCUMENT_TYPE = re.compile(rb"<!DOCTYPE|<!ENTITY", re.IGNORECASE)
+
+# A workbook may name a resource outside itself: an external link to another workbook, or a
+# relationship whose target is external.  Refused rather than followed, on the same reasoning
+# the acquisition parser already applies to a forbidden reference.
+_EXTERNAL_REFERENCE = re.compile(
+    rb"TargetMode\s*=\s*[\"']External[\"']|/relationships/externalLink",
+    re.IGNORECASE,
+)
+
+# The 1900 date system, as the engine spells its epoch.  The 1904 system is the other one the
+# format permits and is refused by name.
+_EPOCH_1900 = datetime.datetime(1899, 12, 30)
+_EPOCH_1904 = datetime.datetime(1904, 1, 1)
+
+# A sheet name is bounded text.  Thirty-one characters is the format's own ceiling, so a longer
+# one names a sheet no workbook could hold.
+_SHEET_NAME_MAX_CHARACTERS = 31
+
+# A plain cell reference: uppercase column letters and a row number, with no dollar signs and
+# no whole-row or whole-column form.  An absolute reference and a relative one mean the same
+# cell, and admitting both spellings would let two recipes with different digests seal the same
+# bytes.
+_CELL_REFERENCE = re.compile(r"^([A-Z]{1,3})([1-9][0-9]{0,6})$")
+
+# The format's own grid limits.  A coordinate outside them names a cell that cannot exist.
+_MAX_ROW = 1_048_576
+_MAX_COLUMN = 16_384
+
+
+def _column_index(letters: str) -> int:
+    """Turn column letters into a one-based index, on the format's base-26 rule."""
+
+    index = 0
+    for character in letters:
+        index = index * 26 + (ord(character) - ord("A") + 1)
+    return index
+
+
+def _column_letters(index: int) -> str:
+    """Turn a one-based column index back into letters, for a refusal a person can act on."""
+
+    letters = ""
+    while index > 0:
+        index, remainder = divmod(index - 1, 26)
+        letters = chr(ord("A") + remainder) + letters
+    return letters
+
+
+def _coordinate(row: int, column: int) -> str:
+    return f"{_column_letters(column)}{row}"
+
+
+def _cell_reference(value: str, subject: str) -> tuple[int, int]:
+    """Admit one plain cell reference as a (column, row) pair, or refuse it by name."""
+
+    matched = _CELL_REFERENCE.fullmatch(value)
+    if matched is None:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            f"{value!r} is not a plain cell reference such as A1; a whole row, a whole "
+            "column, a lower-case reference, and an absolute reference are all refused",
+        )
+    column = _column_index(matched.group(1))
+    row = int(matched.group(2))
+    if column > _MAX_COLUMN or row > _MAX_ROW:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            f"{value!r} names a cell outside the format's grid",
+        )
+    return column, row
+
+
+def _validate_range(value: Any, subject: str) -> tuple[int, int, int, int]:
+    """Admit a range as two plain cell references, the first at or before the second."""
+
+    if not isinstance(value, str) or value.count(":") != 1:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            "must be two plain cell references separated by a colon, such as A1:C4",
+        )
+    first, second = value.split(":")
+    start_column, start_row = _cell_reference(first, subject)
+    end_column, end_row = _cell_reference(second, subject)
+    if start_column > end_column or start_row > end_row:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            f"{value!r} runs backwards; a range states its top-left cell first",
+        )
+    return start_column, start_row, end_column, end_row
+
+
+def _validate_options(options: Any) -> dict[str, Any]:
+    """Admit this family's closed option set, refusing a missing or unknown key by name."""
+
+    subject = "reader.spreadsheet.xlsx.decode_options"
+    if not isinstance(options, Mapping):
+        raise ReaderError("READER_OPTIONS", subject, "must be an object")
+    unknown = sorted(str(key) for key in options if key not in _OPTION_KEYS)
+    if unknown:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            f"names no such setting: {', '.join(unknown)}; this family takes "
+            f"{', '.join(_OPTION_KEYS)}",
+        )
+    missing = sorted(key for key in _OPTION_KEYS if key not in options)
+    if missing:
+        raise ReaderError(
+            "READER_OPTIONS",
+            subject,
+            f"does not state: {', '.join(missing)}; a spreadsheet is read at pinned "
+            "coordinates and all three are required",
+        )
+
+    sheet = options["sheet"]
+    if (
+        not isinstance(sheet, str)
+        or isinstance(sheet, bool)
+        or not sheet
+        or len(sheet) > _SHEET_NAME_MAX_CHARACTERS
+        or any(character < " " or character == "\x7f" for character in sheet)
+    ):
+        raise ReaderError(
+            "READER_OPTIONS",
+            f"{subject}.sheet",
+            "must name one sheet, as bounded text; a sheet is never selected by index, "
+            "because sheet order changes without notice and would move a dataset silently",
+        )
+
+    header_row = options["header_row"]
+    if type(header_row) is not int or header_row < 1 or header_row > _MAX_ROW:
+        raise ReaderError(
+            "READER_OPTIONS",
+            f"{subject}.header_row",
+            "must be the whole number of the row that names the columns",
+        )
+
+    _validate_range(options["range"], f"{subject}.range")
+    return {"sheet": sheet, "header_row": header_row, "range": options["range"]}
+
+
+def _admit_workbook_bytes(content: Any, *, budgets: ReaderBudgets, subject: str) -> bytes:
+    """Admit the package's own bytes, before any decoder object is constructed."""
+
+    if not isinstance(content, (bytes, bytearray)):
+        raise ReaderError("READER_ADMISSION", subject, "must be exact bytes")
+    raw = bytes(content)
+    if len(raw) > budgets.max_input_bytes:
+        raise ReaderError("READER_BUDGET", subject, "exceeds the input byte budget")
+    if not any(raw.startswith(magic) for magic in ZIP_MAGICS):
+        raise ReaderError(
+            "READER_ADMISSION",
+            subject,
+            "does not begin as a workbook package",
+        )
+    return raw
+
+
+def _inspect_package(raw: bytes, *, budgets: ReaderBudgets, subject: str) -> None:
+    """Decide against the package's own directory, and read its text parts, before the engine.
+
+    Everything here happens with the engine still untouched.  The sizes come from the central
+    directory, so a package built to exhaust memory is refused with nothing inflated; the text
+    parts are then read under those checked declarations and scanned for the two things a
+    workbook may not say -- a document type, and a reference to a resource outside itself.
+    """
+
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(raw))
+    except (zipfile.BadZipFile, EOFError, ValueError, zlib.error) as error:
+        raise ReaderError(
+            "READER_ADMISSION",
+            subject,
+            "is not a readable workbook package",
+        ) from error
+
+    with archive:
+        # Reading the directory is the second call into the engine, and the structural test in
+        # ``tests/h3/test_readers_xlsx.py`` requires every one of them to be translated -- not
+        # because this one is known to raise, but because "known to raise" is exactly the
+        # judgement that let the part reads escape untyped in the first place.
+        try:
+            entries = archive.infolist()
+        except Exception as error:
+            raise ReaderError(
+                "READER_ADMISSION",
+                subject,
+                f"has a package directory that could not be read: {type(error).__name__}",
+            ) from error
+        if len(entries) > budgets.max_container_members:
+            raise ReaderError(
+                "READER_BUDGET",
+                subject,
+                f"holds {len(entries)} parts, over the part budget of "
+                f"{budgets.max_container_members}",
+            )
+        declared = sum(entry.file_size for entry in entries)
+        if declared > budgets.max_uncompressed_bytes:
+            raise ReaderError(
+                "READER_BUDGET",
+                subject,
+                f"declares {declared} uncompressed bytes across its parts, over the "
+                "uncompressed byte budget",
+            )
+        if declared > max(len(raw), 1) * budgets.max_expansion_ratio:
+            raise ReaderError(
+                "READER_BUDGET",
+                subject,
+                f"declares an expansion of {declared} from {len(raw)} bytes, over the "
+                f"expansion ratio budget of {budgets.max_expansion_ratio}",
+            )
+
+        names = {entry.filename for entry in entries}
+        absent = [part for part in _REQUIRED_PARTS if part not in names]
+        if absent:
+            raise ReaderError(
+                "READER_ADMISSION",
+                subject,
+                f"is a zip that carries no workbook: it has no {', '.join(absent)}",
+            )
+
+        for entry in entries:
+            if not entry.filename.endswith(_TEXT_PART_SUFFIXES):
+                continue
+            where = f"{subject}.part"
+            # The same three directory screens the zip family applies, from the same
+            # implementation.  Without them an encrypted part escapes as the bare
+            # ``RuntimeError`` ``ZipFile.open`` raises, and a part compressed by a method
+            # this interpreter was not built with escapes as ``NotImplementedError`` -- both
+            # outside the Reader contract's closed table and outside the worker's typed
+            # handler, so a refusal a recipe could repair arrives as a codeless crash.
+            screen_zip_entry(entry, subject=where, described=f"holds {entry.filename!r}")
+            part = _read_package_part(archive, entry, subject=where)
+            if _DOCUMENT_TYPE.search(part) is not None:
+                raise ReaderError(
+                    "READER_ADMISSION",
+                    where,
+                    f"{entry.filename} declares a document type; a document type may define "
+                    "an entity naming a resource outside the file, so the workbook is "
+                    "refused rather than parsed",
+                )
+            if _EXTERNAL_REFERENCE.search(part) is not None:
+                raise ReaderError(
+                    "READER_ADMISSION",
+                    where,
+                    f"{entry.filename} names an external resource; a workbook that points "
+                    "outside itself is refused rather than followed",
+                )
+
+
+def _read_package_part(archive: zipfile.ZipFile, entry: zipfile.ZipInfo, *, subject: str) -> bytes:
+    """Read one part of the package, mapping every engine failure to a typed refusal.
+
+    The directory screens above remove the two failures we know the name of; this removes the
+    class.  ``ZipFile.open`` and the read behind it reach CPython's zip and zlib layers, which
+    raise whatever their own layers raise, and an untyped escape from a decode is a refusal
+    with no code -- which the clean room reports as ``SANDBOX_UNEXPECTED`` and the remediation
+    map cannot bind a fix to.  ``ReaderError`` is re-raised first so a budget refusal from
+    ``read_bounded`` keeps its own code rather than being re-labelled here.
+    """
+
+    try:
+        with archive.open(entry, "r") as stream:
+            return read_bounded(stream, declared=entry.file_size, subject=subject)
+    except ReaderError:
+        raise
+    # Deliberately broad, and for the reason ``_load``'s handler is broad.  ``RuntimeError``
+    # and ``NotImplementedError`` are the two this module has met; naming only those two
+    # would leave the next one to escape untyped.
+    except Exception as error:
+        raise ReaderError(
+            "READER_ADMISSION",
+            subject,
+            f"{entry.filename} could not be read out of the workbook package: "
+            f"{type(error).__name__}",
+        ) from error
+
+
+def _check_backend(subject: str) -> None:
+    """Refuse a decode on a host whose XML backend is not the pinned one.
+
+    ``openpyxl`` selects its parser at import from what it finds on the host, so this is a
+    property of the environment rather than of the file -- which is why the refusal is a
+    contract refusal and why its message names both ways to fix the environment.
+    """
+
+    if openpyxl.xml.LXML:
+        raise ReaderError(
+            "READER_CONTRACT",
+            subject,
+            "is running on a host where openpyxl selected the lxml XML backend; this family "
+            "is pinned to the standard library backend, because a decoder whose parser "
+            "depends on which other packages are installed can answer differently on two "
+            "hosts. Uninstall lxml, or set OPENPYXL_LXML=0, and run the decode again",
+        )
+
+
+def _load(raw: bytes, *, data_only: bool, subject: str) -> Any:
+    """Open the workbook from bytes, read-only, mapping every engine failure to a typed one."""
+
+    try:
+        return load_workbook(io.BytesIO(raw), read_only=True, data_only=data_only)
+    except ReaderError:
+        raise
+    # Deliberately broad.  The engine raises whatever its own layers raise -- a missing part is
+    # a KeyError, a damaged package a BadZipFile, a malformed part a parse error -- and a
+    # refusal that escapes untyped is a refusal the remediation map cannot bind a fix to.
+    except Exception as error:
+        raise ReaderError(
+            "READER_ADMISSION",
+            subject,
+            f"could not be opened as a workbook: {type(error).__name__}",
+        ) from error
+
+
+def _declared_window(worksheet: Any, subject: str) -> tuple[int, int, int, int]:
+    """The used area the sheet declares, as (column, row, column, row), or a refusal.
+
+    A spreadsheet states its used range in the file, so the size of the answer is knowable
+    before the first cell is read.  A sheet that declares nothing is refused rather than
+    scanned to find out: the whole point of reading the declaration is to decide before
+    iterating, and a scan to discover the geometry is the iteration being avoided.
+    """
+
+    bounds = (
+        worksheet.min_column,
+        worksheet.min_row,
+        worksheet.max_column,
+        worksheet.max_row,
+    )
+    if any(type(value) is not int or value < 1 for value in bounds):
+        raise ReaderError(
+            "READER_ADMISSION",
+            subject,
+            "declares no used area, so the work it would take to read cannot be bounded "
+            "before it is done; re-save the workbook so it records its own dimensions",
+        )
+    return bounds
+
+
+def _admit_declared_window(
+    worksheet: Any,
+    budgets: ReaderBudgets,
+    subject: str,
+) -> tuple[int, int, int, int]:
+    """Read and admit declared geometry before any cell iterator is requested."""
+
+    window = _declared_window(worksheet, subject)
+    start_column, start_row, end_column, end_row = window
+    check_declared_size(
+        row_count=end_row - start_row + 1,
+        column_count=end_column - start_column + 1,
+        budgets=budgets,
+        subject=subject,
+    )
+    return window
+
+
+def _window_values(
+    worksheet: Any,
+    window: tuple[int, int, int, int],
+) -> tuple[tuple[Any, ...], ...]:
+    """The values of one bounded window, padded to the window's own width."""
+
+    start_column, start_row, end_column, end_row = window
+    width = end_column - start_column + 1
+    rows: list[tuple[Any, ...]] = []
+    for row in worksheet.iter_rows(
+        min_row=start_row,
+        max_row=end_row,
+        min_col=start_column,
+        max_col=end_column,
+        values_only=True,
+    ):
+        values = tuple(row)[:width]
+        rows.append(values + (None,) * (width - len(values)))
+    return tuple(rows)
+
+
+def _formula_cells(
+    worksheet: Any,
+    window: tuple[int, int, int, int],
+) -> frozenset[tuple[int, int]]:
+    """Which cells of the window hold a formula, read from the cell type and not from text.
+
+    A typed string beginning with an equals sign is a string.  The distinction is in the cell's
+    declared type, so that is what is read; inferring it from the value would flag exactly the
+    cells a careful author quoted on purpose.
+    """
+
+    start_column, start_row, end_column, end_row = window
+    found: set[tuple[int, int]] = set()
+    for row_offset, row in enumerate(
+        worksheet.iter_rows(
+            min_row=start_row,
+            max_row=end_row,
+            min_col=start_column,
+            max_col=end_column,
+        )
+    ):
+        for column_offset, cell in enumerate(row):
+            if cell.data_type == "f":
+                found.add((start_row + row_offset, start_column + column_offset))
+    return frozenset(found)
+
+
+def _column_names(header: Sequence[Any], start_column: int, row: int) -> tuple[str, ...]:
+    """The column names the header row states, refused rather than repaired."""
+
+    subject = "reader.spreadsheet.xlsx.header_row"
+    names: list[str] = []
+    for offset, value in enumerate(header):
+        if not isinstance(value, str) or not value.strip():
+            raise ReaderError(
+                "READER_RANGE",
+                subject,
+                f"cell {_coordinate(row, start_column + offset)} does not hold a column name; "
+                "an empty or non-text header cell is refused rather than auto-named",
+            )
+        names.append(value)
+    if len(set(names)) != len(names):
+        repeated = sorted({name for name in names if names.count(name) > 1})
+        raise ReaderError(
+            "READER_RANGE",
+            subject,
+            f"repeats a column name: {', '.join(repeated)}; a duplicate header is refused "
+            "rather than renamed, because a renamed column is a column nobody asked for",
+        )
+    return tuple(names)
+
+
+def _cell_value(value: Any, subject: str) -> Any:
+    """Give a temporal value its one stated text form and leave every other value alone.
+
+    Numbers, text, and booleans go on to the shared canonical emitter untouched, which is what
+    keeps the float rule in one place.  Temporal values are converted here because the format
+    stores one temporal type and the choice of text form is this family's to state.
+    """
+
+    if isinstance(value, datetime.datetime):
+        return value.isoformat(sep="T")
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    if isinstance(value, datetime.time):
+        return value.isoformat()
+    if isinstance(value, datetime.timedelta):
+        raise ReaderError(
+            "READER_OUTPUT",
+            subject,
+            "holds a duration; a duration is a rendering of a number rather than a value in "
+            "the file, so it has no honest single text form and is refused",
+        )
+    return value
+
+
+@dataclass(frozen=True)
+class SpreadsheetReader:
+    """``spreadsheet.xlsx``: one pinned window of one named sheet, opened from bytes.
+
+    The order of the work is backend, options, admission, package budgets and scan, values,
+    formula types, header, emit -- and the function below is written in that order, because
+    "refused before the engine sees it" is only true if the code says so.
+    """
+
+    family_id: str = "spreadsheet.xlsx"
+    family_version: str = "1.0.0"
+    contract_version: str = READER_CONTRACT_VERSION
+    output_format: str = _OUTPUT_FORMAT
+    accepted_media_types: tuple[str, ...] = (SPREADSHEET_MEDIA_TYPE,)
+    default_budgets: ReaderBudgets = field(default_factory=spreadsheet_default_budgets)
+
+    def validate_options(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
+        return _validate_options(options)
+
+    def decode(self, content: bytes, pin: ReaderPin, budgets: ReaderBudgets) -> ReaderResult:
+        subject = "reader.spreadsheet.xlsx"
+        _check_backend(subject)
+        options = _validate_options(pin.decode_options)
+        sheet_name = str(options["sheet"])
+        header_row = int(options["header_row"])
+        window = _validate_range(options["range"], f"{subject}.range")
+        start_column, start_row, end_column, end_row = window
+
+        raw = _admit_workbook_bytes(content, budgets=budgets, subject=subject)
+        _inspect_package(raw, budgets=budgets, subject=subject)
+
+        book = _load(raw, data_only=True, subject=subject)
+        try:
+            if book.epoch != _EPOCH_1900:
+                raise ReaderError(
+                    "READER_ADMISSION",
+                    subject,
+                    f"declares the {_EPOCH_1904:%Y} date system; this family reads the 1900 "
+                    "date system only, because the two differ by four years and a day and "
+                    "the difference is invisible in a recipe. Re-save the workbook under the "
+                    "1900 date system",
+                )
+            if sheet_name not in book.sheetnames:
+                raise ReaderError(
+                    "READER_SHEET_MISSING",
+                    f"{subject}.sheet",
+                    f"names {sheet_name!r}, which this workbook does not hold; it holds: "
+                    f"{', '.join(book.sheetnames)}",
+                )
+            worksheet = book[sheet_name]
+            used = _admit_declared_window(worksheet, budgets, f"{subject}.sheet")
+            used_start_column, used_start_row, used_end_column, used_end_row = used
+            if (
+                start_row < used_start_row
+                or start_column < used_start_column
+                or end_row > used_end_row
+                or end_column > used_end_column
+            ):
+                raise ReaderError(
+                    "READER_RANGE",
+                    f"{subject}.range",
+                    f"names {options['range']!r}, which reaches outside the used area this "
+                    f"sheet declares, "
+                    f"{_coordinate(used_start_row, used_start_column)}:"
+                    f"{_coordinate(used_end_row, used_end_column)}",
+                )
+            if header_row != start_row:
+                raise ReaderError(
+                    "READER_RANGE",
+                    f"{subject}.header_row",
+                    f"names row {header_row}, which is not the first row of the range "
+                    f"{options['range']!r}; the header row and the range must agree, so that "
+                    "every row inside the range is either the header or data and none is "
+                    "silently neither",
+                )
+            check_declared_size(
+                row_count=end_row - start_row + 1,
+                column_count=end_column - start_column + 1,
+                budgets=budgets,
+                subject=f"{subject}.range",
+            )
+            values = _window_values(worksheet, window)
+        finally:
+            book.close()
+
+        typed = _load(raw, data_only=False, subject=subject)
+        try:
+            formulas = _formula_cells(typed[sheet_name], window)
+        finally:
+            typed.close()
+
+        for row_index, column_index in sorted(formulas):
+            if values[row_index - start_row][column_index - start_column] is None:
+                raise ReaderError(
+                    "READER_ADMISSION",
+                    f"{subject}.cell",
+                    f"{_coordinate(row_index, column_index)} holds a formula with no cached "
+                    "value; an uncomputed formula is missing information rather than a "
+                    "missing value, so it is refused. Open and recalculate the workbook, then "
+                    "save it again",
+                )
+
+        columns = _column_names(values[0], start_column, start_row)
+        rows = tuple(
+            tuple(
+                _cell_value(value, f"{subject}.cell.{_coordinate(start_row + offset + 1, index)}")
+                for index, value in enumerate(row, start=start_column)
+            )
+            for offset, row in enumerate(values[1:])
+        )
+        return ReaderResult(
+            content=encode_canonical_csv(columns, rows, budgets=budgets),
+            data_format=_OUTPUT_FORMAT,
+            media_type=_OUTPUT_MEDIA_TYPE,
+            filename=sealed_filename(sheet_name, suffix=_OUTPUT_SUFFIX),
+            row_count=len(rows),
+            column_names=columns,
+            # Spreadsheet admission charges the complete used area declared by the sheet,
+            # including its header row, before iterating any selected cell. Preserve that
+            # family-specific geometry rather than reducing it to emitted data rows.
+            declared_cell_count=(used_end_row - used_start_row + 1)
+            * (used_end_column - used_start_column + 1),
+            flags=(_FORMULA_FLAG,) if formulas else (),
+        )
+
+
+@dataclass(frozen=True)
+class SpreadsheetReaderV1_1(SpreadsheetReader):
+    """``spreadsheet.xlsx@1.1.0`` admits the byte-stream label, and reads nothing new.
+
+    The same one-label delta as the container coordinates, for the same reason: a workbook
+    downloaded from an object store or a plain file server very often arrives as
+    ``application/octet-stream``, which says only that the server declined to describe it.
+    The admission behind the label is unchanged and decisive -- a workbook is a zip container
+    whose structure ``openpyxl`` validates, so a response that is not a workbook is refused
+    by its own bytes whatever the label said.  ``1.0.0`` stays closed to the weak label, and
+    a label that asserts a different format outright (``application/vnd.ms-excel`` is the
+    legacy XLS assertion) remains refused at both coordinates.
+    """
+
+    family_version: str = "1.1.0"
+    accepted_media_types: tuple[str, ...] = (
+        "application/octet-stream",
+        SPREADSHEET_MEDIA_TYPE,
+    )