reflet 0.1.0__py3-none-any.whl

reflet/sources/__init__.py

@@ -0,0 +1,88 @@
+"""Source backends: read a table from storage, and write edits back."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import tempfile
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import IO, Any
+
+from reflet.lens import RowId, Table
+
+
+class SourceBackend(ABC):
+    """Reads/writes a table to a concrete storage format.
+
+    `key`, when given, is the source field whose value uniquely identifies a
+    row (its `RowId`); rows keep that identity across reads, so write-back
+    survives reordering or insertion done outside reflet. With no key, a
+    row's identity is its position in the file.
+    """
+
+    def __init__(self, path: str, key: str | None = None) -> None:
+        self.path                        = path
+        self.key                         = key
+        self.fieldnames: list[str]       = []
+        self._order: list[RowId]         = []
+        self._fingerprint: str | None    = None
+
+    @abstractmethod
+    def read(self) -> Table: ...
+
+    @abstractmethod
+    def write(self, table: Table) -> None: ...
+
+    def changed_since_read(self) -> bool:
+        """Whether the file on disk differs from what was last read/written."""
+        if self._fingerprint is None:
+            return False
+        return self._file_hash() != self._fingerprint
+
+    def _file_hash(self) -> str:
+        with open(self.path, "rb") as fh:
+            return hashlib.sha256(fh.read()).hexdigest()
+
+    def _remember_fingerprint(self) -> None:
+        self._fingerprint = self._file_hash()
+
+
+def atomic_write(path: str, write_fn: Callable[[IO[str]], None]) -> None:
+    """Write via a temp file + os.replace so readers never see a partial file."""
+    directory       = os.path.dirname(os.path.abspath(path)) or "."
+    fd, tmp_path    = tempfile.mkstemp(dir=directory, prefix=".reflet-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", newline="", encoding="utf-8") as fh:
+            write_fn(fh)
+        os.replace(tmp_path, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.remove(tmp_path)
+        raise
+
+
+def infer_scalar(raw: str) -> Any:
+    """Best-effort conversion of a CSV string cell to int/float/bool/str."""
+    if raw == "":
+        return raw
+    if raw in ("True", "False"):
+        return raw == "True"
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    return raw
+
+
+def render_scalar(value: object) -> str:
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, float | int):
+        return str(value)
+    return "" if value is None else str(value)

reflet/sources/csv_source.py

@@ -0,0 +1,55 @@
+"""CSV source backend."""
+
+from __future__ import annotations
+
+import csv
+from typing import IO
+
+from reflet.lens import Cell, Record, RowId, Table
+from reflet.provenance import Provenance
+from reflet.sources import SourceBackend, atomic_write, infer_scalar, render_scalar
+
+
+class CsvSource(SourceBackend):
+    def read(self) -> Table:
+        with open(self.path, newline="", encoding="utf-8") as fh:
+            reader                = csv.DictReader(fh)
+            self.fieldnames       = list(reader.fieldnames or [])
+            table: Table          = []
+            seen: set[RowId]      = set()
+            order: list[RowId]    = []
+            for i, raw_row in enumerate(reader):
+                fields = {
+                    k: Cell(infer_scalar(v), Provenance(self.path, k)) for k, v in raw_row.items()
+                }
+                rid: RowId = i
+                if self.key is not None:
+                    if self.key not in fields:
+                        raise ValueError(
+                            f"{self.path}: key field {self.key!r} missing on row {i}"
+                        )
+                    rid = fields[self.key].value
+                    if rid in seen:
+                        raise ValueError(f"{self.path}: duplicate key {self.key}={rid!r}")
+                seen.add(rid)
+                order.append(rid)
+                table.append(Record(rid, fields))
+        self._order = order
+        self._remember_fingerprint()
+        return table
+
+    def write(self, table: Table) -> None:
+        fieldnames    = self.fieldnames or (list(table[0].fields.keys()) if table else [])
+        by_rid        = {r.rid: r for r in table}
+
+        def _write(fh: IO[str]) -> None:
+            writer = csv.DictWriter(fh, fieldnames=fieldnames)
+            writer.writeheader()
+            for rid in self._order:
+                record = by_rid.get(rid)
+                if record is None:
+                    continue
+                writer.writerow({k: render_scalar(record.fields[k].value) for k in fieldnames})
+
+        atomic_write(self.path, _write)
+        self._remember_fingerprint()

reflet/sources/json_path_source.py

@@ -0,0 +1,93 @@
+"""JSON source addressing a list nested inside a larger document, by path.
+
+`rows_at="servers"` (or the more explicit "servers[*]") treats
+`doc["servers"]` as the table; everything else in the document is kept
+byte-for-byte except for that one list on write-back. Only a single,
+non-wildcard-in-the-middle dotted path is supported (e.g. "a.b.servers");
+a path like "a[*].b" addressing more than one list isn't.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import IO, Any
+
+from reflet.lens import Cell, Record, RowId, Table
+from reflet.provenance import Provenance
+from reflet.sources import SourceBackend, atomic_write
+
+
+def _path_parts(path: str) -> list[str]:
+    cleaned = path[:-3] if path.endswith("[*]") else path
+    return [p for p in cleaned.split(".") if p]
+
+
+def _get_path(doc: Any, path: str) -> Any:
+    node = doc
+    for part in _path_parts(path):
+        if not isinstance(node, dict) or part not in node:
+            raise ValueError(f"path {path!r}: no key {part!r}")
+        node = node[part]
+    return node
+
+
+def _set_path(doc: Any, path: str, value: Any) -> None:
+    parts    = _path_parts(path)
+    node     = doc
+    for part in parts[:-1]:
+        node = node[part]
+    node[parts[-1]] = value
+
+
+class JsonPathSource(SourceBackend):
+    def __init__(self, path: str, row_path: str, key: str | None = None) -> None:
+        super().__init__(path, key)
+        self.row_path         = row_path
+        self._raw_doc: Any    = None
+
+    def read(self) -> Table:
+        with open(self.path, encoding="utf-8") as fh:
+            self._raw_doc = json.load(fh)
+        rows = _get_path(self._raw_doc, self.row_path)
+        if not isinstance(rows, list):
+            raise ValueError(f"{self.path}: path {self.row_path!r} doesn't resolve to a list")
+        if rows:
+            self.fieldnames = list(rows[0].keys())
+
+        table: Table          = []
+        seen: set[RowId]      = set()
+        order: list[RowId]    = []
+        source_name           = f"{self.path}#{self.row_path}"
+        for i, raw_row in enumerate(rows):
+            fields        = {k: Cell(v, Provenance(source_name, k)) for k, v in raw_row.items()}
+            rid: RowId    = i
+            if self.key is not None:
+                if self.key not in fields:
+                    raise ValueError(f"{source_name}: key field {self.key!r} missing on row {i}")
+                rid = fields[self.key].value
+                if rid in seen:
+                    raise ValueError(f"{source_name}: duplicate key {self.key}={rid!r}")
+            seen.add(rid)
+            order.append(rid)
+            table.append(Record(rid, fields))
+        self._order = order
+        self._remember_fingerprint()
+        return table
+
+    def write(self, table: Table) -> None:
+        by_rid      = {r.rid: r for r in table}
+        new_rows    = []
+        for rid in self._order:
+            record = by_rid.get(rid)
+            if record is None:
+                continue
+            keys = self.fieldnames or list(record.fields.keys())
+            new_rows.append({k: record.fields[k].value for k in keys})
+        _set_path(self._raw_doc, self.row_path, new_rows)
+
+        def _write(fh: IO[str]) -> None:
+            json.dump(self._raw_doc, fh, indent=2)
+            fh.write("\n")
+
+        atomic_write(self.path, _write)
+        self._remember_fingerprint()

