sapwright 0.0.1__py3-none-any.whl

sapwright/__init__.py

@@ -0,0 +1,213 @@
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from types import TracebackType
+from typing import final
+
+from sapwright._utils import default_password_generator, launch_saplogon
+from sapwright.connection_manager import ConnectionManager
+from sapwright.exceptions import SAPLoginError
+from sapwright.objects import GuiSession
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SAPLoginScreenElements:
+    client = "wnd[0]/usr/txtRSYST-MANDT"
+    username = "wnd[0]/usr/txtRSYST-BNAME"
+    password = "wnd[0]/usr/pwdRSYST-BCODE"
+    language = "wnd[0]/usr/txtRSYST-LANGU"
+    terminate_other_sessions_radio = "wnd[1]/usr/radMULTI_LOGON_OPT1"
+    reset_password = r"wnd[1]/usr/lblRSYST-NCODE_TEXT"
+    new_password = "wnd[1]/usr/pwdRSYST-NCODE"
+    repeat_password = "wnd[1]/usr/pwdRSYST-NCOD2"
+
+
+@final
+class Sapwright:
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        connection_string: str | None = None,
+        connection_name: str | None = None,
+        client: int | None = None,
+        language: str | None = None,
+        terminate_other_sessions: bool = True,
+        exe_path: str | Path | None = None,
+        password_generator: Callable[[], str] | None = None,
+    ):
+        """
+        First preference is given to the connection_string, then connection_name.
+
+        password_generator is called to produce a new password when SAP asks
+        for a password change during login. Defaults to month and year of
+        today's date, e.g. "Jan@2026".
+        """
+        if not connection_string and not connection_name:
+            raise ValueError("connection_string or connection_name must be provided.")
+
+        self._username = username
+        self._password = password
+        self._connection_string = connection_string
+        self._connection_name = connection_name
+        self._client = client
+        self._language = language
+        self._terminate_other_sessions = terminate_other_sessions
+        self._exe_path = exe_path
+        self._password_generator = password_generator or default_password_generator
+        self._connection_mgr = ConnectionManager()
+        self._session: GuiSession | None = None
+
+    def __enter__(self):
+        return self.connect()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._session:
+            self._session.close()
+
+    def connect(self) -> GuiSession:
+        """Attach to the user's existing connection, or open a new one if none is found.
+
+        When opening, connection_string takes precedence over connection_name.
+        """
+        session = self._attach_existing() or self._open_new()
+        self._login(session)
+        self._session = session
+        return session
+
+    def close_connection(self):
+        """Closes the SAP connection including all its sessions.
+
+        Logs off by sending "/nex" to the session, falling back to
+        connection.CloseConnection() if the command fails.
+        """
+        session, self._session = self._session, None
+        if session is None:
+            self._connection_mgr.close_connection()
+            return
+
+        try:
+            session.send_command("/nex")
+        except Exception as e:
+            logger.debug(f"'/nex' failed, closing connection directly: {e}")
+            self._connection_mgr.close_connection()
+
+    def _attach_existing(self) -> GuiSession | None:
+        # find existing connections of the user
+        connection = self._connection_mgr.find_connection_by_user(
+            self._username,
+            connection_string=self._connection_string,
+            connection_name=self._connection_name,
+        )
+        if not connection:
+            return None
+
+        logger.debug(
+            f"Attaching to existing connection '{connection.Description}' for user: {self._username}"
+        )
+        return GuiSession(connection.Children(0))
+
+    def _open_new(self) -> GuiSession:
+        logger.info(
+            f"No existing connection with given connection_string or connection_name found for user: {self._username}, opening a new one"
+        )
+        launch_saplogon(self._exe_path)
+        return self._connection_mgr.open_connection(
+            connection_string=self._connection_string,
+            connection_name=self._connection_name,
+        )
+
+    def _login(self, session: GuiSession):
+        """Performs SAP login with provided credentials
+
+        This method performs SAP login with the provided credentials, handling
+        multiple login attempts, incorrect password attempts, terminating other
+        sessions logged in other computers, and dismissing any additional popups
+        that may appear after login.
+
+        Raises
+        ------
+        SAPLoginError
+            If the login process fails
+        """
+        user_field = session.find_by_id(
+            SAPLoginScreenElements.username, raise_error=False
+        )
+        if not user_field:
+            logger.debug("Login screen not found, assuming user is already logged in")
+            return
+
+        logger.debug(f"Logging in as: {self._username}")
+        user_field.text = self._username
+        session.find_by_id(SAPLoginScreenElements.password).text = self._password
+
+        if self._client:
+            session.find_by_id(SAPLoginScreenElements.client).text = self._client
+
+        if self._language:
+            session.find_by_id(SAPLoginScreenElements.language).text = self._language
+
+        session.press_enter()
+
+        # Check for immediate login errors (e.g invalid credentials)
+        status = session.raise_for_status(
+            message="Login failed", exception=SAPLoginError
+        )
+
+        # Handle multi-logon
+        if status.text and "already logged on" in status.text.lower():
+            self._handle_multi_logon(session)
+
+        # Handle new/reset password dialog
+        if session.find_by_id(SAPLoginScreenElements.reset_password, False):
+            self._change_password(session)
+
+        # Dismiss any other popups
+        session.dismiss_popups(limit=10)
+
+    def _change_password(self, session: GuiSession):
+        logger.debug("Password change requested")
+        new_password = self._password_generator()
+        if not new_password:
+            raise SAPLoginError("password_generator must return a non-empty string.")
+
+        session.find_by_id(SAPLoginScreenElements.new_password).text = new_password
+        session.find_by_id(SAPLoginScreenElements.repeat_password).text = new_password
+        session.press_enter(1)
+
+        session.raise_for_status(
+            message="Password change failed", exception=SAPLoginError
+        )
+        if session.find_by_id(SAPLoginScreenElements.reset_password, False):
+            raise SAPLoginError("Password change failed: new password was rejected.")
+
+        self._password = new_password
+        logger.info(f"Password changed for user: {self._username}")
+
+    def _handle_multi_logon(self, session: GuiSession):
+        # TODO: If server supports multi-logon, allow user to multi-logon
+
+        logger.debug("Multi-logon detected")
+        if not self._terminate_other_sessions:
+            raise SAPLoginError("User already logged on in some other session.")
+
+        logger.debug("Terminating other sessions")
+        try:
+            rb = session.find_by_id(
+                SAPLoginScreenElements.terminate_other_sessions_radio, raise_error=False
+            )
+            if rb:
+                rb.select()
+        except Exception as e:
+            logger.warning(
+                f"Could not find multi-logon terminate radio button, attempting to press enter key: {e}"
+            )
+        session.press_enter(1)

