pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/jobs.py

@@ -0,0 +1,146 @@
+"""One supervised SDK operation at a time; widgets stay on Qt's main thread."""
+import copy
+import gc
+import threading
+from PySide6.QtCore import QObject, QThread, QTimer, Signal, Slot, Qt
+from .. import SDK, Outcome, discover_engines
+
+
+_gc_users = 0
+_gc_restore = False
+
+
+def _begin_gui_work():
+    """Keep cyclic destruction of GUI wrappers on their owning GUI thread.
+
+    Fast worker allocations can otherwise trigger Python's cyclic collector on
+    that worker, releasing a previously closed window's Qt wrappers there. Ref-
+    counting remains active. Multiple SDK runners share this short-lived guard.
+    """
+    global _gc_users, _gc_restore
+    if _gc_users == 0:
+        _gc_restore = gc.isenabled()
+        gc.disable()
+        gc.collect()
+    _gc_users += 1
+
+
+def _end_gui_work():
+    global _gc_users
+    _gc_users -= 1
+    if _gc_users == 0:
+        gc.collect()
+        if _gc_restore:
+            gc.enable()
+
+
+class Worker(QObject):
+    completed = Signal(object)
+    progress = Signal(object)
+    done = Signal()
+
+    def __init__(self, configuration, method, args, kwargs, cancel):
+        super().__init__()
+        self.configuration, self.method = configuration, method
+        self.args, self.kwargs, self.cancel = args, kwargs, cancel
+
+    @Slot()
+    def run(self):
+        try:
+            if self.method == "discover":
+                result = discover_engines(**self.kwargs, cancel=self.cancel, progress=self.progress.emit)
+                self.completed.emit(copy.deepcopy(result.to_dict()))
+                return
+            sdk = SDK(**self.configuration, cancel=self.cancel, progress=self.progress.emit)
+            if self.method == "catalogue":
+                connection = sdk.connect(**self.kwargs)
+                # With no cached snapshot, methods() would try another live
+                # connection. Offline recovery must not execute an interpreter.
+                if connection.data.get("engine") is None:
+                    templates = methods = Outcome("incomplete")
+                    workbench = Outcome("incomplete")
+                else:
+                    templates, methods = sdk.templates(), sdk.methods()
+                    workbench = sdk.workbench()
+                result = Outcome(connection.status, {"connection": connection.data,
+                    "templates": templates.data.get("templates", []),
+                    "methods": methods.data.get("methods", []),
+                    "array_operations": methods.data.get("array_operations", []),
+                    "workbench": workbench.data.get("workbench"), "documents": workbench.data.get("documents", []),
+                    "limits": methods.data.get("limits", [])},
+                    connection.diagnostics + templates.diagnostics + methods.diagnostics + workbench.diagnostics)
+            else:
+                result = getattr(sdk, self.method)(*self.args, **self.kwargs)
+            self.completed.emit(copy.deepcopy(result.to_dict()))
+        except Exception as exc:
+            self.completed.emit(Outcome("internal_failure", diagnostics=(
+                {"code": "SDK_UI_WORKER", "message": str(exc)},)).to_dict())
+        finally:
+            self.done.emit()
+
+
+class JobRunner(QObject):
+    finished = Signal(str, object, int)
+    progress = Signal(object)
+    busy_changed = Signal(bool)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.thread = self.worker = None
+        self.cancel_event = None
+        self.result = None
+
+    @property
+    def busy(self):
+        return self.thread is not None
+
+    def start(self, configuration, method, args=(), kwargs=None, *, revision=0):
+        if self.busy:
+            return False
+        self.method, self.revision = method, revision
+        self.result = None
+        self.cancel_event = threading.Event()
+        self.thread = QThread(self)
+        self.thread.setObjectName("SDK operation: " + method)
+        self.worker = Worker(copy.deepcopy(configuration), method, copy.deepcopy(args),
+                             copy.deepcopy(kwargs or {}), self.cancel_event)
+        self.worker.moveToThread(self.thread)
+        # Enter run only after the worker event loop starts. An empty discovery
+        # can finish immediately; quitting from started's direct callback races
+        # the event-loop startup and deferred QObject cleanup on some Qt builds.
+        self.thread.started.connect(self.worker.run, Qt.ConnectionType.QueuedConnection)
+        self.worker.progress.connect(self.progress)
+        self.worker.completed.connect(self._capture)
+        # quit() is thread-safe. It must not depend on a blocked GUI close loop.
+        self.worker.done.connect(self.thread.quit, Qt.ConnectionType.DirectConnection)
+        self.thread.finished.connect(self.worker.deleteLater)
+        self.thread.finished.connect(self._stopped)
+        _begin_gui_work()
+        self.busy_changed.emit(True)
+        self.thread.start()
+        return True
+
+    @Slot(object)
+    def _capture(self, result):
+        self.result = result
+
+    @Slot()
+    def _stopped(self):
+        thread = self.thread
+        # finished is emitted before native thread-local/deferred deletion has
+        # fully completed. Keep Python wrappers alive until a nonblocking join
+        # confirms that cleanup is over, including on fast successive jobs.
+        if not thread.wait(0):
+            QTimer.singleShot(1, self._stopped)
+            return
+        self.thread = self.worker = None
+        thread.deleteLater()
+        _end_gui_work()
+        result = self.result or Outcome("internal_failure", diagnostics=(
+            {"code": "SDK_UI_WORKER", "message": "Worker ended without a result."},)).to_dict()
+        self.busy_changed.emit(False)
+        self.finished.emit(self.method, result, self.revision)
+
+    def cancel(self):
+        if self.cancel_event is not None:
+            self.cancel_event.set()

