iris-pex-embedded-python 3.7.2b2__py3-none-any.whl → 4.0.0__py3-none-any.whl

iop/runtime/remote/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .director import _print_log_entry, _RemoteDirector
+from .settings import get_remote_settings
+from .settings import load_remote_settings_from_file as _load_remote_settings_from_file
+
+__all__ = [
+    "_RemoteDirector",
+    "_load_remote_settings_from_file",
+    "_print_log_entry",
+    "get_remote_settings",
+]

iop/runtime/remote/client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+import urllib3
+
+
+class _RemoteClient:
+    """Small HTTP client for the IOP REST API."""
+
+    def __init__(self, remote_settings: dict[str, Any]) -> None:
+        self._url = remote_settings["url"].rstrip("/")
+        self._base = self._url + "/api/iop"
+        self._auth = (
+            remote_settings.get("username", ""),
+            remote_settings.get("password", ""),
+        )
+        self._namespace: str = remote_settings.get("namespace", "USER")
+        self._verify: bool = remote_settings.get("verify_ssl", True)
+        if not self._verify:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        """Like resp.raise_for_status() but includes the response body error message."""
+        if resp.ok:
+            return
+        try:
+            body = resp.json()
+            error = body.get("error") or body.get("message") or resp.text
+        except Exception:
+            error = resp.text or resp.reason
+        raise requests.exceptions.HTTPError(
+            f"{resp.status_code} {resp.reason}: {error}",
+            response=resp,
+        )
+
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        p = {"namespace": self._namespace, **(params or {})}
+        resp = requests.get(
+            f"{self._base}{path}",
+            params=p,
+            auth=self._auth,
+            verify=self._verify,
+            timeout=30,
+        )
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _post(self, path: str, body: dict | None = None) -> Any:
+        resp = requests.post(
+            f"{self._base}{path}",
+            json=(body or {}),
+            params={"namespace": self._namespace},
+            auth=self._auth,
+            verify=self._verify,
+            timeout=30,
+        )
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _put(self, path: str, body: dict | None = None) -> Any:
+        resp = requests.put(
+            f"{self._base}{path}",
+            json=(body or {}),
+            params={"namespace": self._namespace},
+            auth=self._auth,
+            verify=self._verify,
+            timeout=30,
+        )
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _delete(self, path: str, params: dict | None = None) -> Any:
+        p = {"namespace": self._namespace, **(params or {})}
+        resp = requests.delete(
+            f"{self._base}{path}",
+            params=p,
+            auth=self._auth,
+            verify=self._verify,
+            timeout=30,
+        )
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def _check_error(self, data: Any) -> Any:
+        if isinstance(data, dict) and "error" in data:
+            raise RuntimeError(data["error"])
+        return data

iop/runtime/remote/director.py

