pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/discovery.py

@@ -0,0 +1,227 @@
+"""Bounded installation discovery, shared by human and automated SDK clients.
+
+Searching enumerates known environment roots, never an entire drive. Candidates
+are validated through PyCForge's public discovery protocol in separate processes.
+Discovery neither changes the reference cache nor installs or registers anything.
+"""
+from __future__ import annotations
+from itertools import islice
+import os
+from pathlib import Path
+import re
+import sys
+import time
+from . import catalogue
+from .connection import Connection
+from .results import Outcome, SDKError, operation
+
+DISCOVERY_SCHEMA = "pycforge-sdk.discovery/0.1"
+_PYTHON = re.compile(r"python(?:3(?:\.\d+)*)?(?:\.exe)?$", re.IGNORECASE)
+
+
+def _key(path):
+    # Resolving a venv's python symlink would lose the environment identity.
+    return os.path.normcase(os.path.abspath(os.path.expanduser(str(path))))
+
+
+def _children(path):
+    try:
+        return sorted(islice(Path(path).iterdir(), 256), key=lambda p: p.name.lower())
+    except OSError:
+        return []
+
+
+def support_folder(location):
+    """Recognize the engine-owned support folder without importing engine code."""
+    path = Path(location).expanduser().absolute()
+    for item in (path, path / "crucible/landscape", path / "pycforge/crucible/landscape"):
+        if item.is_dir() and (item / "index.json").is_file() and (item / "api.xml").is_file():
+            return item
+    return None
+
+
+def interpreters_at(location):
+    """Resolve a Python, environment, or installed support folder without execution."""
+    path = Path(location).expanduser().absolute()
+    if path.is_file():
+        if path.name.lower() == "pythonw.exe":
+            path = path.with_name("python.exe")
+        return [path] if path.is_file() and _PYTHON.fullmatch(path.name) else []
+    if not path.is_dir():
+        return []
+    roots = [path]
+    support = support_folder(path)
+    if support:
+        roots.extend(list(support.parents)[:8])
+    found = []
+    for root in roots:
+        for relative in ("Scripts/python.exe", "bin/python", "bin/python3", "python.exe", "python", "python3"):
+            item = root / relative
+            if item.is_file() and _key(item) not in {_key(p) for p in found}:
+                found.append(item)
+    return found
+
+
+def _windows_registry_locations():
+    """PEP 514 Python registrations, including both registry views."""
+    if sys.platform != "win32":
+        return []
+    import winreg
+    values = []
+    for hive in (winreg.HKEY_CURRENT_USER, winreg.HKEY_LOCAL_MACHINE):
+        for view in (winreg.KEY_WOW64_64KEY, winreg.KEY_WOW64_32KEY):
+            try:
+                with winreg.OpenKey(hive, r"Software\Python", 0, winreg.KEY_READ | view) as root:
+                    for ci in range(min(winreg.QueryInfoKey(root)[0], 64)):
+                        company = winreg.EnumKey(root, ci)
+                        with winreg.OpenKey(root, company) as vendor:
+                            for ti in range(min(winreg.QueryInfoKey(vendor)[0], 64)):
+                                tag = winreg.EnumKey(vendor, ti)
+                                try:
+                                    with winreg.OpenKey(vendor, tag + r"\InstallPath") as install:
+                                        for field in ("ExecutablePath", ""):
+                                            try:
+                                                value, kind = winreg.QueryValueEx(install, field)
+                                                if kind in (winreg.REG_SZ, winreg.REG_EXPAND_SZ):
+                                                    values.append(os.path.expandvars(value))
+                                            except OSError:
+                                                pass
+                                except OSError:
+                                    pass
+            except OSError:
+                pass
+    return values
+
+
+def common_locations():
+    """Known Python/environment locations; no shell, registry writes or recursion."""
+    home = Path.home()
+    locations = [sys.executable]
+    for name in ("VIRTUAL_ENV", "CONDA_PREFIX"):
+        if os.environ.get(name):
+            locations.append(os.environ[name])
+    locations.extend(_windows_registry_locations())
+    # Ignore empty/relative PATH entries and Windows Store execution aliases.
+    for value in os.environ.get("PATH", "").split(os.pathsep)[:64]:
+        if value and Path(value).is_absolute() and "windowsapps" not in value.lower():
+            locations.append(value)
+    locations.append(getattr(sys, "_base_executable", sys.executable))
+    bases = [home / ".virtualenvs", home / ".venvs", home / "venvs",
+             home / ".pyenv/versions", home / ".local/share/pipx/venvs", home / ".local/pipx/venvs",
+             home / "miniconda3/envs", home / "anaconda3/envs", home / ".conda/envs"]
+    locations.extend([home / "miniconda3", home / "anaconda3"])
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            bases.append(Path(local) / "Programs/Python")
+        for name in ("ProgramFiles", "ProgramFiles(x86)"):
+            if os.environ.get(name):
+                locations.extend(p for p in _children(os.environ[name]) if p.name.lower().startswith("python"))
+    elif sys.platform == "darwin":
+        bases.extend([Path("/Library/Frameworks/Python.framework/Versions"),
+                      home / "Library/Python", Path("/opt/homebrew/opt")])
+    for base in bases:
+        locations.extend(_children(base))
+    # Conda records environments outside its default envs directory here.
+    try:
+        with (home / ".conda/environments.txt").open(encoding="utf-8") as file:
+            text = file.read(65537)
+        if len(text) <= 65536:
+            locations.extend(line.strip() for line in text.splitlines()[:128]
+                             if line.strip() and Path(line.strip()).is_absolute())
+    except (OSError, UnicodeError):
+        pass
+    return locations
+
+
+def _probe(python, timeout, cancel):
+    connection = Connection(python, ".", timeout=timeout, cancel=cancel)
+    discovery = connection.discover()
+    connection.snapshot = catalogue.read_snapshot(discovery)
+    if "authoring.json" in connection.snapshot.files:
+        connection.reference()
+    connection.workbench()
+    return {"engine_python": str(python), "engine": dict(connection.snapshot.identity),
+            "folder": str(discovery["folder"]), "execution_available": connection._authoring_ready}
+
+
+@operation
+def discover_engines(*, preferred=None, locations=None, timeout=3.0, search_timeout=20.0,
+                     max_candidates=48, cancel=None, progress=None):
+    """Find validated installations without changing a cache or authoring state.
+
+    A valid preferred installation wins immediately. Explicit locations restrict
+    the search; otherwise known installations and environment roots are checked.
+    Results identify partial searches and failures. Cancellation returns no choice.
+    Time/output budgets supervise child processes, not filesystem/network mounts.
+    """
+    if (not 0 < timeout <= 300 or not 0 < search_timeout <= 300
+            or type(max_candidates) is not int or not 1 <= max_candidates <= 128):
+        raise SDKError("SDK_ARGUMENT", "Use positive timeouts up to 300 seconds and 1–128 candidates.")
+    if locations is not None and (not isinstance(locations, (list, tuple)) or len(locations) > 128):
+        raise SDKError("SDK_ARGUMENT", "Locations must be a list of at most 128 paths.")
+    started = time.monotonic()
+    def notify(**data):
+        if cancel is not None and cancel.is_set():
+            raise SDKError("SDK_CANCELED", "Installation search canceled.", status="canceled")
+        if progress:
+            progress({"schema": "pycforge-sdk.progress/0.1", "phase": "discovery", **data})
+    notify(name="Looking for installed PyCForge support files…", current=0, total=1)
+    sources = ([preferred] if preferred else []) + (list(locations) if locations is not None else common_locations())
+    candidates, seen = [], set()
+    support_requested = [support_folder(item) for item in (locations or [])]
+    support_requested = [item for item in support_requested if item is not None]
+    # An installed user-site catalogue may have its interpreter outside its parents.
+    if support_requested:
+        sources.extend(common_locations())
+    limited = False
+    for location in sources:
+        notify(name="Checking known installation locations…", current=0, total=1)
+        for python in interpreters_at(location):
+            key = _key(python)
+            if key in seen:
+                continue
+            seen.add(key)
+            if len(candidates) >= max_candidates:
+                limited = True
+                break
+            candidates.append(python)
+        if limited:
+            break
+    engines, attempts, identities = [], [], set()
+    preferred_keys = {_key(p) for p in interpreters_at(preferred)} if preferred else set()
+    reason = "searched"
+    for index, python in enumerate(candidates):
+        notify(name="Checking PyCForge installation…", path=str(python), current=index, total=len(candidates))
+        remaining = search_timeout - (time.monotonic() - started)
+        if remaining <= 0:
+            limited = True
+            break
+        try:
+            item = _probe(python, min(timeout, remaining), cancel)
+            if support_requested and not any(_key(item["folder"]) == _key(p) for p in support_requested):
+                attempts.append({"engine_python": str(python), "code": "SDK_LOCATION_MISMATCH",
+                                 "message": "This interpreter uses a different PyCForge support folder."})
+                continue
+            identity = (_key(item["folder"]), item["engine"]["manifest_sha256"])
+            if identity not in identities:
+                engines.append(item)
+                identities.add(identity)
+            if _key(python) in preferred_keys:
+                reason = "preferred"
+                limited = False
+                break
+        except (SDKError, catalogue.CatalogueError, OSError, ValueError, TypeError, KeyError) as exc:
+            if isinstance(exc, SDKError) and exc.status == "canceled":
+                raise
+            attempts.append({"engine_python": str(python), "code": getattr(exc, "code", "SDK_DISCOVERY"),
+                             "message": str(exc)[:500]})
+    notify(name="Installation search finished", current=1, total=1)
+    data = {"schema": DISCOVERY_SCHEMA, "engines": engines, "attempts": attempts,
+            "limited": limited, "reason": reason, "candidate_count": len(candidates)}
+    if not engines:
+        message = ("The selected support folder needs its matching installed PyCForge environment. "
+                   "A source folder alone does not provide a working engine." if support_requested else
+                   "No compatible PyCForge installation was found in the checked locations.")
+        return Outcome("incomplete", data, ({"code": "SDK_ENGINE_NOT_FOUND", "message": message},))
+    return Outcome("succeeded", data)