sapwright/_utils.py

@@ -0,0 +1,140 @@
+import datetime
+import logging
+import sys
+import winreg
+from pathlib import Path
+from typing import Any
+
+import psutil
+import pywintypes
+import win32com.client as win32
+from pywinauto import Application
+from pywinauto.timings import TimeoutError as PywinautoTimeoutError
+
+from sapwright.exceptions import SAPLogonError
+
+logger = logging.getLogger(__name__)
+
+SAPLOGON_EXE = "saplogon.exe"
+DEFAULT_TIMEOUT = 60
+REGISTRY_KEYS = (
+    r"SOFTWARE\SAP\SAP Shared",
+    r"SOFTWARE\WOW6432Node\SAP\SAP Shared",
+)
+
+
+def launch_saplogon(exe_path: str | Path | None = None, timeout: int = 60) -> None:
+    """Launches the SAP Logon Pad executable and waits for it to become ready.
+    If no exe_path is provided, saplogon.exe is resolved from windows registry.
+
+    Parameters
+    ----------
+    exe_path : str | Path | None, optional
+        Path to the saplogon executable, by default None
+    timeout : int, optional
+        Maximum time to wait for the application to become ready, by default 30
+
+    Raises
+    ------
+    NotImplementedError
+        If called on non-windows platform
+    FileNotFoundError
+        If the saplogon executable cannot be found
+    TimeoutError
+        If timeout waiting for the main window after launching.
+    SAPLogonError
+        If the SAP Logon fails to launch
+    """
+    if sys.platform != "win32":
+        raise NotImplementedError("Launch SAP Logon only supported on Windows")
+
+    if is_process_running(SAPLOGON_EXE):
+        logger.debug("SAP Logon is already running")
+        return
+
+    path = Path(exe_path) if exe_path else get_saplogon_path()
+    if path is None or not path.is_file():
+        raise FileNotFoundError(
+            f"SAP Logon executable not found at {path or 'registry'}"
+        )
+
+    logger.debug(f"Launching SAP Logon from '{path}'")
+    try:
+        process = psutil.Popen([path])
+        app = Application().connect(process=process.pid, timeout=timeout)
+        app.top_window().wait("ready", timeout=timeout)
+    except PywinautoTimeoutError as e:
+        raise TimeoutError(f"Timeout waiting for SAP Logon to become ready: {e}") from e
+    except Exception as e:
+        msg = f"Failed to connect to SAP Logon: {e}"
+        logger.error(msg)
+        raise SAPLogonError(msg) from e
+
+    logger.debug("SAP Logon launched and ready")
+
+
+def is_process_running(process_name: str) -> bool:
+    """Checks if a process with the given name is running.
+
+    Parameters
+    ----------
+    process_name : str
+        Name of the process
+
+    Returns
+    -------
+    bool
+        True if the process is running
+
+    Example
+    -------
+    >>> is_process_running("saplogon.exe")
+    True
+    """
+    target = process_name.lower()
+    for proc in psutil.process_iter(["name"]):
+        if (proc.info["name"] or "").lower() == target:
+            return True
+    return False
+
+
+def get_saplogon_path() -> Path | None:
+    """Finds the saplogon executable path from the windows registry, or None if not found.
+
+    Returns
+    -------
+    Path | None
+        Path to the saplogon.exe or None if not found
+    """
+    for key_path in REGISTRY_KEYS:
+        try:
+            with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, key_path) as key:
+                install_dir, _ = winreg.QueryValueEx(key, "SAPsysdir")
+        except FileNotFoundError:
+            continue
+
+        path = Path(install_dir) / SAPLOGON_EXE
+        if path.is_file():
+            return path
+
+    return None
+
+
+def default_password_generator() -> str:
+    """Generates a password from the current month abbreviation and year.
+
+    Example
+    -------
+    >>> default_password_generator()  # on 2026-01-15
+    'Jan@2026'
+    """
+    return datetime.date.today().strftime("%b@%Y")  # noqa: DTZ011
+
+
+def get_scripting_engine() -> Any | None:
+    """Returns the SAP GUI scripting engine, or None if SAP Logon is not running."""
+    try:
+        rot_entry = win32.GetObject("SAPGUI")
+    except pywintypes.com_error:
+        return None
+    return rot_entry.GetScriptingEngine