@@ -0,0 +1,283 @@
+"""Remote director: mirrors _Director's interface over the IOP REST API.
+
+Configure via environment variables:
+    IOP_URL          Required. e.g. http://localhost:8080
+    IOP_USERNAME     Optional. Default: ""
+    IOP_PASSWORD     Optional. Default: ""
+    IOP_NAMESPACE    Optional. Default: "USER"
+    IOP_VERIFY_SSL   Optional. "0"/"false" to disable TLS verification.
+
+Or pass a RemoteSettings dict directly (same shape as REMOTE_SETTINGS in settings.py).
+"""
+
+from __future__ import annotations
+
+import signal
+import time
+
+import requests
+
+from ..protocol import (
+    DirectorProtocol as _DirectorProtocol,  # noqa: F401 --- IGNORE ---
+)
+from .client import _RemoteClient
+from .migration import upload_migration
+from .settings import (
+    get_remote_settings,
+)
+from .settings import (
+    load_remote_settings_from_file as _load_remote_settings_from_file,
+)
+from .setup import setup_remote_classes
+
+__all__ = [
+    "_RemoteDirector",
+    "_load_remote_settings_from_file",
+    "_print_log_entry",
+    "get_remote_settings",
+]
+
+
+class _RemoteDirector(_RemoteClient, _DirectorProtocol):
+    """Implements DirectorProtocol over the IOP REST API."""
+
+    # ------------------------------------------------------------------
+    # Production lifecycle
+    # ------------------------------------------------------------------
+
+    def get_default_production(self) -> str:
+        data = self._check_error(self._get("/default"))
+        return data.get("production") or "Not defined"
+
+    def set_default_production(self, production_name: str = "") -> None:
+        self._check_error(self._put("/default", {"production": production_name}))
+
+    def list_productions(self) -> dict:
+        return self._check_error(self._get("/list"))
+
+    def status_production(self) -> dict:
+        data = self._check_error(self._get("/status"))
+        if not data.get("production"):
+            data["production"] = self.get_default_production()
+        return data
+
+    def start_production(self, production_name: str | None = None) -> None:
+        body: dict = {}
+        if production_name:
+            body["production"] = production_name
+        self._check_error(self._post("/start", body))
+
+    def start_production_with_log(self, production_name: str | None = None) -> None:
+        """Start remotely then stream the log until Ctrl-C (which also stops)."""
+        self.start_production(production_name)
+        prod = production_name or self.get_default_production()
+        print(f"Production '{prod}' started. Streaming log — Ctrl-C to stop.")
+        running = True
+
+        def _sigint(sig, frame):  # pragma: no cover
+            nonlocal running
+            running = False
+
+        signal.signal(signal.SIGINT, _sigint)
+
+        last_id = 0
+        for entry in self._get_log_entries(top=10):
+            _print_log_entry(entry)
+            last_id = max(last_id, entry.get("id", 0))
+
+        while running:
+            time.sleep(1)
+            entries = self._get_log_entries(since_id=last_id)
+            for entry in entries:
+                _print_log_entry(entry)
+                last_id = max(last_id, entry.get("id", 0))
+
+        self.stop_production()
+
+    def stop_production(self) -> None:
+        self._check_error(self._post("/stop"))
+
+    def shutdown_production(self) -> None:
+        self._check_error(self._post("/kill"))
+
+    def restart_production(self) -> None:
+        self._check_error(self._post("/restart"))
+
+    def update_production(self) -> None:
+        self._check_error(self._post("/update"))
+
+    def start_component(self, component_name: str) -> None:
+        self._check_error(
+            self._post("/component/start", {"component": component_name})
+        )
+
+    def stop_component(self, component_name: str) -> None:
+        self._check_error(
+            self._post("/component/stop", {"component": component_name})
+        )
+
+    def restart_component(self, component_name: str) -> None:
+        self._check_error(
+            self._post("/component/restart", {"component": component_name})
+        )
+
+    def list_bindings(self, unused_only: bool = False) -> list[dict]:
+        params = {"unused": 1} if unused_only else {}
+        data = self._check_error(self._get("/bindings", params))
+        return data if isinstance(data, list) else []
+
+    def unbind_component(self, iris_classname: str) -> None:
+        self._check_error(self._delete("/binding", {"class": iris_classname}))
+
+    # ------------------------------------------------------------------
+    # Logging
+    # ------------------------------------------------------------------
+
+    def _get_log_entries(
+        self,
+        top: int = 10,
+        since_id: int | None = None,
+    ) -> list[dict]:
+        params: dict = {}
+        if since_id is not None:
+            params["since_id"] = since_id
+        else:
+            params["top"] = top
+        data = self._check_error(self._get("/log", params))
+        return data if isinstance(data, list) else []
+
+    def log_production_top(self, top: int = 10) -> None:
+        entries = self._get_log_entries(top=top)
+        for entry in reversed(entries):
+            _print_log_entry(entry)
+
+    def log_production(self) -> None:
+        """Stream log continuously until Ctrl-C."""
+        running = True
+
+        def _sigint(sig, frame):  # pragma: no cover
+            nonlocal running
+            running = False
+
+        signal.signal(signal.SIGINT, _sigint)
+
+        last_id = 0
+        for entry in self._get_log_entries(top=10):
+            _print_log_entry(entry)
+            last_id = max(last_id, entry.get("id", 0))
+
+        while running:
+            time.sleep(1)
+            entries = self._get_log_entries(since_id=last_id)
+            for entry in entries:
+                _print_log_entry(entry)
+                last_id = max(last_id, entry.get("id", 0))
+
+    # ------------------------------------------------------------------
+    # Test
+    # ------------------------------------------------------------------
+
+    def test_component(
+        self,
+        target: str | None,
+        message=None,  # ignored remotely — not serialisable over HTTP
+        classname: str | None = None,
+        body: str | dict | None = None,
+        restart: bool = True,
+    ) -> dict:
+        """Returns a dict: {"classname": "...", "body": "...", "truncated": false}.
+
+        If *restart* is True the target component is stopped and restarted on
+        the server before the test message is dispatched.
+        """
+        payload: dict = {"target": target or ""}
+        if classname:
+            payload["classname"] = classname
+        if body is not None:
+            payload["body"] = body
+        if restart:
+            payload["restart"] = True
+        try:
+            return self._check_error(self._post("/test", payload))
+        except requests.exceptions.HTTPError as exc:
+            try:
+                err_msg = exc.response.json().get("error", str(exc))
+            except Exception:
+                err_msg = str(exc)
+            raise RuntimeError(err_msg) from exc
+        except requests.exceptions.RequestException as exc:
+            raise RuntimeError(f"Remote test component error: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    def export_production(self, production_name: str) -> dict:
+        return self._check_error(self._get("/export", {"production": production_name}))
+
+    def export_production_connections(self, production_name: str) -> dict:
+        return self._check_error(
+            self._get("/connections", {"production": production_name})
+        )
+
+    def export_production_queue_info(self, production_name: str) -> dict:
+        return self._check_error(self._get("/queues", {"production": production_name}))
+
+    def apply_production_plan(
+        self,
+        plan: dict,
+        allow_destructive: bool = False,
+    ) -> dict:
+        raise RuntimeError(
+            "Remote production plan apply is not supported in v1. "
+            "Run apply from a local IRIS environment."
+        )
+
+    # ------------------------------------------------------------------
+    # Migrate
+    # ------------------------------------------------------------------
+
+    def migrate(
+        self,
+        path: str,
+        strict_production_validation: bool = False,
+    ) -> None:
+        upload_migration(
+            self,
+            path,
+            strict_production_validation=strict_production_validation,
+        )
+
+    # ------------------------------------------------------------------
+    # Init / setup — uploads .cls files via the Atelier API
+    # ------------------------------------------------------------------
+
+    def setup(self, path: str | None = None) -> None:
+        setup_remote_classes(self, path)
+
+    # ------------------------------------------------------------------
+    # Metadata
+    # ------------------------------------------------------------------
+
+    @property
+    def namespace(self) -> str:
+        return self._namespace
+
+
+# ------------------------------------------------------------------
+# Shared helpers
+# ------------------------------------------------------------------
+
+
+def _print_log_entry(entry: dict) -> None:
+    print(
+        entry.get("time_logged", ""),
+        entry.get("type", ""),
+        entry.get("config_name", ""),
+        entry.get("job", ""),
+        entry.get("message_id", ""),
+        entry.get("session_id", ""),
+        entry.get("source_class", ""),
+        entry.get("source_method", ""),
+        entry.get("text", ""),
+    )

iop/runtime/remote/migration.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+
+import requests
+
+
+def upload_migration(
+    client,
+    path: str,
+    *,
+    strict_production_validation: bool = False,
+) -> None:
+    """Upload .py and .cls files from *path*'s folder to remote IRIS."""
+    folder = os.path.dirname(path)
+
+    package = "python"
+    remote_folder = ""
+    try:
+        spec = importlib.util.spec_from_file_location("_iop_migrate_settings", path)
+        mod = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+        spec.loader.exec_module(mod)  # type: ignore[union-attr]
+        remote_settings = getattr(mod, "REMOTE_SETTINGS", {})
+        package = remote_settings.get("package", package)
+        remote_folder = remote_settings.get("remote_folder", remote_folder)
+    except Exception:
+        pass
+
+    body: list[dict] = []
+    settings_file = os.path.basename(path)
+    for dirpath, _, filenames in os.walk(folder):
+        for fname in sorted(filenames):
+            if not (fname.endswith(".py") or fname.endswith(".cls")):
+                continue
+            full = os.path.join(dirpath, fname)
+            rel = os.path.relpath(full, folder).replace(os.sep, "/")
+            with open(full, encoding="utf-8") as fh:
+                body.append({"name": rel, "data": fh.read()})
+
+    payload = {
+        "namespace": client._namespace,
+        "package": package,
+        "remote_folder": remote_folder,
+        "settings_file": settings_file,
+        "strict_production_validation": bool(strict_production_validation),
+        "body": body,
+    }
+    resp = requests.put(
+        f"{client._base}/migrate",
+        json=payload,
+        params={"namespace": client._namespace},
+        auth=client._auth,
+        verify=client._verify,
+        timeout=30,
+    )
+    client._raise_for_status(resp)

iop/runtime/remote/settings.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import ast
+import os
+from typing import Any
+
+
+def load_remote_settings_from_file(settings_path: str) -> dict[str, Any] | None:
+    """Load a literal ``REMOTE_SETTINGS`` dict without executing the file."""
+    try:
+        with open(settings_path, encoding="utf-8") as fh:
+            tree = ast.parse(fh.read(), filename=settings_path)
+    except (OSError, SyntaxError):
+        return None
+
+    try:
+        for node in tree.body:
+            value = None
+            targets = []
+            if isinstance(node, ast.Assign):
+                value = node.value
+                targets = node.targets
+            elif isinstance(node, ast.AnnAssign):
+                value = node.value
+                targets = [node.target]
+            if value is None:
+                continue
+            if any(
+                isinstance(target, ast.Name) and target.id == "REMOTE_SETTINGS"
+                for target in targets
+            ):
+                remote = ast.literal_eval(value)
+                if isinstance(remote, dict) and "url" in remote:
+                    return remote
+                return None
+    except (ValueError, TypeError):
+        return None
+    return None
+
+
+def get_remote_settings(
+    explicit_settings_path: str | None = None,
+    fallback_settings_path: str | None = None,
+) -> dict[str, Any] | None:
+    """Detect remote settings from env vars or settings files."""
+    url = os.environ.get("IOP_URL")
+    if url:
+        verify_raw = os.environ.get("IOP_VERIFY_SSL", "1")
+        return {
+            "url": url,
+            "username": os.environ.get("IOP_USERNAME", ""),
+            "password": os.environ.get("IOP_PASSWORD", ""),
+            "namespace": os.environ.get("IOP_NAMESPACE", "USER"),
+            "verify_ssl": verify_raw.lower() not in ("0", "false"),
+        }
+
+    for path in filter(
+        None,
+        [
+            explicit_settings_path,
+            os.environ.get("IOP_SETTINGS"),
+            fallback_settings_path,
+        ],
+    ):
+        result = load_remote_settings_from_file(path)
+        if result:
+            return result
+
+    return None

iop/runtime/remote/setup.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import importlib.resources
+import os
+
+import requests
+
+
+def setup_remote_classes(client, path: str | None = None) -> None:
+    """Upload and compile IOP .cls files to remote IRIS via the Atelier REST API."""
+    paths_to_upload: list[str] = []
+    if path is None:
+        try:
+            paths_to_upload.append(str(importlib.resources.files("iop").joinpath("cls")))
+        except ModuleNotFoundError:
+            pass
+    else:
+        paths_to_upload.append(path)
+
+    atelier_base = f"{client._url}/api/atelier/v1"
+    doc_names: list[str] = []
+
+    for cls_root in paths_to_upload:
+        for dirpath, _, filenames in os.walk(cls_root):
+            for fname in sorted(filenames):
+                if not fname.endswith(".cls"):
+                    continue
+                full_path = os.path.join(dirpath, fname)
+                doc_name = (
+                    os.path.relpath(full_path, cls_root)
+                    .replace(os.sep, ".")
+                    .replace("/", ".")
+                )
+                with open(full_path, encoding="utf-8") as fh:
+                    content = fh.read().splitlines()
+                resp = requests.put(
+                    f"{atelier_base}/{client._namespace}/doc/{doc_name}",
+                    json={"enc": False, "content": content},
+                    params={"ignoreConflict": "1"},
+                    auth=client._auth,
+                    verify=client._verify,
+                    timeout=30,
+                )
+                client._raise_for_status(resp)
+                doc_names.append(doc_name)
+                print(f"Uploaded: {doc_name}")
+
+    if not doc_names:
+        raise RuntimeError("No .cls files found to upload.")
+
+    resp = requests.post(
+        f"{atelier_base}/{client._namespace}/action/compile",
+        json=doc_names,
+        params={"flags": "cuk"},
+        auth=client._auth,
+        verify=client._verify,
+        timeout=120,
+    )
+    client._raise_for_status(resp)
+    result = resp.json()
+    for line in result.get("console", []):
+        if line:
+            print(line)
+    errors = result.get("status", {}).get("errors", [])
+    if errors:
+        raise RuntimeError(f"Compilation errors: {errors}")
+    print(
+        "\n.cls files uploaded and compiled successfully."
+        "\nNext step: ensure the 'iop' Python package is installed on the IRIS server:"
+        "\n  python3 -m pip install iris-pex-embedded-python"
+        "\nThis is required for full IOP Support; without it, only the migrate() and export_production() methods will work remotely."
+    )

{iris_pex_embedded_python-3.7.2b2.dist-info → iris_pex_embedded_python-4.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 3.7.2b2
+Version: 4.0.0
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License
@@ -37,6 +37,8 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -61,6 +63,9 @@ Dynamic: license-file
 Welcome to the **Interoperability On Python (IoP)** proof of concept! This project demonstrates how the **IRIS Interoperability Framework** can be utilized with a **Python-first approach**.
 
 Documentation can be found [here](https://grongierisc.github.io/interoperability-embedded-python/).
+For prompt-driven workflows, see [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For task-oriented examples, see the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For application repositories, start from the [reusable AGENTS.md template](https://grongierisc.github.io/interoperability-embedded-python/agents-template/).
 
 ## Example
 
@@ -84,6 +89,10 @@ pip install iris-pex-embedded-python
 
 ## Getting Started
 
-If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Business Operation.
+If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
+
+If you are using an AI coding assistant, start with [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For concrete workflows, use the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For healthcare productions, also see [Healthcare AI-assisted coding](https://grongierisc.github.io/interoperability-embedded-python/healthcare-ai-coding/).
 
 Happy coding!