pycforge_sdk/editing.py

@@ -0,0 +1,84 @@
+"""Bounded editor snapshots and optimistic, one-file atomic saves; no Qt."""
+from pathlib import Path
+import tempfile
+from .project import Project, MAX_PROJECT, MAX_SOURCE, atomic_write, canonical
+from .results import SDKError
+
+
+def snapshot(project):
+    document = project.document
+    declaration = document.get("declaration")
+    if (type(declaration) is not dict or type(declaration.get("functions")) is not list
+            or any(type(f) is not dict or type(f.get("export")) is not str for f in declaration["functions"])
+            or any(key in declaration and type(declaration[key]) is not str for key in ("namespace", "package_id", "version", "schema"))):
+        raise SDKError("SDK_EDITOR_DATA", "The declaration needs an object with a list of named functions. Correct project.json and reopen it.")
+    documentation = document.get("documentation")
+    if isinstance(documentation, dict) and (type(documentation.get("functions", {})) is not dict or type(documentation.get("constants", {})) is not dict):
+        raise SDKError("SDK_EDITOR_DATA", "Help functions and constants must be objects. Correct project.json and reopen it.")
+    if isinstance(documentation, dict):
+        for function in documentation.get("functions", {}).values():
+            if (type(function) is not dict or type(function.get("parameters", [])) is not list
+                    or any(type(p) is not str for p in function.get("parameters", []))):
+                raise SDKError("SDK_EDITOR_DATA", "Function Help needs an object with a list of parameter explanations. Correct project.json and reopen it.")
+    return {"directory": str(project.root), "project_sha256": project.sha256,
+            "document": document,
+            "sources": {name: value.decode("utf-8") for name, value in project.sources}}
+
+
+def open_project(directory):
+    project = Project.load(directory)
+    project.ensure_current()
+    return snapshot(project)
+
+
+def current(directory, expected_sha256):
+    project = Project.load(directory)
+    if project.sha256 != expected_sha256:
+        raise SDKError("SDK_EDIT_CONFLICT", "Project changed on disk. Reload it before saving; your saved files were preserved.")
+    return project
+
+
+def validate_draft(project, document, sources):
+    # Project.load owns data/path/budget validation for every client. A private
+    # staged snapshot never imports source and never creates verification.
+    data = canonical(document)
+    if len(data) + sum(len(v) for v in sources.values()) > MAX_PROJECT:
+        raise SDKError("SDK_PROJECT", "Project exceeds the 4 MiB budget; no files were changed.")
+    # Newly referenced existing files go through the same path/symlink/budget
+    # checks before any path is copied into the private validation directory.
+    candidate = Project.load(project.root, document_bytes=data)
+    snapshot(candidate)
+    sources = {**dict(candidate.sources), **sources}
+    with tempfile.TemporaryDirectory(prefix="sdk-edit-") as folder:
+        root = Path(folder)
+        (root / "project.json").write_bytes(data)
+        # Keys originate in an already validated Project, never draft paths.
+        for name, value in sources.items():
+            target = root / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(value)
+        snapshot(Project.load(root))
+    return data
+
+
+def save_project(directory, document, *, expected_sha256):
+    project = current(directory, expected_sha256)
+    data = validate_draft(project, document, dict(project.sources))
+    project.ensure_current()
+    atomic_write(project.root / "project.json", data)
+    return open_project(directory)
+
+
+def save_source(directory, filename, source, *, expected_sha256):
+    project = current(directory, expected_sha256)
+    sources = dict(project.sources)
+    if filename not in sources or type(source) is not str:
+        raise SDKError("SDK_ARGUMENT", "Choose an existing UTF-8 project fixture.")
+    data = source.encode("utf-8")
+    if len(data) > MAX_SOURCE:
+        raise SDKError("SDK_PROJECT", "Fixture exceeds the 256 KiB budget; no files were changed.")
+    sources[filename] = data
+    validate_draft(project, project.document, sources)
+    project.ensure_current()
+    atomic_write(project.root / filename, data)
+    return open_project(directory)

