gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/connectors/template.py

@@ -0,0 +1,106 @@
+"""Gather the files a workspace connector is made of from a directory on disk.
+
+Two directory shapes publish:
+
+* a **template** directory — the layout the platform stores and ``gateway worlds
+  schema init`` reads: ``world.json``, ``connector.toml``, ``handlers.py``, and
+  optionally ``provenance.json``, ``scope.toml``, ``api/handlers.py``,
+  ``scenarios/**``, ``evidence/**``, ``reports/**``; taken as-is;
+* a **world** directory — what ``init`` wrote and the author worked in:
+  ``schema/world.json``, ``tools/handlers.py``, ``connector.toml``, …; mapped back
+  into the template layout, leaving behind what is generated (``schema/base.json``,
+  ``lock.json`` …), stateful (``data/``, ``db/``, ``captures/`` — captures hold real
+  vendor records) or local (``gateway-env.toml``, ``verifiers/``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from gatewaysdk.environment.schema.scaffold import GENERATED_NAMES, SUPPORTING_SUFFIXES
+
+#: World-directory trees that are never part of the template.
+WORLD_SKIPPED_DIRS = ("data", "captures", "db", "verifiers")
+#: World-directory files that are never part of the template.
+WORLD_SKIPPED_FILES = ("gateway-env.toml", "tool-schemas.json")
+#: World-directory trees copied into the template unchanged.
+WORLD_CARRIED_DIRS = ("api", "scenarios", "evidence", "reports")
+
+
+@dataclass
+class TemplateFiles:
+    """What :func:`collect_template` found: ``source`` says which layout the
+    directory had, ``files`` is the template (path → text), ``skipped`` lists the
+    world-directory entries that stayed behind, for the author to see."""
+
+    source: str
+    files: Dict[str, str] = field(default_factory=dict)
+    skipped: List[str] = field(default_factory=list)
+
+
+def _wanted(path: Path) -> bool:
+    return path.is_file() and not path.is_symlink() and path.suffix != ".pyc" and not path.name.startswith(".")
+
+
+def _in_ignored_dir(relative: Path) -> bool:
+    return any(part == "__pycache__" or part.startswith(".") for part in relative.parts[:-1])
+
+
+def _read_text(path: Path, relative: str) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise ValueError(f"{relative} is not UTF-8 text; a connector template holds text files only") from None
+
+
+def _template_path(relative: Path) -> Optional[str]:
+    """The template path a world-directory file maps to, or ``None`` to leave it behind."""
+    parts = relative.parts
+    if parts[0] in WORLD_SKIPPED_DIRS or relative.as_posix() in WORLD_SKIPPED_FILES:
+        return None
+    if len(parts) == 1:
+        return relative.name if relative.name == "connector.toml" else None
+    if parts[0] == "schema":
+        if len(parts) != 2 or relative.suffix not in SUPPORTING_SUFFIXES or relative.name in GENERATED_NAMES:
+            return None
+        return relative.name
+    if relative.as_posix() == "tools/handlers.py":
+        return "handlers.py"
+    if parts[0] in WORLD_CARRIED_DIRS:
+        return relative.as_posix()
+    return None
+
+
+def collect_template(directory: str | Path) -> TemplateFiles:
+    """The template held in ``directory``, whichever of the two layouts it uses.
+
+    Raises ``FileNotFoundError`` when the directory has neither ``world.json`` nor
+    ``schema/world.json``, and ``ValueError`` for a file that is not UTF-8 text.
+    """
+    root = Path(directory)
+    if (root / "world.json").is_file():
+        report = TemplateFiles(source="template")
+        for path in sorted(root.rglob("*")):
+            relative = path.relative_to(root)
+            if not _wanted(path) or _in_ignored_dir(relative):
+                continue
+            report.files[relative.as_posix()] = _read_text(path, relative.as_posix())
+        return report
+    if not (root / "schema/world.json").is_file():
+        raise FileNotFoundError(f"{root}: neither a connector template (world.json) nor a world (schema/world.json)")
+    report = TemplateFiles(source="world")
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root)
+        if not _wanted(path) or _in_ignored_dir(relative):
+            continue
+        target = _template_path(relative)
+        if target is None:
+            report.skipped.append(relative.as_posix())
+            continue
+        report.files[target] = _read_text(path, relative.as_posix())
+    return report
+
+
+__all__ = ["TemplateFiles", "collect_template"]