reflet/sources/json_source.py

@@ -0,0 +1,56 @@
+"""JSON source backend: a file containing a list of flat objects."""
+
+from __future__ import annotations
+
+import json
+from typing import IO
+
+from reflet.lens import Cell, Record, RowId, Table
+from reflet.provenance import Provenance
+from reflet.sources import SourceBackend, atomic_write
+
+
+class JsonSource(SourceBackend):
+    def read(self) -> Table:
+        with open(self.path, encoding="utf-8") as fh:
+            raw = json.load(fh)
+        if not isinstance(raw, list):
+            raise ValueError(f"{self.path}: expected a JSON array of objects")
+        if raw:
+            self.fieldnames = list(raw[0].keys())
+
+        table: Table          = []
+        seen: set[RowId]      = set()
+        order: list[RowId]    = []
+        for i, raw_row in enumerate(raw):
+            fields        = {k: Cell(v, Provenance(self.path, k)) for k, v in raw_row.items()}
+            rid: RowId    = i
+            if self.key is not None:
+                if self.key not in fields:
+                    raise ValueError(f"{self.path}: key field {self.key!r} missing on row {i}")
+                rid = fields[self.key].value
+                if rid in seen:
+                    raise ValueError(f"{self.path}: duplicate key {self.key}={rid!r}")
+            seen.add(rid)
+            order.append(rid)
+            table.append(Record(rid, fields))
+        self._order = order
+        self._remember_fingerprint()
+        return table
+
+    def write(self, table: Table) -> None:
+        by_rid = {r.rid: r for r in table}
+
+        def _write(fh: IO[str]) -> None:
+            rows = []
+            for rid in self._order:
+                record = by_rid.get(rid)
+                if record is None:
+                    continue
+                keys = self.fieldnames or list(record.fields.keys())
+                rows.append({k: record.fields[k].value for k in keys})
+            json.dump(rows, fh, indent=2)
+            fh.write("\n")
+
+        atomic_write(self.path, _write)
+        self._remember_fingerprint()