pycforge_sdk/gui/reference.py

@@ -0,0 +1,39 @@
+"""Searchable, inert engine-owned method help with explicit offline labeling."""
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QWidget, QVBoxLayout, QLineEdit, QSplitter, QListWidget, QListWidgetItem
+from .widgets import label, SafeBrowser, method_html
+
+
+class ReferencePanel(QWidget):
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        layout = QVBoxLayout(self)
+        self.state = label("Connect to load the selected engine's reference.")
+        layout.addWidget(self.state)
+        self.search = QLineEdit(); self.search.setPlaceholderText("Find a method, field or operation…")
+        self.search.setAccessibleName("Search engine reference"); layout.addWidget(self.search)
+        split = QSplitter(); self.entries = QListWidget(); self.details = SafeBrowser()
+        self.entries.setAccessibleName("Authoring methods")
+        self.details.setAccessibleName("Method explanation")
+        split.addWidget(self.entries); split.addWidget(self.details); split.setSizes([270, 650])
+        layout.addWidget(split, 1)
+        self.search.textChanged.connect(self.filter)
+        self.entries.currentItemChanged.connect(self.show_entry)
+
+    def load(self, entries, state, limits):
+        self.state.setText(("Connected engine reference" if state == "connected" else "OFFLINE REFERENCE — cached information cannot approve verification or packaging") +
+                           "\nBrowsing never executes examples.")
+        self.entries.clear()
+        for entry in entries:
+            item = QListWidgetItem(entry["title"]); item.setData(Qt.ItemDataRole.UserRole, entry)
+            self.entries.addItem(item)
+        self.filter(self.search.text())
+        if self.entries.count(): self.entries.setCurrentRow(0)
+
+    def filter(self, text):
+        for i in range(self.entries.count()):
+            item = self.entries.item(i)
+            item.setHidden(text.casefold() not in str(item.data(Qt.ItemDataRole.UserRole)).casefold())
+
+    def show_entry(self, current, _previous=None):
+        if current: self.details.setHtml(method_html(current.data(Qt.ItemDataRole.UserRole)))

pycforge_sdk/gui/scanner.py

