financechatbotkit 2.0.0__py3-none-any.whl

telebotkit/sheets.py

@@ -0,0 +1,219 @@
+"""General-purpose spreadsheet -> JSON helpers."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from openpyxl import load_workbook
+
+_ONE_MIB = 1_048_576
+
+
+def read_rows_from_xlsx(path: str | Path, *, sheet_name: str | None = None) -> list[list[str]]:
+    """Read rows from an XLSX worksheet using openpyxl."""
+
+    workbook = load_workbook(filename=Path(path), read_only=True, data_only=True)
+    try:
+        worksheet = workbook[sheet_name] if sheet_name else workbook[workbook.sheetnames[0]]
+        rows: list[list[str]] = []
+        for row in worksheet.iter_rows(values_only=True):
+            values = ["" if value is None else str(value) for value in row]
+            if any(value.strip() for value in values):
+                rows.append(values)
+        return rows
+    finally:
+        workbook.close()
+
+
+def build_typed_rows_payload(
+    rows: list[list[str]],
+    *,
+    source_file: str = "",
+    document_type: str = "typed_rows",
+    records_field: str = "records",
+    metadata_field: str = "metadata",
+    key_field_name: str = "key",
+) -> dict[str, Any]:
+    """Build a typed JSON payload from a simple row sheet."""
+
+    if not rows:
+        raise ValueError("Excel sheet is empty.")
+    header = rows[0]
+    if len(header) < 1:
+        raise ValueError("Excel sheet must contain at least a key column.")
+
+    dynamic_fields: list[tuple[int, str]] = []
+    seen_fields: set[str] = set()
+    for idx, raw_header in enumerate(header[1:], start=1):
+        field_name = str(raw_header or "").strip()
+        if not field_name:
+            continue
+        if field_name in seen_fields:
+            raise ValueError(f"Duplicate field header: {field_name}")
+        seen_fields.add(field_name)
+        dynamic_fields.append((idx, field_name))
+
+    records: dict[str, dict[str, Any]] = {}
+
+    for row_index, row in enumerate(rows[1:], start=2):
+        record_key = str(row[0] if len(row) >= 1 else "").strip()
+        if not record_key and not any(str(value).strip() for value in row[1:]):
+            continue
+        if not record_key:
+            raise ValueError(f"Row {row_index}: key value is required.")
+        if record_key in records:
+            raise ValueError(f"Row {row_index}: duplicate key `{record_key}`.")
+
+        entry: dict[str, Any] = {
+            key_field_name: record_key,
+        }
+        for field_index, field_name in dynamic_fields:
+            raw_value = str(row[field_index] if field_index < len(row) else "").strip()
+            if not raw_value:
+                continue
+            entry[field_name] = parse_strict_json_cell(
+                raw_value,
+                row_index=row_index,
+                field_name=field_name,
+            )
+
+        records[record_key] = entry
+
+    payload: dict[str, Any] = {
+        "document_type": document_type,
+        "schema_version": 1,
+        "generated_at": datetime.now(UTC).isoformat(),
+        "source_file": source_file,
+        metadata_field: {
+            "record_count": len(records),
+            "field_names": [field_name for _, field_name in dynamic_fields],
+        },
+        records_field: records,
+    }
+    payload[metadata_field]["size_bytes"] = typed_rows_size_bytes(payload)
+    return payload
+
+
+def build_typed_rows_payload_from_xlsx(
+    path: str | Path,
+    *,
+    document_type: str = "typed_rows",
+    records_field: str = "records",
+    metadata_field: str = "metadata",
+    key_field_name: str = "key",
+    sheet_name: str | None = None,
+) -> dict[str, Any]:
+    source = Path(path)
+    rows = read_rows_from_xlsx(source, sheet_name=sheet_name)
+    return build_typed_rows_payload(
+        rows,
+        source_file=str(source),
+        document_type=document_type,
+        records_field=records_field,
+        metadata_field=metadata_field,
+        key_field_name=key_field_name,
+    )
+
+
+def typed_rows_size_bytes(payload: dict[str, Any]) -> int:
+    return len(json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
+
+
+def validate_typed_rows_payload(
+    payload: dict[str, Any],
+    *,
+    document_type: str = "typed_rows",
+    records_field: str = "records",
+    metadata_field: str = "metadata",
+    key_field_name: str = "key",
+) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise ValueError("Typed rows JSON must be an object.")
+    if payload.get("document_type") != document_type:
+        raise ValueError("Typed rows JSON has unexpected document_type.")
+    if not isinstance(payload.get(records_field), dict):
+        raise ValueError(f"Typed rows JSON must contain a `{records_field}` object.")
+    if not isinstance(payload.get(metadata_field), dict):
+        raise ValueError(f"Typed rows JSON must contain a `{metadata_field}` object.")
+
+    for record_key, entry in payload[records_field].items():
+        if not isinstance(entry, dict):
+            raise ValueError(f"`{records_field}.{record_key}` must be an object.")
+        if str(entry.get(key_field_name) or "") != str(record_key):
+            raise ValueError(
+                f"`{records_field}.{record_key}.{key_field_name}` must match the record key."
+            )
+
+    size_bytes = typed_rows_size_bytes(payload)
+    if size_bytes >= _ONE_MIB:
+        raise ValueError(
+            f"Typed rows JSON is too large for a single Firestore document: {size_bytes} bytes"
+        )
+    payload.setdefault(metadata_field, {})["size_bytes"] = size_bytes
+    return payload
+
+
+def save_typed_rows_payload_json(
+    *,
+    payload: dict[str, Any],
+    output_path: str,
+    document_type: str = "typed_rows",
+    records_field: str = "records",
+    metadata_field: str = "metadata",
+    key_field_name: str = "key",
+) -> str:
+    validated = validate_typed_rows_payload(
+        payload,
+        document_type=document_type,
+        records_field=records_field,
+        metadata_field=metadata_field,
+        key_field_name=key_field_name,
+    )
+    target = Path(output_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(validated, ensure_ascii=False, indent=2), encoding="utf-8")
+    return str(target)
+
+
+def load_typed_rows_json(
+    json_path: str | Path,
+    *,
+    document_type: str = "typed_rows",
+    records_field: str = "records",
+    metadata_field: str = "metadata",
+    key_field_name: str = "key",
+) -> dict[str, Any]:
+    source = Path(json_path)
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    return validate_typed_rows_payload(
+        payload,
+        document_type=document_type,
+        records_field=records_field,
+        metadata_field=metadata_field,
+        key_field_name=key_field_name,
+    )
+
+
+def parse_strict_json_cell(raw_value: str, *, row_index: int, field_name: str) -> Any:
+    try:
+        return json.loads(raw_value)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Row {row_index} field `{field_name}` must be valid JSON. "
+            f"Use strict JSON such as 1, 0.75, true, null, \"text\", [..], or {{..}}."
+        ) from exc
+
+
+__all__ = [
+    "build_typed_rows_payload",
+    "build_typed_rows_payload_from_xlsx",
+    "load_typed_rows_json",
+    "parse_strict_json_cell",
+    "read_rows_from_xlsx",
+    "save_typed_rows_payload_json",
+    "typed_rows_size_bytes",
+    "validate_typed_rows_payload",
+]