pycforge_sdk/engine_launch.py

@@ -0,0 +1,45 @@
+"""Isolated engine entry point, including standard per-user installations.
+
+Executed by the selected Python, not imported into the SDK process. Preserve
+-I's exclusion of the working directory and PYTHONPATH. Add that interpreter's
+standard user-site folder when its environment permits it; never process its
+.pth files or accept an arbitrary source folder as an import path.
+"""
+from pathlib import Path
+import runpy
+import site
+import sys
+
+
+def user_site_allowed():
+    if sys.prefix == sys.base_prefix:
+        return True
+    try:
+        lines = (Path(sys.prefix) / "pyvenv.cfg").read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return False
+    return any(line.partition("=")[0].strip().lower() == "include-system-site-packages"
+               and line.partition("=")[2].strip().lower() == "true" for line in lines)
+
+
+def main():
+    if user_site_allowed():
+        folder = site.getusersitepackages()
+        if isinstance(folder, str) and Path(folder).is_dir() and folder not in sys.path:
+            # Match normal user-site precedence ahead of global site-packages,
+            # retaining the standard library first.
+            globals_ = site.getsitepackages()
+            position = next((i for i, p in enumerate(sys.path) if p in globals_), len(sys.path))
+            sys.path.insert(position, folder)
+    mode = sys.argv[1]
+    if mode == "discover":
+        sys.argv = ["pycforge", "--format", "json", "sdk-api"]
+        runpy.run_module("pycforge", run_name="__main__", alter_sys=True)
+    elif mode == "call":
+        runpy.run_path(str(Path(__file__).with_name("engine_worker.py")), run_name="__main__")
+    else:
+        raise ValueError("Unknown engine launch mode")
+
+
+if __name__ == "__main__":
+    main()