@@ -0,0 +1,134 @@
+"""Scanner verdict, actionable findings and fixture evidence, without policy."""
+import json
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (QWidget, QVBoxLayout, QTreeWidget, QTreeWidgetItem,
+    QSplitter, QTabWidget, QFrame, QHBoxLayout, QProgressBar)
+from .widgets import label, SafeBrowser
+
+STATE_TEXT = {
+    "ready-to-package": ("Ready to package", "All required checks pass for this saved project and its recorded verification environment."),
+    "ready-to-verify": ("Ready to verify", "Authoring checks pass. Run Verify fixtures to establish native results before packaging."),
+    "needs-verification": ("Verification needed", "The current project does not have matching passing evidence. Review the finding, then run Verify fixtures."),
+    "needs-authoring": ("Needs attention", "Fix the listed fields, save, then scan again."),
+    "unavailable": ("Engine unavailable", "Connect to a compatible PyCForge installation to evaluate readiness."),
+    "canceled": ("Scan canceled", "Readiness was not established. Run Scan when you are ready."),
+}
+
+
+class ScannerPanel(QWidget):
+    field_requested = Signal(str)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        layout = QVBoxLayout(self)
+        self.verdict = label("Start with a project")
+        self.verdict.setAccessibleName("Packaging readiness")
+        font = self.verdict.font(); font.setPointSize(19); font.setBold(True); self.verdict.setFont(font)
+        layout.addWidget(self.verdict)
+        self.explanation = label("Connect to PyCForge, then create or open a conversion extension. Scan shows exactly what is ready and what still needs work.")
+        layout.addWidget(self.explanation)
+        self.scope = label("Scan never runs fixture programs. Verify fixtures explicitly compiles and executes them.", muted=True)
+        layout.addWidget(self.scope)
+        self.progress = QProgressBar(); self.progress.setRange(0, 1); self.progress.setValue(0)
+        self.progress.setAccessibleName("SDK operation progress")
+        layout.addWidget(self.progress)
+        self.phase = label("No project scanned", muted=True); layout.addWidget(self.phase)
+        self.tabs = QTabWidget(); layout.addWidget(self.tabs, 1)
+        self.checks = QTreeWidget(); self.checks.setHeaderLabels(["Check", "Result"])
+        self.checks.setColumnWidth(0, 480); self.checks.setRootIsDecorated(False)
+        self.checks.setAccessibleName("Scanner checklist"); self.tabs.addTab(self.checks, "Checklist")
+        findings = QWidget(); findings_layout = QVBoxLayout(findings)
+        self.issues = QTreeWidget(); self.issues.setHeaderLabels(["Finding", "Field"])
+        self.issues.setColumnWidth(0, 460); self.issues.setRootIsDecorated(False)
+        self.issues.setAccessibleName("Scanner findings")
+        self.issues.currentItemChanged.connect(self.describe_issue)
+        self.issues.itemActivated.connect(self.open_issue)
+        findings_layout.addWidget(self.issues, 1)
+        self.details = SafeBrowser(); self.details.setMaximumHeight(180)
+        self.details.setAccessibleName("Finding explanation and remedy")
+        findings_layout.addWidget(self.details)
+        findings_layout.addWidget(label("Double-click a finding or press Enter to open its field.", muted=True))
+        self.tabs.addTab(findings, "Findings")
+        self.fixtures = QTreeWidget(); self.fixtures.setHeaderLabels(["Fixture", "Expected", "Result"])
+        self.fixtures.setColumnWidth(0, 310); self.fixtures.setRootIsDecorated(False)
+        self.fixtures.setAccessibleName("Native fixture results")
+        self.fixtures.itemActivated.connect(self.open_fixture)
+        self.tabs.addTab(self.fixtures, "Fixture results")
+        self.evidence = SafeBrowser(); self.evidence.setAccessibleName("Evidence identity and limitations")
+        self.tabs.addTab(self.evidence, "Evidence")
+
+    def invalidate(self, message="Project changed. Save and scan again."):
+        self.verdict.setText("Readiness needs a new scan")
+        self.explanation.setText(message)
+        self.checks.clear(); self.issues.clear(); self.fixtures.clear(); self.evidence.clear(); self.details.clear()
+        self.tabs.setTabText(1, "Findings")
+        self.phase.setText("Previous approval cleared")
+        self.progress.setRange(0, 1); self.progress.setValue(0)
+
+    def running(self, message):
+        self.checks.clear(); self.issues.clear(); self.fixtures.clear(); self.evidence.clear(); self.details.clear()
+        self.tabs.setTabText(1, "Findings")
+        self.verdict.setText(message)
+        self.explanation.setText("You can cancel this operation. Packaging stays disabled until current evidence passes.")
+        self.progress.setRange(0, 0)
+
+    def update_progress(self, event):
+        if event.get("phase") == "case":
+            total = event.get("total", 1)
+            self.progress.setRange(0, total)
+            self.progress.setValue(event.get("index", 0))
+            self.phase.setText(f"Fixture {event.get('index', 0)+1} of {total}: {event.get('name', '')}")
+        else:
+            self.phase.setText(event.get("name", event.get("phase", "Working")))
+
+    def show_readiness(self, data):
+        title, explanation = STATE_TEXT.get(data["state"], ("Readiness unavailable", "Run Scan again."))
+        self.verdict.setText(title); self.explanation.setText(explanation)
+        self.scope.setText(data["scope"])
+        self.progress.setRange(0, 1); self.progress.setValue(1)
+        self.phase.setText("Scan complete")
+        self.checks.clear(); self.issues.clear()
+        for check in data["checks"]:
+            QTreeWidgetItem(self.checks, [check["label"], check["status"].replace("-", " ").title()])
+        for issue in data["issues"]:
+            item = QTreeWidgetItem(self.issues, [issue["message"], issue.get("path", "")])
+            item.setData(0, Qt.ItemDataRole.UserRole, issue)
+        self.tabs.setTabText(1, f"Findings ({len(data['issues'])})")
+        if data["issues"]:
+            self.issues.setCurrentItem(self.issues.topLevelItem(0)); self.tabs.setCurrentIndex(1)
+        else: self.tabs.setCurrentIndex(0)
+        if "cases" in data: self.show_cases(data["cases"])
+        identity = {key: data.get(key) for key in ("project_sha256", "evidence_sha256", "engine", "compiler", "coverage", "last_attempt_status", "scope")}
+        self.evidence.setPlainText(display_json(identity))
+
+    def show_cases(self, cases):
+        self.fixtures.clear()
+        for case in cases:
+            row = QTreeWidgetItem(self.fixtures, [case["name"], case["expected"]["kind"], "Passed" if case.get("passed") is True else "Failed"])
+            row.setData(0, Qt.ItemDataRole.UserRole, case)
+
+    def show_report(self, report):
+        self.show_cases(report.get("cases", []))
+        self.evidence.setPlainText(display_json(report))
+        self.progress.setRange(0, 1); self.progress.setValue(1)
+        self.tabs.setCurrentIndex(2)
+
+    def describe_issue(self, current, _previous=None):
+        if current:
+            issue = current.data(0, Qt.ItemDataRole.UserRole)
+            self.details.setPlainText(issue.get("code", "") + "\n" + issue["message"] + "\n\n" + issue.get("remedy", ""))
+
+    def open_issue(self, item, _column=0):
+        issue = item.data(0, Qt.ItemDataRole.UserRole)
+        if issue.get("path"): self.field_requested.emit(issue["path"])
+
+    def open_fixture(self, item, _column=0):
+        self.evidence.setPlainText(display_json(item.data(0, Qt.ItemDataRole.UserRole)))
+        self.tabs.setCurrentIndex(3)
+
+
+def display_json(value):
+    text = json.dumps(value, indent=2)
+    if len(text) > 65536:
+        return text[:65536] + "\n\nDisplay shortened. Complete native evidence is in the project's .pycforge-sdk/verification.json."
+    return text