reflet/sources/sqlite_source.py

@@ -0,0 +1,83 @@
+"""SQLite source backend, via the stdlib `sqlite3` module."""
+
+from __future__ import annotations
+
+import sqlite3
+
+from reflet.lens import Cell, Record, RowId, Table
+from reflet.provenance import Provenance
+from reflet.sources import SourceBackend
+
+
+def _quote_identifier(identifier: str) -> str:
+    return '"' + identifier.replace('"', '""') + '"'
+
+
+class SqliteSource(SourceBackend):
+    """Reads/writes one table of a SQLite database file.
+
+    Write-back replaces the table's contents wholesale (delete + reinsert,
+    in one transaction) rather than diffing individual rows, same as the
+    CSV/JSON backends: only the columns seen on read are written back.
+    """
+
+    def __init__(self, path: str, table: str, key: str | None = None) -> None:
+        super().__init__(path, key)
+        self.table = table
+
+    def read(self) -> Table:
+        conn = sqlite3.connect(self.path)
+        try:
+            conn.row_factory    = sqlite3.Row
+            cur                 = conn.execute(f"SELECT * FROM {_quote_identifier(self.table)}")
+            rows                = cur.fetchall()
+            self.fieldnames     = [d[0] for d in cur.description]
+        finally:
+            conn.close()
+
+        table: Table          = []
+        seen: set[RowId]      = set()
+        order: list[RowId]    = []
+        source_name           = f"{self.path}#{self.table}"
+        for i, raw_row in enumerate(rows):
+            fields = {
+                k: Cell(v, Provenance(source_name, k)) for k, v in dict(raw_row).items()
+            }
+            rid: RowId = i
+            if self.key is not None:
+                if self.key not in fields:
+                    raise ValueError(
+                        f"{self.path}#{self.table}: key field {self.key!r} missing on row {i}"
+                    )
+                rid = fields[self.key].value
+                if rid in seen:
+                    raise ValueError(f"{self.path}#{self.table}: duplicate key {self.key}={rid!r}")
+            seen.add(rid)
+            order.append(rid)
+            table.append(Record(rid, fields))
+        self._order = order
+        self._remember_fingerprint()
+        return table
+
+    def write(self, table: Table) -> None:
+        by_rid          = {r.rid: r for r in table}
+        cols            = self.fieldnames or (list(table[0].fields.keys()) if table else [])
+        qtable          = _quote_identifier(self.table)
+        qcols           = ", ".join(_quote_identifier(c) for c in cols)
+        placeholders    = ", ".join("?" for _ in cols)
+
+        conn = sqlite3.connect(self.path)
+        try:
+            with conn:
+                conn.execute(f"DELETE FROM {qtable}")
+                for rid in self._order:
+                    record = by_rid.get(rid)
+                    if record is None:
+                        continue
+                    conn.execute(
+                        f"INSERT INTO {qtable} ({qcols}) VALUES ({placeholders})",
+                        [record.fields[c].value for c in cols],
+                    )
+        finally:
+            conn.close()
+        self._remember_fingerprint()