adapt-server 0.2.6__tar.gz → 0.2.8__tar.gz

{adapt_server-0.2.6 → adapt_server-0.2.8}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: adapt-server
-Version: 0.2.6
+Version: 0.2.8
 Summary: Adaptive file-backed FastAPI server that turns datasets into CRUD APIs and UIs.
 Author-email: notesofcliff <notesofcliff@gmail.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/McInci/adapt
+Project-URL: Homepage, https://www.mcindi.com/software/adapt/
 Project-URL: Repository, https://github.com/McIndi/adapt
 Project-URL: Issues, https://github.com/McIndi/adapt/issues
 Keywords: fastapi,api,csv,excel,parquet,markdown,media

{adapt_server-0.2.6 → adapt_server-0.2.8}/adapt/__init__.py

@@ -1,3 +1,3 @@
 """Adapt package namespace."""
 
-__version__ = "0.2.6"
+__version__ = "0.2.8"

{adapt_server-0.2.6 → adapt_server-0.2.8}/adapt/discovery.py

@@ -23,9 +23,31 @@ class DatasetResource:
     schema_path: Path
     ui_path: Path
     plugin_name: str
+    options_path: Path | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
 
+def read_resource_options(options_path: Path) -> dict[str, Any]:
+    """Read a companion `.options.json` file, tolerating absence and bad content.
+
+    Options are hand-written, so a malformed file must not take the server down —
+    it is logged and ignored, leaving the resource on its defaults.
+    """
+    if not options_path.exists():
+        return {}
+    try:
+        with options_path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.error("Ignoring invalid options file %s: %s", options_path, exc)
+        return {}
+    if not isinstance(data, dict):
+        logger.error("Ignoring options file %s: expected a JSON object", options_path)
+        return {}
+    logger.debug("Loaded options from %s: %s", options_path, data)
+    return data
+
+
 def should_ignore(path: Path) -> bool:
     """Check if a path should be ignored during discovery.
 
@@ -91,9 +113,16 @@ def discover_resources(root: Path, config: AdaptConfig) -> list[DatasetResource]
             base_path = adapt_dir / path.relative_to(root)
             schema_path = base_path.with_suffix(f"{suffix}.schema.json")
             ui_path = base_path.with_suffix(f"{suffix}.index.html")
+            options_path = base_path.with_suffix(f"{suffix}.options.json")
 
             descriptor.schema_path = schema_path
             descriptor.ui_path = ui_path
+            descriptor.options_path = options_path
+
+            # Options must be applied before companion files are generated, so a
+            # schema derived from an overridden header row is written out correctly.
+            descriptor.metadata["options"] = read_resource_options(options_path)
+            plugin.apply_options(descriptor)
 
             plugin.generate_companion_files(descriptor)
 
@@ -103,6 +132,7 @@ def discover_resources(root: Path, config: AdaptConfig) -> list[DatasetResource]
                 resource_type=descriptor.resource_type,
                 schema_path=schema_path,
                 ui_path=ui_path,
+                options_path=options_path,
                 plugin_name=plugin_cls.__name__,
                 metadata=descriptor.metadata,
             )
@@ -115,4 +145,5 @@ def discover_resources(root: Path, config: AdaptConfig) -> list[DatasetResource]
 __all__ = [
     "DatasetResource",
     "discover_resources",
+    "read_resource_options",
 ]

{adapt_server-0.2.6 → adapt_server-0.2.8}/adapt/plugins/base.py

@@ -37,6 +37,7 @@ class ResourceDescriptor:
     resource_type: str
     schema_path: Path | None = None
     ui_path: Path | None = None
+    options_path: Path | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
 
@@ -77,6 +78,20 @@ class Plugin(ABC):
         """Write data/content for the resource."""
         ...
 
+    def apply_options(self, descriptor: ResourceDescriptor) -> None:
+        """Apply per-resource options to a descriptor after discovery has located them.
+
+        Options come from the companion `.adapt/<name>[.<sub_namespace>].options.json`
+        file and are already parsed into `descriptor.metadata["options"]`. This runs
+        after `load()` because `load()` receives only a path and cannot know where the
+        companion directory is; it runs before `generate_companion_files()` so that any
+        derived schema reflects the options.
+
+        The default does nothing. Plugins override this to honour the options they
+        support.
+        """
+        logger.debug(f"No options to apply for resource: {descriptor.path}")
+
     def get_route_configs(self, descriptor: ResourceDescriptor) -> list[tuple[str, APIRouter]]:
         """Return list of (prefix, router) tuples for mounting routes."""
         logger.debug(f"Getting route configs for resource: {descriptor.path}")

{adapt_server-0.2.6 → adapt_server-0.2.8}/adapt/plugins/dataset_plugin.py

@@ -19,6 +19,67 @@ from .base import Plugin, ResourceDescriptor, PluginContext, SearchDocument, ens
 
 logger = logging.getLogger(__name__)
 
+#: 1-based sheet/file row that holds the column names, unless a resource
+#: overrides it via `header_row` in its companion `.options.json`.
+DEFAULT_HEADER_ROW = 1
+
+#: Marks a companion schema.json as machine-written, so Adapt may refresh it when
+#: the resource's shape changes. A schema without this key is treated as
+#: hand-maintained and is never overwritten.
+GENERATED_MARKER = "generated_by"
+GENERATED_BY_ADAPT = "adapt"
+
+
+def resolve_header_row(resource: ResourceDescriptor) -> int:
+    """Return the 1-based header row for a resource, falling back to the default.
+
+    A bad override is logged and ignored rather than raised: the value is
+    hand-written into a companion file, and a typo should not break the resource.
+    """
+    raw = resource.metadata.get("header_row", DEFAULT_HEADER_ROW)
+    try:
+        header_row = int(raw)
+    except (TypeError, ValueError):
+        logger.error("Ignoring non-integer header_row %r for %s", raw, resource.path)
+        return DEFAULT_HEADER_ROW
+    if header_row < 1:
+        logger.error("Ignoring header_row %d for %s: must be >= 1", header_row, resource.path)
+        return DEFAULT_HEADER_ROW
+    return header_row
+
+
+def write_generated_schema(path: Path, schema: dict[str, Any]) -> bool:
+    """Write an auto-derived schema, refreshing a stale one but sparing hand-edits.
+
+    `ensure_file` would leave a stale schema in place forever, which matters once a
+    resource can be re-shaped by its options: a workbook switched to `header_row: 3`
+    would keep serving the old column names to the UI while the API returned the new
+    ones, and the table would render empty.
+
+    Returns True when the file was written.
+    """
+    payload = {GENERATED_MARKER: GENERATED_BY_ADAPT, **schema}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning("Leaving unreadable schema %s in place: %s", path, exc)
+            return False
+        if not isinstance(existing, dict) or existing.get(GENERATED_MARKER) != GENERATED_BY_ADAPT:
+            # Schemas written before the marker existed carry no provenance. One that
+            # still matches what we derive was ours, so adopt it; anything else is
+            # assumed hand-maintained and left alone.
+            if existing != schema:
+                logger.debug("Schema %s is hand-maintained; not regenerating", path)
+                return False
+            logger.debug("Adopting pre-marker generated schema %s", path)
+        if existing == payload:
+            return False
+        logger.info("Refreshing stale generated schema %s", path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return True
+
 
 def _guess_type(value: str | None) -> str:
     """Guess the data type of a string value."""
@@ -64,7 +125,12 @@ def _build_columns(header: Sequence[str], sample: Sequence[str | None]) -> dict[
 
 class DatasetPlugin(Plugin):
     """Base plugin for dataset-like resources (CSV, Excel, etc.)."""
-    
+
+    #: (path, sub_namespace) pairs already reported by `_warn_on_column_drift`,
+    #: so a misconfigured resource warns once rather than on every request.
+    _drift_warned: set[tuple[str, str]] = set()
+
+
     def load(self, path: Path) -> ResourceDescriptor:
         """Load a resource descriptor for the dataset."""
         header, sample = self._get_header_and_sample(path)
@@ -75,6 +141,22 @@ class DatasetPlugin(Plugin):
         logger.debug("Loaded descriptor for %s", path)
         return descriptor
 
+    def derive_schema(self, resource: ResourceDescriptor) -> dict[str, Any]:
+        """Build the schema from the descriptor's parsed header and sample row.
+
+        Kept separate from `schema()` because `schema()` prefers whatever is already
+        on disk; regenerating a companion file has to compare against a freshly
+        derived schema or it would only ever rewrite a stale file with itself.
+        """
+        header = resource.metadata.get("header", [])
+        sample = resource.metadata.get("sample_row", [])
+        return {
+            "type": "object",
+            "name": resource.path.stem,
+            "primary_key": resource.metadata.get("primary_key"),
+            "columns": _build_columns(header, sample),
+        }
+
     def schema(self, resource: ResourceDescriptor) -> dict[str, Any]:
         """Get the schema for the resource, with caching."""
         sub_namespace = resource.metadata.get("sub_namespace", "")
@@ -86,16 +168,10 @@ class DatasetPlugin(Plugin):
         if resource.schema_path and resource.schema_path.exists():
             with resource.schema_path.open() as f:
                 schema = json.load(f)
+            # Internal bookkeeping, not part of the published schema.
+            schema.pop(GENERATED_MARKER, None)
         else:
-            header = resource.metadata.get("header", [])
-            sample = resource.metadata.get("sample_row", [])
-            columns = _build_columns(header, sample)
-            schema = {
-                "type": "object",
-                "name": resource.path.stem,
-                "primary_key": resource.metadata.get("primary_key"),
-                "columns": columns,
-            }
+            schema = self.derive_schema(resource)
         set_cache(cache_key, schema, ttl_seconds=3600, resource=str(resource.path))  # 1 hour TTL
         logger.debug("Generated schema for %s", resource.path)
         return schema
@@ -105,6 +181,7 @@ class DatasetPlugin(Plugin):
         header = resource.metadata.get("header", [])
         schema = self.schema(resource)
         columns = schema.get("columns", {})
+        self._warn_on_column_drift(resource, header, columns)
         raw_rows = self._read_raw_rows(resource)
         
         # Apply Row-Level Security
@@ -170,6 +247,31 @@ class DatasetPlugin(Plugin):
         logger.debug("Indexed %d rows from %s", len(documents), resource.path)
         return documents
 
+    def _warn_on_column_drift(
+        self, resource: ResourceDescriptor, header: Sequence[str], columns: dict[str, Any]
+    ) -> None:
+        """Warn once when the schema's columns don't match the parsed header.
+
+        `read()` keys its row dicts off the header parsed from the file, while the
+        UI builds its table from the schema. If a hand-edited schema.json names
+        different columns the two never meet, and the table renders empty with no
+        error anywhere — so say something instead of failing silently.
+        """
+        if not columns or not header:
+            return
+        if list(columns) == list(header):
+            return
+        key = (str(resource.path), resource.metadata.get("sub_namespace", ""))
+        if key in self._drift_warned:
+            return
+        self._drift_warned.add(key)
+        logger.warning(
+            "Schema columns %s do not match the parsed header %s for %s%s; rows are keyed "
+            "by the header, so mismatched columns will render empty in the UI.",
+            list(columns), list(header), resource.path,
+            f" [{key[1]}]" if key[1] else "",
+        )
+
     def _convert_value(self, value: str, col_type: str) -> Any:
         """Convert a string value to the appropriate type."""
         if col_type == "integer":
@@ -448,8 +550,9 @@ class DatasetPlugin(Plugin):
         logger.debug(f"Generating companion files for {descriptor.path}")
         # Generate schema.json
         if descriptor.schema_path:
-            schema = self.schema(descriptor)
-            ensure_file(descriptor.schema_path, json.dumps(schema, indent=2))
+            if write_generated_schema(descriptor.schema_path, self.derive_schema(descriptor)):
+                # The cached copy describes the shape we just replaced.
+                invalidate_cache(str(descriptor.path))
             logger.debug(f"Generated schema.json at {descriptor.schema_path}")
 
         # Generate index.html using datatable.html template

adapt_server-0.2.8/adapt/plugins/excel_plugin.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+import logging
+from adapt.cache import get_cache, set_cache, invalidate_cache
+
+from itertools import zip_longest
+from pathlib import Path
+from typing import Any, Iterator, Sequence
+
+from openpyxl import load_workbook
+
+from .base import ResourceDescriptor, atomic_write
+from .dataset_plugin import DEFAULT_HEADER_ROW, DatasetPlugin, resolve_header_row
+
+
+logger = logging.getLogger(__name__)
+
+
+def _is_blank(value: Any) -> bool:
+    """True for a cell holding nothing a reader would call a value."""
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def _merge_formula(value: Any, formula: Any) -> Any:
+    """Fall back to a cell's formula text when it has no cached result.
+
+    openpyxl reports only the value Excel last calculated and stored in the file.
+    A workbook written by openpyxl itself carries no cached results at all, so
+    under `data_only=True` every formula cell reads back as None and the column
+    renders blank. Surfacing the formula is worse than a number and much better
+    than an empty column with nothing to explain it.
+    """
+    if value is not None:
+        return value
+    if isinstance(formula, str) and formula.startswith("="):
+        return formula
+    return value
+
+
+def _merged_rows(value_sheet: Any, formula_sheet: Any) -> Iterator[tuple[int, list[Any]]]:
+    """Yield (1-based row number, cells) for a sheet, formulas filled in.
+
+    Both sheets are streamed in lockstep so a large workbook is never fully
+    materialised. `zip_longest` guards the case where the two passes disagree on
+    width rather than silently truncating a row.
+    """
+    paired = zip_longest(
+        value_sheet.iter_rows(values_only=True),
+        formula_sheet.iter_rows(values_only=True),
+        fillvalue=(),
+    )
+    for row_number, (value_row, formula_row) in enumerate(paired, start=1):
+        yield row_number, [
+            _merge_formula(value, formula)
+            for value, formula in zip_longest(value_row or (), formula_row or ())
+        ]
+
+
+def _extract_header_and_sample(
+    value_sheet: Any, formula_sheet: Any, header_row: int
+) -> tuple[list[Any], list[Any]]:
+    """Return the header cells and the first non-blank row beneath them."""
+    header: list[Any] = []
+    sample: list[Any] = []
+    for row_number, cells in _merged_rows(value_sheet, formula_sheet):
+        if row_number < header_row:
+            continue
+        if row_number == header_row:
+            header = cells
+            continue
+        if all(_is_blank(cell) for cell in cells):
+            continue
+        sample = cells
+        break
+    return header, sample
+
+
+class ExcelPlugin(DatasetPlugin):
+    @property
+    def resource_type(self) -> str:
+        """Return the resource type string."""
+        return "excel"
+
+    def detect(self, path: Path) -> bool:
+        """Detect if the path is an Excel file.
+
+        Args:
+            path: The file path to check.
+
+        Returns:
+            True if the file has .xlsx extension, False otherwise.
+        """
+        return path.suffix.lower() == ".xlsx"
+
+    def load(self, path: Path) -> Sequence[ResourceDescriptor]:
+        """Load Excel file and create descriptors for each worksheet.
+
+        Every sheet is read at the default header row; a sheet that overrides it
+        is re-read later by `apply_options`, once discovery has located the
+        companion options file.
+
+        Args:
+            path: The path to the Excel file.
+
+        Returns:
+            A sequence of ResourceDescriptors, one for each worksheet.
+        """
+        logger.debug(f"Loading Excel file: {path}")
+        descriptors = []
+        with self._open_pair(path) as (values, formulas):
+            for sheet_name in values.sheetnames:
+                logger.debug(f"Processing sheet: {sheet_name}")
+                descriptor = ResourceDescriptor(path=path, resource_type=self.resource_type)
+                descriptor.metadata["primary_key"] = "_row_id"
+                descriptor.metadata["sub_namespace"] = sheet_name
+                self._set_header_metadata(
+                    descriptor, values[sheet_name], formulas[sheet_name], DEFAULT_HEADER_ROW
+                )
+                descriptors.append(descriptor)
+        logger.info(f"Loaded {len(descriptors)} worksheets from Excel file: {path}")
+        return descriptors
+
+    def apply_options(self, descriptor: ResourceDescriptor) -> None:
+        """Honour a `header_row` override from the companion options file.
+
+        Sheets often open with a title banner rather than column names, which
+        would otherwise be parsed as the header and turn a sentence into a column
+        name. Setting `{"header_row": 3}` points Adapt at the real header.
+        """
+        options = descriptor.metadata.get("options") or {}
+        if "header_row" not in options:
+            return
+
+        descriptor.metadata["header_row"] = options["header_row"]
+        header_row = resolve_header_row(descriptor)
+        descriptor.metadata["header_row"] = header_row
+        if header_row == DEFAULT_HEADER_ROW:
+            return
+
+        sheet_name = descriptor.metadata["sub_namespace"]
+        logger.info(
+            "Re-reading header of %s [%s] from row %d", descriptor.path, sheet_name, header_row
+        )
+        with self._open_pair(descriptor.path) as (values, formulas):
+            self._set_header_metadata(
+                descriptor, values[sheet_name], formulas[sheet_name], header_row
+            )
+        # Rows cached under the previous header row describe a different shape.
+        invalidate_cache(str(descriptor.path))
+
+    def _read_raw_rows(self, resource: ResourceDescriptor) -> list[list[str]]:
+        """Read raw rows from the Excel worksheet.
+
+        Rows that are entirely empty are dropped, and the sheet's extent is taken
+        from the rows that actually carry values rather than from the declared
+        `<dimension>`. Writers routinely leave styled-but-valueless cells behind
+        (a whole formatted column, say), which inflates the dimension and would
+        otherwise surface as hundreds of blank records. Note that openpyxl's
+        `reset_dimensions()` is not a fix here — it falls back to the sheet
+        maximum and yields over a million empty rows.
+
+        Args:
+            resource: The resource descriptor.
+
+        Returns:
+            A list of rows as lists of strings.
+        """
+        sub_namespace = resource.metadata["sub_namespace"]
+        header_row = resolve_header_row(resource)
+        logger.debug(f"Reading raw rows from Excel sheet: {sub_namespace}")
+        cache_key = f"data:{resource.path}:{sub_namespace}:{header_row}"
+        cached = get_cache(cache_key, str(resource.path))
+        if cached:
+            logger.debug(f"Cache hit for Excel data: {resource.path}")
+            return cached
+
+        logger.debug(f"Cache miss, reading from Excel file: {resource.path}")
+        width = len(resource.metadata.get("header") or [])
+        rows: list[list[str]] = []
+        skipped = 0
+        with self._open_pair(resource.path) as (values, formulas):
+            merged = _merged_rows(values[sub_namespace], formulas[sub_namespace])
+            for row_number, cells in merged:
+                if row_number <= header_row:
+                    continue
+                if all(_is_blank(cell) for cell in cells):
+                    skipped += 1
+                    continue
+                row = ["" if cell is None else str(cell) for cell in cells]
+                if width:
+                    row = (row + [""] * width)[:width]
+                rows.append(row)
+
+        if skipped:
+            logger.debug(
+                "Skipped %d empty rows in %s [%s]", skipped, resource.path, sub_namespace
+            )
+        set_cache(cache_key, rows, ttl_seconds=300, resource=str(resource.path))  # 5 min TTL
+        return rows
+
+    def _write_rows(self, resource: ResourceDescriptor, rows: list[dict[str, Any]], header: list[str]) -> None:
+        """Write rows to the Excel worksheet.
+
+        Args:
+            resource: The resource descriptor.
+            rows: The rows to write.
+            header: The column headers.
+        """
+        sub_namespace = resource.metadata["sub_namespace"]
+        header_row = resolve_header_row(resource)
+        first_data_row = header_row + 1
+        logger.info(f"Writing rows to Excel worksheet: {sub_namespace}")
+        workbook = load_workbook(resource.path)
+        try:
+            sheet = workbook[sub_namespace]
+            # Clear existing data, leaving the header and anything above it intact.
+            for row in sheet.iter_rows(min_row=first_data_row):
+                for cell in row:
+                    cell.value = None
+            # Write new data
+            for row_idx, row_data in enumerate(rows, start=first_data_row):
+                for col_idx, col_name in enumerate(header):
+                    sheet.cell(row=row_idx, column=col_idx+1).value = row_data.get(col_name, "")
+
+            def write_tmp(tmp_path: Path) -> None:
+                workbook.save(tmp_path)
+
+            atomic_write(resource.path, ".xlsx", write_tmp)
+        finally:
+            workbook.close()
+
+        # Invalidate cache after mutation
+        invalidate_cache(str(resource.path))
+        logger.debug(f"Successfully wrote {len(rows)} rows to Excel file: {resource.path}")
+
+    def _set_header_metadata(
+        self, descriptor: ResourceDescriptor, value_sheet: Any, formula_sheet: Any, header_row: int
+    ) -> None:
+        """Parse the header and sample row for a sheet into descriptor metadata."""
+        from .dataset_plugin import _ensure_header
+
+        header, sample = _extract_header_and_sample(value_sheet, formula_sheet, header_row)
+        descriptor.metadata["header"] = _ensure_header(header)
+        descriptor.metadata["sample_row"] = [
+            str(cell) if cell is not None else None for cell in sample
+        ]
+        descriptor.metadata["header_row"] = header_row
+
+    @staticmethod
+    def _open_pair(path: Path) -> "_WorkbookPair":
+        """Open the workbook twice: once for cached values, once for formulas.
+
+        Two passes are the only way to tell "empty cell" from "formula whose
+        result was never cached" — openpyxl surfaces one or the other, never both.
+        Both are read-only and streamed, and the result is cached for 5 minutes,
+        so the second parse is paid rarely.
+        """
+        return _WorkbookPair(path)
+
+
+class _WorkbookPair:
+    """Context manager yielding (values_workbook, formulas_workbook)."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    def __enter__(self) -> tuple[Any, Any]:
+        self._values = load_workbook(self._path, read_only=True, data_only=True)
+        try:
+            self._formulas = load_workbook(self._path, read_only=True, data_only=False)
+        except Exception:
+            self._values.close()
+            raise
+        return self._values, self._formulas
+
+    def __exit__(self, *exc_info: Any) -> None:
+        try:
+            self._formulas.close()
+        finally:
+            self._values.close()