pycforge_sdk/gui/startup.py

@@ -0,0 +1,118 @@
+"""A single-progress startup and recovery surface with the SDK identity."""
+from PySide6.QtCore import Qt, Signal, QSize
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QListWidget, QListWidgetItem, QProgressBar
+from .dialogs import Dialog
+from .identity import sdk_icon, PathLabel
+from .visual.qt_icons import load_pycforge_icon
+from .widgets import label, button
+
+
+class StartupDialog(Dialog):
+    offline_requested = Signal()
+    locate_requested = Signal()
+    retry_requested = Signal()
+    engine_selected = Signal(str)
+
+    def __init__(self, parent=None):
+        super().__init__("PyCForge SDK", parent)
+        self.setObjectName("SDKStartup")
+        self.setWindowModality(Qt.WindowModality.WindowModal)
+        self.engines = []
+        self.searching = True
+        heading = QHBoxLayout()
+        mark = QLabel(); mark.setFixedSize(64, 64)
+        mark.setPixmap(sdk_icon().pixmap(mark.size(), self.devicePixelRatioF()))
+        heading.addWidget(mark)
+        title = label("Your conversion workshop")
+        title.setObjectName("SDKWelcomeTitle")
+        heading.addWidget(title, 1)
+        self.body.addLayout(heading)
+        self.caption = label("Conversion capabilities, starters and reference — supplied by PyCForge.", muted=True)
+        self.body.addWidget(self.caption)
+        self.status = label("Finding your PyCForge installation…")
+        self.status.setObjectName("SDKConnectionTitle")
+        self.body.addWidget(self.status)
+        self.detail = label("Checking the saved connection and common installation locations.", muted=True)
+        self.body.addWidget(self.detail)
+        self.location = PathLabel(); self.location.setAccessibleName("Installation being checked")
+        self.body.addWidget(self.location)
+        self.progress = QProgressBar()
+        self.progress.setAccessibleName("PyCForge connection progress")
+        self.progress.setTextVisible(False); self.progress.setRange(0, 100)
+        self.body.addWidget(self.progress)
+        self.choices = QListWidget(); self.choices.setIconSize(QSize(24, 24))
+        self.choices.setAccessibleName("Discovered PyCForge installations")
+        self.choices.setTextElideMode(Qt.TextElideMode.ElideMiddle)
+        self.choices.currentRowChanged.connect(self._choice_changed)
+        self.choices.itemDoubleClicked.connect(lambda _item: self.choose())
+        self.choices.hide(); self.body.addWidget(self.choices, 1)
+        row = QHBoxLayout()
+        self.locate = button("Locate PyCForge…", "open", self.locate_requested.emit)
+        self.retry = button("Search again", "history", self.retry_requested.emit)
+        self.connect = button("Use selected", "link-c", self.choose)
+        self.connect.setProperty("sdkAccent", True)
+        self.offline = button("Continue offline", "cancel", self.offline_requested.emit)
+        for item in (self.locate, self.retry, self.connect, self.offline):
+            row.addWidget(item)
+        self.body.addLayout(row)
+        self.search_started()
+        self.resize(720, 365)
+
+    def search_started(self):
+        self.searching = True
+        self.status.setText("Finding your PyCForge installation…")
+        self.detail.setText("Checking the saved connection and common installation locations.")
+        self.location.setText("")
+        self.progress.setRange(0, 100); self.progress.setValue(0)
+        self.choices.hide(); self.connect.hide(); self.locate.hide(); self.retry.hide()
+        self.offline.setEnabled(True)
+
+    def update_progress(self, event):
+        self.status.setText(event.get("name", "Looking for PyCForge…"))
+        self.location.setText(event.get("path", ""))
+        current, total = event.get("current", 0), event.get("total", 1)
+        self.progress.setValue(min(85, int(85 * current / max(1, total))))
+
+    def connecting(self, path):
+        self.status.setText("Refreshing your engine reference…")
+        self.detail.setText("Loading the conversion capabilities and starter projects from this installation.")
+        self.location.setText(path); self.progress.setValue(90)
+        self.choices.hide(); self.connect.hide(); self.locate.hide(); self.retry.hide()
+
+    def show_choices(self, engines, *, limited=False):
+        self.searching = False; self.engines = engines
+        self.status.setText("Choose your PyCForge installation")
+        self.detail.setText("Several installations are available. The SDK will remember your choice." +
+                            (" The search reached its limit; Locate can find another installation." if limited else ""))
+        self.location.setText(""); self.progress.setValue(100)
+        self.choices.clear()
+        for engine in engines:
+            title = "PyCForge " + engine["engine"]["engine_version"]
+            if not engine["execution_available"]:
+                title += " · reference only"
+            item = QListWidgetItem(load_pycforge_icon("module"), title + "\n" + engine["engine_python"])
+            item.setToolTip(engine["engine_python"] + "\nSupport folder: " + engine["folder"])
+            item.setSizeHint(QSize(300, 64)); self.choices.addItem(item)
+        self.choices.show(); self.connect.show(); self.connect.setEnabled(False)
+        self.locate.show(); self.retry.show(); self.resize(760, 490)
+
+    def failed(self, message):
+        self.searching = False
+        self.status.setText("PyCForge needs locating")
+        self.detail.setText(message + " Select its installation, Python environment, or installed SDK support folder. "
+                            "You can also continue with any cached reference and local projects.")
+        self.location.setText(""); self.progress.setValue(0)
+        self.choices.hide(); self.connect.hide(); self.locate.show(); self.retry.show()
+        self.offline.setEnabled(True)
+
+    def _choice_changed(self, row):
+        self.connect.setEnabled(0 <= row < len(self.engines))
+
+    def choose(self):
+        row = self.choices.currentRow()
+        if 0 <= row < len(self.engines):
+            self.engine_selected.emit(self.engines[row]["engine_python"])
+
+    def reject(self):
+        # The owner cancels and waits asynchronously before releasing this window.
+        self.offline_requested.emit()

pycforge_sdk/gui/visual/__init__.py

@@ -0,0 +1 @@
+"""Preserved PyCForge 1.3.67 presentation components; no engine imports."""