pycforge_sdk/engine_worker.py

@@ -0,0 +1,53 @@
+"""SDK bridge executed by the selected engine interpreter using -I.
+
+Only public PyCForge services are imported. The SDK need not be installed in
+that interpreter. Incoming authoring data is JSON, never executable Python.
+"""
+import base64
+import json
+from pathlib import Path
+import sys
+
+
+def main():
+    request = json.loads(sys.stdin.buffer.read(8*1024*1024 + 1))
+    from pycforge.crucible.sdk_api import discover
+    identity = discover()
+    if request["identity"] != identity:
+        raise ValueError("Engine identity changed; reconnect and reverify.")
+    action, payload = request["action"], request["payload"]
+    from pycforge.crucible import ScalarAuthoring, ImportRegistrationStore
+    import pycforge.crucible as api
+    Authoring = getattr(api, "ExtensionAuthoring", ScalarAuthoring)
+    if action == "register":
+        store = ImportRegistrationStore(Path(payload["store"]) if payload.get("store") else None)
+        row = store.register_file(Path(payload["file"]))
+        from dataclasses import fields
+        result = {field.name: getattr(row, field.name) for field in fields(row) if field.name != "package"}
+        result["package_sha256"] = row.package.package_sha256 if row.package is not None else None
+    else:
+        candidate = Authoring(payload["declaration"])
+        if action == "inspect":
+            result = candidate.inspect()
+        elif action == "scan":
+            result = candidate.scan(payload.get("documentation"), examples=payload.get("examples"))
+        elif action == "convert":
+            result = candidate.convert(payload["source"], logical_name=payload["logical_name"]).semantic_dict()
+        elif action == "package":
+            result = {"package_base64": base64.b64encode(candidate.package(
+                **payload["metadata"], verification_producer=payload["verification_producer"],
+                documentation=payload["documentation"], examples=payload["examples"])).decode("ascii")}
+        else:
+            raise ValueError("Unknown bridge action")
+    if discover() != identity:
+        raise ValueError("Engine identity changed during the operation.")
+    return {"schema": "pycforge-sdk.bridge/0.1", "identity": identity, "ok": True, "result": result}
+
+
+if __name__ == "__main__":
+    try:
+        answer = main()
+    except Exception as exc:
+        answer = {"schema": "pycforge-sdk.bridge/0.1", "ok": False,
+                  "diagnostic": {"code": getattr(exc, "code", "SDK_ENGINE_ERROR"), "message": str(exc)}}
+    print(json.dumps(answer, sort_keys=True, allow_nan=False))