sapwright/connection_manager.py

@@ -0,0 +1,125 @@
+import logging
+from typing import Any
+
+from sapwright._utils import get_scripting_engine
+from sapwright.exceptions import SAPConnectionError, SAPLogonError, SAPScriptingDisabled
+from sapwright.objects import GuiSession
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize(value: object) -> str:
+    return str(value).strip().lower()
+
+
+def _matches(
+    connection: Any, connection_string: str | None, connection_name: str | None
+) -> bool:
+    """Match by connection string (substring) if given, otherwise by description."""
+    if connection_string:
+        # connection_string returned by SAP logon contains a lot more text and other details
+        # we would only want to check for a substring match
+        return connection_string.lower() in str(connection.ConnectionString).lower()
+
+    # Case-insensitive connection name matching
+    return _normalize(connection.Description) == _normalize(connection_name)
+
+
+class ConnectionManager:
+    def __init__(self) -> None:
+        self._connection: Any = None
+
+    def find_connection_by_user(
+        self,
+        username: str,
+        connection_string: str | None = None,
+        connection_name: str | None = None,
+    ) -> Any | None:
+        """Check if a connection for the specified user is already open.
+
+        Returns
+        -------
+        object or None
+            The underlying native GuiConnection COM object if a matching connection
+            has a session logged in as the user, otherwise None
+
+        Raises
+        ------
+        ValueError
+            If neither connection_string nor connection_name is provided
+        SAPScriptingDisabled
+            If SAP GUI Scripting is disabled by the server
+        """
+        if not connection_string and not connection_name:
+            raise ValueError("connection_string or connection_name must be provided.")
+
+        application = get_scripting_engine()
+        if application is None:
+            return None
+
+        user = _normalize(username)
+        for i in range(application.Children.Count):
+            connection = application.Children(i)
+            if connection.DisabledByServer:
+                raise SAPScriptingDisabled(
+                    "SAP GUI Scripting is disabled by server. Contact your SAP basis team to enable it."
+                )
+            if not _matches(connection, connection_string, connection_name):
+                continue
+
+            sessions = connection.Children
+            for j in range(sessions.Count):
+                if _normalize(sessions(j).Info.User) == user:
+                    self._connection = connection
+                    return connection
+
+        return None
+
+    def open_connection(
+        self,
+        connection_string: str | None = None,
+        connection_name: str | None = None,
+    ) -> GuiSession:
+        """Open a new connection and return its first session.
+
+        connection_string takes precedence over connection_name.
+
+        Raises
+        ------
+        SAPLogonError
+            If SAP Logon is not running
+        SAPConnectionError
+            If the connection could not be opened
+        """
+        application = get_scripting_engine()
+        if application is None:
+            raise SAPLogonError("SAP Logon is not running")
+
+        try:
+            if connection_string:
+                connection = application.OpenConnectionByConnectionString(
+                    connection_string, True, True
+                )
+            else:
+                connection = application.OpenConnection(connection_name, True, True)
+
+            self._connection = connection
+            return GuiSession(connection.Children(0))
+        except Exception as e:
+            msg = f"Failed to open SAP connection: {e}"
+            logger.error(msg)
+            raise SAPConnectionError(msg) from e
+
+    def close_connection(self):
+        """
+        Closes the SAP connection including all sessions.
+        This method closes the SAP connection and all associated sessions,
+        and cleans up the internal references to the SAP GUI objects.
+        """
+        try:
+            self._connection.CloseConnection()
+            logger.debug("SAP connection closed")
+        except Exception as e:
+            logger.error(f"Error while closing connection: {e}")
+
+        self._connection = None