{adapt_server-0.2.6 → adapt_server-0.2.8}/adapt/templates/datatable.html

@@ -53,8 +53,8 @@
                 <form id="createForm">
                     {% for col_name, col_info in schema.columns.items() %}
                     <div class="mb-3">
-                        <label for="create_{{ col_name }}" class="form-label">{{ col_name }}</label>
-                        <input type="text" class="form-control" id="create_{{ col_name }}" name="{{ col_name }}">
+                        <label for="create_col_{{ loop.index0 }}" class="form-label">{{ col_name }}</label>
+                        <input type="text" class="form-control" id="create_col_{{ loop.index0 }}" name="{{ col_name }}">
                     </div>
                     {% endfor %}
                 </form>
@@ -80,8 +80,8 @@
                     <input type="hidden" id="edit_row_id" name="_row_id">
                     {% for col_name, col_info in schema.columns.items() %}
                     <div class="mb-3">
-                        <label for="edit_{{ col_name }}" class="form-label">{{ col_name }}</label>
-                        <input type="text" class="form-control" id="edit_{{ col_name }}" name="{{ col_name }}">
+                        <label for="edit_col_{{ loop.index0 }}" class="form-label">{{ col_name }}</label>
+                        <input type="text" class="form-control" id="edit_col_{{ loop.index0 }}" name="{{ col_name }}">
                     </div>
                     {% endfor %}
                 </form>