pycforge_sdk/gui/__init__.py

@@ -0,0 +1 @@
+"""Optional desktop client. Importing the SDK never imports this application."""

pycforge_sdk/gui/__main__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+raise SystemExit(main())

pycforge_sdk/gui/app.py

@@ -0,0 +1,36 @@
+"""Optional PySide6 entry point; dependency errors stay separate from the SDK."""
+import argparse
+from pathlib import Path
+import sys
+from .. import __version__
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="pycforge-sdk-ui", description="PyCForge conversion extension workshop")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--engine-python")
+    parser.add_argument("--compiler")
+    parser.add_argument("--cache", type=Path)
+    parser.add_argument("--project", type=Path)
+    parser.add_argument("--timeout", type=float, default=30)
+    args = parser.parse_args(argv)
+    if not 0 < args.timeout <= 300: parser.error("timeout must be greater than zero and at most 300 seconds")
+    try:
+        from PySide6.QtCore import QTimer
+        from PySide6.QtWidgets import QApplication
+    except ImportError:
+        print("The desktop needs the optional GUI dependency. Install pycforge-sdk[gui] in this environment; the headless SDK remains usable.", file=sys.stderr)
+        return 3
+    from .visual.theme import apply_pycforge_theme
+    from .identity import sdk_icon
+    from .window import MainWindow
+    from .visual.qt_screen_geometry import fit_window_to_available_screen
+    app = QApplication.instance() or QApplication([sys.argv[0]])
+    app.setApplicationName("PyCForge SDK"); app.setApplicationVersion(__version__)
+    app.setWindowIcon(sdk_icon())
+    apply_pycforge_theme(app)
+    window = MainWindow(engine_python=args.engine_python, compiler=args.compiler, cache=args.cache, timeout=args.timeout)
+    fit_window_to_available_screen(window, preferred=(1320, 860), minimum=(920, 640))
+    if args.project: window.after_connect = str(args.project.absolute())
+    QTimer.singleShot(0, window.begin_startup)
+    return app.exec()