sapwright/exceptions.py

@@ -0,0 +1,46 @@
+class SAPGuiError(Exception):
+    """Base class for all SAP GUI related errors"""
+
+
+class SAPLogonError(SAPGuiError):
+    """Raised when SAP Logon fails to launch"""
+
+
+class SAPConnectionError(SAPGuiError):
+    """Raised when a connection to SAP Logon fails"""
+
+
+class SAPScriptingDisabled(SAPGuiError):
+    """Raised when SAP GUI Scripting is disabled by server"""
+
+
+class SAPElementNotFound(SAPGuiError):
+    """Raised when a SAP GUI element is not found"""
+
+
+class SAPElementNotChangeable(SAPGuiError):
+    """Raised when attempting to modify a read-only element."""
+
+
+class SAPComboBoxOptionNotFound(SAPGuiError):
+    """Raised when a specified option is not available in a ComboBox."""
+
+
+class SAPStatusBarError(SAPGuiError):
+    """Raised when there is an error in the status bar."""
+
+
+class SAPTransactionError(SAPGuiError):
+    """Raised when a transaction fails to start or encounters a critical error."""
+
+
+class SAPLoginError(SAPGuiError):
+    """Raised when the login process fails."""
+
+
+class SAPElementTypeMismatch(SAPGuiError):
+    """Raised when the element type does not match the expected type."""
+
+
+class SAPTableConfigurationError(SAPGuiError):
+    """Raised when there is a mismatch or error in table configuration/population."""

sapwright/models.py

@@ -0,0 +1,41 @@
+from pydantic import BaseModel
+
+
+class StatusBarMsg(BaseModel):
+    """The status bar message"""
+
+    id: str
+    type: str
+    text: str
+    number: str
+    has_longtext: int
+    is_popup: bool | None
+
+
+class SessionInfo(BaseModel):
+    """Session information"""
+
+    application_server: str = ""
+    client: str = ""
+    codepage: int | None = None
+    flushes: int | None = None
+    group: str = ""
+    gui_codepage: int | None = None
+    i18n_mode: bool | None = None
+    interpretation_time: int | None = None
+    is_low_speed_connection: bool | None = None
+    language: str = ""
+    message_server: str = ""
+    program: str = ""
+    response_time: int | None = None
+    round_trips: int | None = None
+    screen_number: int | None = None
+    scripting_mode_force_notification: bool | None = None
+    scripting_mode_read_only: bool | None = None
+    scripting_mode_recording_disabled: bool | None = None
+    system_name: str = ""
+    session_number: int | None = None
+    system_session_id: str = ""
+    transaction: str = ""
+    ui_guideline: int | None = None
+    user: str = ""

sapwright/objects/__init__.py

@@ -0,0 +1,16 @@
+from sapwright.objects.component import GuiComponent, GuiComponentCollection
+from sapwright.objects.scrollbar import GuiScrollbar
+from sapwright.objects.session import GuiSession
+from sapwright.objects.shell import GuiShell
+from sapwright.objects.table_control import GuiTableColumn, GuiTableControl, GuiTableRow
+
+__all__ = [
+    "GuiComponent",
+    "GuiComponentCollection",
+    "GuiScrollbar",
+    "GuiSession",
+    "GuiShell",
+    "GuiTableColumn",
+    "GuiTableControl",
+    "GuiTableRow",
+]