robotframework-velo-sapgui 0.2.2__py3-none-any.whl

SapLibrary/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from SapLibrary.exceptions import SapConnectionError, SapKeywordError, SapLibraryError
+
+try:
+    __version__ = version("robotframework-velo-sapgui")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    "SapLibrary",
+    "SapLibraryError",
+    "SapConnectionError",
+    "SapKeywordError",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name == "SapLibrary":
+        from SapLibrary.library import SapLibrary
+
+        globals()["SapLibrary"] = SapLibrary
+        return SapLibrary
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

SapLibrary/backends/__init__.py

@@ -0,0 +1,5 @@
+"""SAP automation backends (Java gateway and Windows COM)."""
+
+from SapLibrary.backends.base import SapAutomationBackend, resolve_client
+
+__all__ = ["SapAutomationBackend", "resolve_client"]

SapLibrary/backends/base.py

@@ -0,0 +1,70 @@
+"""Backend interface for SAP GUI automation (Java gateway or Windows COM)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+def resolve_client(client: str | None = None) -> str:
+    """Resolve SAP client type: ``auto``, ``java``, or ``windows``."""
+    raw = (client or os.getenv("VELO_SAP_CLIENT") or "auto").strip().lower()
+    if raw not in ("auto", "java", "windows"):
+        raise ValueError(f"Invalid SAP client '{client}'. Expected auto, java, or windows.")
+    if raw == "auto":
+        return "windows" if sys.platform == "win32" else "java"
+    if raw == "windows" and sys.platform != "win32":
+        raise RuntimeError(
+            "SAP GUI for Windows backend requires a Windows host. "
+            "Use client=java or VELO_SAP_CLIENT=java for Docker/Java execution."
+        )
+    return raw
+
+
+class BackendResponse:
+    """Minimal response object compatible with Java StepResponse accessors."""
+
+    def __init__(self, success: bool, message: str = "", result: Any = None) -> None:
+        self._success = success
+        self._message = message
+        self._result = result
+
+    def isSuccessful(self) -> bool:
+        return self._success
+
+    def getMessage(self) -> str:
+        return self._message
+
+    def getResult(self) -> Any:
+        return self._result
+
+
+class SapAutomationBackend(ABC):
+    """Abstract SAP automation backend."""
+
+    @abstractmethod
+    def ensure_connected(self) -> None:
+        """Open backend resources if needed."""
+
+    @abstractmethod
+    def call(self, method: str, *args: Any) -> Any:
+        """Invoke a facade method by name."""
+
+    @abstractmethod
+    def start_event_capture(self) -> None:
+        """Begin scripting event capture."""
+
+    @abstractmethod
+    def stop_event_capture(self) -> str | None:
+        """Stop event capture and return output path."""
+
+    @abstractmethod
+    def cleanup(self, close_app: bool = True, stop_recording: bool = True) -> str:
+        """Release backend resources."""
+
+    @property
+    @abstractmethod
+    def client_name(self) -> str:
+        """Backend identifier (``java`` or ``windows``)."""

SapLibrary/backends/event_capture.py

@@ -0,0 +1,78 @@
+"""Normalized scripting event log (events.jsonl) shared by Java and Windows backends."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+
+class EventCaptureWriter:
+    """Append-only JSONL writer for SAP GUI scripting interaction events."""
+
+    def __init__(self, output_path: Path | None = None) -> None:
+        results_dir = os.environ.get("RESULTS_DIR", "/results")
+        default_path = Path(results_dir) / "events.jsonl"
+        env_path = os.environ.get("VELO_EVENTS_PATH")
+        self._path = Path(output_path or env_path or default_path)
+        self._active = False
+        self._lock = Lock()
+        self._events: list[dict[str, Any]] = []
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def start(self) -> None:
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._events = []
+            self._active = True
+
+    def record(
+        self,
+        action: str,
+        *,
+        element_id: str = "",
+        name: str = "",
+        element_type: str = "",
+        value: str = "",
+        screen_context: str = "",
+        source: str = "",
+    ) -> None:
+        if not self._active:
+            return
+        event = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "action": action,
+            "element_id": element_id,
+            "name": name,
+            "type": element_type,
+            "value": value,
+            "screen_context": screen_context,
+            "source": source,
+        }
+        with self._lock:
+            self._events.append(event)
+
+    def stop(self) -> str:
+        with self._lock:
+            if not self._active:
+                return str(self._path)
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("w", encoding="utf-8") as handle:
+                for event in self._events:
+                    handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+            self._active = False
+            return str(self._path)
+
+    def get_events(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return list(self._events)

SapLibrary/backends/java_gateway.py

@@ -0,0 +1,126 @@
+"""Java py4j gateway backend (SAP GUI for Java)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from py4j.java_gateway import GatewayParameters, JavaGateway
+from py4j.protocol import Py4JError, Py4JJavaError
+
+from SapLibrary.backends.base import SapAutomationBackend
+from SapLibrary.exceptions import SapConnectionError, SapKeywordError
+
+logger = logging.getLogger(__name__)
+
+
+class JavaGatewayBackend(SapAutomationBackend):
+    """Drive SAP GUI for Java via the sapgui-engine py4j gateway."""
+
+    def __init__(self, port: int = 8081) -> None:
+        self._port = int(port)
+        self._gateway: JavaGateway | None = None
+        self._automation: Any = None
+        self._event_capture_active = False
+
+    @property
+    def client_name(self) -> str:
+        return "java"
+
+    def ensure_connected(self) -> None:
+        if self._gateway is not None:
+            return
+        try:
+            self._gateway = JavaGateway(
+                gateway_parameters=GatewayParameters(
+                    port=self._port,
+                    auto_field=True,
+                )
+            )
+            self._automation = self._gateway.entry_point.getAutomationFacade()
+        except Exception as exc:
+            self._gateway = None
+            self._automation = None
+            raise SapConnectionError(
+                f"Cannot connect to the Java automation gateway on port {self._port}. "
+                "Ensure the Java process is running before calling any keyword."
+            ) from exc
+
+    def call(self, method: str, *args: Any) -> Any:
+        self.ensure_connected()
+        try:
+            response = getattr(self._automation, method)(*args)
+        except (Py4JJavaError, Py4JError) as exc:
+            raise SapKeywordError(method, exc) from exc
+        except AttributeError as exc:
+            raise SapKeywordError(method, exc) from exc
+
+        if hasattr(response, "isSuccessful") and not response.isSuccessful():
+            msg = response.getMessage() if hasattr(response, "getMessage") else "Action failed"
+            raise SapKeywordError(method, msg)
+
+        return response
+
+    def start_event_capture(self) -> None:
+        self.ensure_connected()
+        response = self._automation.startEventCapture()
+        if hasattr(response, "isSuccessful") and not response.isSuccessful():
+            msg = (
+                response.getMessage()
+                if hasattr(response, "getMessage")
+                else "startEventCapture failed"
+            )
+            raise SapConnectionError(msg)
+        self._event_capture_active = True
+
+    def stop_event_capture(self) -> str | None:
+        if not self._event_capture_active or self._automation is None:
+            return None
+        try:
+            result = self._automation.stopEventCapture()
+            self._event_capture_active = False
+            return str(result) if result is not None else None
+        except Exception as exc:
+            logger.warning("JavaGatewayBackend: stopEventCapture() failed: %s", exc)
+            return None
+
+    def cleanup(self, close_app: bool = True, stop_recording: bool = True) -> str:
+        if self._gateway is None:
+            return "Cleanup: gateway was already closed."
+
+        events_path: str | None = None
+        if stop_recording:
+            events_path = self.stop_event_capture()
+
+        if close_app and self._automation is not None:
+            try:
+                self._automation.closeApplication()
+            except Exception:
+                logger.warning("JavaGatewayBackend: closeApplication() failed during cleanup.")
+
+        try:
+            self._gateway.close()
+        except Exception:
+            logger.warning("JavaGatewayBackend: gateway.close() failed.")
+        finally:
+            self._gateway = None
+            self._automation = None
+            self._event_capture_active = False
+
+        return events_path or "Cleanup complete."
+
+    def get_captured_events(self) -> list[Any]:
+        self.ensure_connected()
+        return list(self._automation.getCapturedEvents())
+
+    def close_gateway_only(self) -> None:
+        """Close py4j socket without closing the SAP application."""
+        if self._gateway is None:
+            return
+        try:
+            self._gateway.close()
+        except Exception:
+            pass
+        finally:
+            self._gateway = None
+            self._automation = None