@@ -102,7 +102,16 @@
 
 <script>
     let dataTable;
-    const apiUrl = '{{ api_url }}';
+    const apiUrl = {{ api_url | tojson }};
+
+    // Column names are data, not code. They come from a spreadsheet header or a
+    // hand-written schema, so they may contain spaces, quotes, parentheses, dots
+    // or a leading digit. Interpolating them into JS expressions turns a column
+    // named "Total (net)" into a syntax error that takes down this whole script
+    // -- including the DataTable init below -- and the table renders as a bare
+    // header with no rows and nothing in the console to explain it. Everything
+    // below indexes into this array instead.
+    const COLUMNS = {{ schema.columns | list | tojson }};
 
     function csrfHeaders(headers = {}) {
         const token = window.getAdaptCsrfToken ? window.getAdaptCsrfToken() : '';
@@ -124,26 +133,40 @@
                     alert('Error loading data: ' + error);
                 }
             },
-            columns: [
-                {% for col_name, col_info in schema.columns.items() %}
-                    { data: '{{ col_name }}' },
-            {% endfor %}
-                    {% if not readonly %}
-                    {
+            columns: buildColumns()
+        });
+    });
+
+    function buildColumns() {
+        // An accessor function rather than `data: name`: DataTables parses a
+        // string source as object notation, so a column called "Q1.Revenue"
+        // would be looked up as row.Q1.Revenue and quietly resolve to nothing.
+        const columns = COLUMNS.map(function (name) {
+            return {
+                data: function (row) { return row[name]; },
+                defaultContent: '',
+                render: $.fn.dataTable.render.text()
+            };
+        });
+
+        {% if not readonly %}
+        // Guarded by Jinja rather than at runtime so a read-only page never ships
+        // write controls, not even as unreachable markup.
+        columns.push({
             data: null,
             orderable: false,
             searchable: false,
             render: function (data, type, row) {
                 return `
-                                <button class="btn btn-sm btn-warning me-1" onclick="editRecord(${row._row_id})">Edit</button>
-                                <button class="btn btn-sm btn-danger" onclick="deleteRecord(${row._row_id})">Delete</button>
-                            `;
+                    <button class="btn btn-sm btn-warning me-1" onclick="editRecord(${row._row_id})">Edit</button>
+                    <button class="btn btn-sm btn-danger" onclick="deleteRecord(${row._row_id})">Delete</button>
+                `;
             }
-        }
-                    {% endif %}
-                ]
-            });
         });
+        {% endif %}
+
+        return columns;
+    }
 
     {% if not readonly %}
     function createRecord() {
@@ -180,9 +203,12 @@
         const rowData = dataTable.rows().data().toArray().find(row => row._row_id === rowId);
         if (rowData) {
             document.getElementById('edit_row_id').value = rowId;
-            {% for col_name, col_info in schema.columns.items() %}
-            document.getElementById('edit_{{ col_name }}').value = rowData.{{ col_name }};
-            {% endfor %}
+            COLUMNS.forEach(function (name, index) {
+                const input = document.getElementById('edit_col_' + index);
+                if (input) {
+                    input.value = rowData[name] ?? '';
+                }
+            });
             const modal = bootstrap.Modal.getOrCreateInstance(document.getElementById('editModal'));
             modal.show();
         }