40class SAPManager:
 41    """Main facade for SAP GUI automation.
 42
 43    This class coordinates the different internal components necessary for
 44    controlling SAP GUI:
 45
 46    - SAPProcessService: Manages the SAP Logon process
 47    - SAPApplication: Accesses the SAP GUI Scripting application
 48    - VBScriptRunner: Executes scripts in parallel
 49
 50    The manager prepares the SAP environment and exposes the SAP GUI Scripting
 51    application, but does not itself open the connection. Connection opening
 52    is the responsibility of SAPApplication, consistent with the COM hierarchy
 53    of SAP GUI Scripting.
 54
 55    When a connection is opened via the application attached to this manager,
 56    the manager remembers it to enable automatic closing when exiting the
 57    `with` context.
 58
 59    Note:
 60        A single `SAPManager` can track **at most one** open connection at a
 61        time. Calling `application.open_connection()` a second time on the
 62        same manager before closing the first (via `close_connection()`)
 63        raises `SAPConnectionException`. If you need several simultaneous
 64        connections, create multiple sessions on one connection instead
 65        (`connection.create_session()`), or use separate `SAPManager`
 66        instances.
 67
 68    Attributes:
 69        _config (SAPConfig): Configuration settings for SAP and automation.
 70        _logger (Callable[[str, bool], None]): The logging function.
 71        _process (SAPProcessService): Service for managing SAP Logon processes.
 72        _runner (VBScriptRunner): Service for asynchronous script execution.
 73        _application (SAPApplication | None): Cached SAP GUI Scripting application.
 74        _connection (SAPConnection | None): The currently active/managed connection.
 75
 76    Example:
 77        Typical usage with a context manager:
 78
 79        ```python
 80        with SAPManager(config) as manager:
 81            application = manager.get_application()
 82            connection = application.open_connection()
 83            session = connection.first_session()
 84        ```
 85    """
 86
 87    def __init__(
 88        self,
 89        config: SAPConfig,
 90        *,
 91        logger: Callable[[str, bool], None] | None = None,
 92        file_validator: Callable[[Path], None] | None = None,
 93        max_parallel_scripts: int = 4,
 94        enable_logging: bool | None = None,
 95    ) -> None:
 96        """Initializes the main SAP GUI manager.
 97
 98        This method constructs the different internal services necessary for
 99        SAP automation from the provided configuration.
100
101        Args:
102            config: Global SAP configuration used for launching SAP Logon and
103                preparing the target connection.
104            logger: Logging function. If None, :func:`~pysapmanager.utils.default_logger`
105                is used. Expected signature:
106                `logger(message: str, critical: bool = False) -> None`.
107            file_validator: File validator eventually used by the script runner.
108                Expected signature: `file_validator(path: Path) -> None`.
109            max_parallel_scripts: Maximum number of scripts executed in parallel
110                by VBScriptRunner. Defaults to 4.
111            enable_logging: Convenience flag equivalent to calling
112                `pysapmanager.set_logging_enabled(enable_logging)` before
113                constructing the manager. Since the underlying switch is
114                library-wide (see :func:`pysapmanager.set_logging_enabled`),
115                passing `enable_logging=False` here silences **all**
116                PySAPManager components for the lifetime of the process, not
117                just this manager instance - including ones created before
118                or after this call, and it stays disabled until something
119                re-enables it. Defaults to `None`, which leaves the current
120                global logging state untouched (so this constructor never
121                surprises you by silently re-enabling logging you disabled
122                elsewhere). Pass `True` explicitly to force logging back on.
123        """
124        if enable_logging is not None:
125            set_logging_enabled(enable_logging)
126
127        self._config = config
128        self._logger = resolve_logger(logger)
129
130        self._process = SAPProcessService(
131            config.sap_logon_path,
132            logger=self._logger,
133        )
134        self._runner = VBScriptRunner(
135            max_workers=max_parallel_scripts,
136            file_validator=file_validator,
137            logger=self._logger,
138        )
139        self._application: SAPApplication | None = None
140        self._connection: SAPConnection | None = None
141
142    @property
143    def process(self) -> SAPProcessService:
144        """SAPProcessService: The SAP Logon process management service."""
145        return self._process
146
147    @property
148    def connection(self) -> SAPConnection | None:
149        """SAPConnection | None: The connection currently registered in the manager, 
150        or None if no connection is registered.
151        """
152        return self._connection
153
154    def get_application(
155        self, retry_count: int = 20, retry_delay: float = 0.5
156    ) -> SAPApplication:
157        """Returns the SAP GUI Scripting application associated with the manager.
158
159        The application is instantiated on demand and then cached for subsequent
160        accesses. This method serves as the normal entry point for obtaining
161        the SAPApplication object from the manager.
162
163        Args:
164            retry_count: Maximum number of attempts to get the SAP GUI Scripting
165                application. Defaults to 20.
166            retry_delay: Delay in seconds between attempts to access the SAP
167                GUI Scripting application. Defaults to 0.5.
168
169        Returns:
170            SAPApplication: Instance of the SAP GUI Scripting application.
171        """
172        if self._application is None:
173            self._application = SAPApplication(
174                config=self._config,
175                script_runner=self._runner,
176                retry_count=retry_count,
177                retry_delay=retry_delay,
178                logger=self._logger,
179                on_connection_opened=self._register_connection,
180            )
181        return self._application
182
183    def _register_connection(self, connection: SAPConnection) -> None:
184        """Registers the connection opened in the manager's context.
185
186        This method is called by the application when it opens a connection
187        in the manager's context. The manager can remember only one connection
188        at a time.
189
190        Args:
191            connection: SAP connection opened via the manager's application.
192
193        Raises:
194            SAPConnectionException: If a connection is already registered in
195                this manager.
196        """
197        if self._connection is not None:
198            raise SAPConnectionException(
199                "A SAP connection is already registered in this manager.",
200                critical=True,
201            )
202        self._connection = connection
203
204    @staticmethod
205    def wait_until(
206        condition: Callable[[], bool],
207        timeout: float = 10,
208        interval: float = 0.2,
209    ) -> bool:
210        """Waits for a condition to become true within a maximum delay.
211
212        This method periodically evaluates a condition until it returns True or
213        until the maximum delay expires. Exceptions raised by the condition are
214        ignored to tolerate transient states, such as during process startup or
215        shutdown.
216
217        Args:
218            condition: Function with no arguments called repeatedly.
219            timeout: Maximum wait duration in seconds.
220            interval: Delay in seconds between condition evaluations.
221
222        Returns:
223            bool: True if the condition becomes true before timeout expiration,
224                False otherwise.
225
226        Example:
227            Wait for a process to stop running:
228
229            ```python
230            SAPManager.wait_until(
231                lambda: not process.is_running(),
232                timeout=10
233            )
234            ```
235        """
236        start = time.time()
237        while time.time() - start < timeout:
238            try:
239                if condition():
240                    return True
241            except Exception:
242                pass
243            time.sleep(interval)
244        return False
245
246    def _reset_sap_logon(self) -> None:
247        """Closes then relaunches SAP Logon.
248
249        This method is used when the target connection defined in the
250        configuration is already open in SAP. It forces a complete restart
251        of SAP Logon to start from a clean state before reopening the connection.
252
253        Raises:
254            TimeoutError: If SAP Logon does not close or relaunch within the
255                allotted time.
256        """
257        self._logger("Closing SAP Logon.", False)
258        self._process.kill()
259
260        if not self.wait_until(lambda: not self._process.is_running()):
261            raise TimeoutError("SAP Logon did not close within the allotted time.")
262
263        self._logger("Reopening SAP Logon.", False)
264        self._process.launch()
265
266        if not self.wait_until(lambda: self._process.is_running()):
267            raise TimeoutError("SAP Logon did not open within the allotted time.")
268
269        self._application = None
270        self._connection = None
271
272    def prepare_sap_environment(self) -> None:
273        """Prepares the SAP environment for the configured target connection.
274
275        Behavior is as follows:
276
277        1. If SAP Logon is not running, it is started.
278        2. If SAP Logon is already running, open connections are inspected.
279        3. If the target connection is already open, SAP Logon is closed and
280           relaunched to ensure a clean state.
281        4. If the target connection is not open, the environment is preserved.
282
283        Raises:
284            TimeoutError: If SAP Logon does not open, close, or relaunch within
285                the allotted time.
286        """
287        if not self._process.is_running():
288            self._logger("SAP Logon is not open. Opening.", False)
289            self._process.launch()
290
291            if not self.wait_until(lambda: self._process.is_running()):
292                raise TimeoutError(
293                    "SAP Logon did not open within the allotted time."
294                )
295
296            self._application = None
297            return
298
299        self._application = None
300        application = self.get_application()
301
302        existing = application.find_connection(self._config.connection_description)
303        if existing is not None:
304            self._logger(
305                f"Target connection '{self._config.connection_description}' "
306                "is already open. Restarting SAP Logon.",
307                False,
308            )
309            self._reset_sap_logon()
310            return
311
312        self._logger(
313            f"Target connection '{self._config.connection_description}' "
314            "is not open. Current environment can be used.",
315            False,
316        )
317
318    def close_connection(self) -> None:
319        """Closes the connection registered in the manager, if any.
320
321        Raises:
322            SAPConnectionException: If the connection closing fails.
323        """
324        if self._connection is None:
325            return
326
327        self._connection.close()
328        self._connection = None
329        self._logger("Manager connection closed.", False)
330
331    def wait_all(self, *futures: Future[Any]) -> None:
332        """Waits for all asynchronous tasks to complete and reraises any exceptions.
333
334        Args:
335            *futures: Set of asynchronous task Future objects to wait for.
336
337        Raises:
338            Exception: Any exception raised in one of the tasks is propagated
339                when calling `future.result()`.
340        """
341        done, _ = wait(futures)
342        for future in done:
343            future.result()
344
345    def shutdown(self) -> None:
346        """Releases the manager's internal resources.
347
348        Gracefully stops components requiring explicit termination, such as
349        the script runner's thread pool.
350        """
351        self._runner.shutdown()
352
353    def __enter__(self) -> SAPManager:
354        """Context manager entry.
355
356        Prepares the SAP environment and returns the manager instance.
357
358        Returns:
359            SAPManager: The initialized manager instance.
360        """
361        self.prepare_sap_environment()
362        return self
363
364    def __exit__(
365        self,
366        exc_type: type[BaseException] | None,
367        exc_value: BaseException | None,
368        traceback: TracebackType | None,
369    ) -> None:
370        """Context manager exit.
371
372        Closes the registered connection then releases internal resources,
373        ensuring cleanup regardless of errors within the `with` block.
374        """
375        try:
376            self.close_connection()
377        finally:
378            self.shutdown()

 31class SAPApplication:
 32    """Represents the SAP GUI Scripting application (GuiApplication).
 33
 34    This class encapsulates access to the SAP GUI Scripting application
 35    exposed by COM and provides the main operations related to open or
 36    unopened SAP connections.
 37
 38    The instance automatically retrieves the COM GuiApplication object upon
 39    creation, with a configurable retry mechanism to tolerate availability
 40    delays in SAP GUI immediately after SAP Logon startup.
 41
 42    Attributes:
 43        _config (SAPConfig): Global configuration for SAP connection parameters.
 44        _script_runner (VBScriptRunner): Executor for VBScript files.
 45        _retry_count (int): Maximum attempts to retrieve COM interface.
 46        _retry_delay (float): Seconds to wait between retry attempts.
 47        _logger (Callable[[str, bool], None]): Logging function for reporting status.
 48        _on_connection_opened (Callable[[SAPConnection], None] | None): Callback for new connections.
 49        _com_application (Any): The underlying COM GuiApplication object.
 50    """
 51
 52    def __init__(
 53        self,
 54        *,
 55        config: SAPConfig,
 56        script_runner: VBScriptRunner,
 57        retry_count: int = 20,
 58        retry_delay: float = 0.5,
 59        logger: Callable[[str, bool], None] | None = None,
 60        on_connection_opened: Callable[[SAPConnection], None] | None = None,
 61    ) -> None:
 62        """Initializes the SAP GUI Scripting application.
 63
 64        Args:
 65            config: Global SAP configuration used particularly for opening the
 66                target connection.
 67            script_runner: VBScript executor used by connections and sessions
 68                created from this application.
 69            retry_count: Maximum number of attempts to retrieve the SAP GUI Scripting
 70                application. Defaults to 20.
 71            retry_delay: Delay in seconds between successive retry attempts.
 72                Defaults to 0.5.
 73            logger: Logging function. If None, :func:`~pysapmanager.utils.default_logger`
 74                is used. Regardless of which logger is used, all output is
 75                subject to the library-wide switch controlled by
 76                :func:`pysapmanager.set_logging_enabled`.
 77            on_connection_opened: Callback invoked when a connection is opened
 78                successfully. Allows a calling component like the manager to
 79                register the opened connection.
 80
 81        Raises:
 82            SAPApplicationException: If the SAP GUI Scripting application cannot
 83                be retrieved after the specified retry attempts.
 84        """
 85        self._config = config
 86        self._script_runner = script_runner
 87        self._retry_count = retry_count
 88        self._retry_delay = retry_delay
 89        self._logger = resolve_logger(logger)
 90        self._on_connection_opened = on_connection_opened
 91        self._com_application = self._acquire_com_application()
 92
 93    def _acquire_com_application(self) -> Any:
 94        """Retrieves the COM GuiApplication object from SAP GUI Scripting.
 95
 96        This method attempts to retrieve the SAPGUI COM object via
 97        win32com.client.GetObject, then accesses its GetScriptingEngine
 98        property to obtain the GuiApplication object.
 99
100        On failure, multiple attempts are made according to the configuration,
101        with a delay between each attempt.
102
103        Returns:
104            The COM GuiApplication object returned by SAP GUI Scripting.
105
106        Raises:
107            SAPApplicationException: If the SAPGUI object is not found, if the
108                scripting engine is unavailable, or if all retry attempts fail.
109        """
110        last_error: Exception | None = None
111
112        for attempt in range(1, self._retry_count + 1):
113            try:
114                sap_gui = win32.GetObject("SAPGUI")
115
116                application = sap_gui.GetScriptingEngine
117                if application is None:
118                    raise SAPApplicationException(
119                        "SAP GUI Scripting engine is unavailable."
120                    )
121
122                self._logger("SAP GUI Scripting application retrieved successfully.", False)
123                return application
124
125            except Exception as exc:
126                last_error = exc
127                self._logger(
128                    f"Attempt {attempt}/{self._retry_count} to access SAP GUI Scripting failed: {exc}",
129                    True,
130                )
131                if attempt < self._retry_count:
132                    time.sleep(self._retry_delay)
133
134        raise SAPApplicationException(
135            f"Unable to access SAP GUI Scripting engine. Ensure SAP GUI Scripting is enabled. "
136            f"Detailed error: {last_error}",
137            critical=True,
138        ) from last_error
139
140    @property
141    def com_object(self) -> Any:
142        """Returns the raw COM GuiApplication object.
143
144        This property exposes the underlying COM object directly to enable
145        advanced use cases not covered by the library's business API.
146
147        Returns:
148            The raw COM object representing the SAP GUI Scripting application.
149        """
150        return self._com_application
151
152    def iter_connections(self) -> Iterator[SAPConnection]:
153        """Iterates over open SAP connections via native COM enumeration.
154
155        This method relies on the COM collection Application.Children as
156        exposed by SAP GUI Scripting. Each COM connection retrieved is wrapped
157        in a SAPConnection instance.
158
159        Yields:
160            SAPConnection: Each open connection currently managed by the application.
161
162        Raises:
163            SAPApplicationException: If iteration over open connections fails due to
164                COM communication errors.
165        """
166        try:
167            for com_connection in self._com_application.Children:
168                yield SAPConnection(
169                    application=self,
170                    com_connection=com_connection,
171                    config=self._config,
172                    script_runner=self._script_runner,
173                    logger=self._logger,
174                )
175        except Exception as exc:
176            raise SAPApplicationException(
177                f"Failed to iterate over open SAP connections: {exc}",
178                critical=True,
179            ) from exc
180
181    def find_connection(self, description: str) -> SAPConnection | None:
182        """Searches for an open connection by its description.
183
184        The comparison is performed on the Description property of each open
185        SAP connection. The description matching is case-sensitive after
186        stripping whitespace.
187
188        Args:
189            description: The exact description of the connection to search for.
190
191        Returns:
192            The matching SAPConnection instance if found, otherwise None.
193        """
194        expected = description.strip()
195
196        for connection in self.iter_connections():
197            try:
198                current = connection.description.strip()
199                if current == expected:
200                    return connection
201            except Exception:
202                continue
203
204        return None
205
206    def open_connection(self, sync: bool = True) -> SAPConnection:
207        """Opens the target SAP connection defined in the configuration.
208
209        This method calls OpenConnection() on the COM application using the
210        connection description defined in SAPConfig. Once the COM connection
211        is obtained, it is wrapped in a SAPConnection instance.
212
213        If the configuration requests it, SAP credentials are automatically
214        injected. If a registration callback was provided, the opened connection
215        is notified to the calling component so it can be remembered.
216
217        Args:
218            sync: Whether the connection opening should be synchronous (waits
219                for the window to fully open). Defaults to True.
220
221        Returns:
222            The open SAP connection wrapped in a business-logic object.
223
224        Raises:
225            SAPConnectionException: If OpenConnection returns None, if the
226                connection description is invalid, or if an underlying COM error
227                occurs during the connection process.
228        """
229        try:
230            com_connection = self._com_application.OpenConnection(
231                self._config.connection_description,
232                sync,
233            )
234
235            if com_connection is None:
236                raise SAPConnectionException(
237                    "OpenConnection returned None (connection failed).",
238                    critical=True,
239                )
240
241            connection = SAPConnection(
242                application=self,
243                com_connection=com_connection,
244                config=self._config,
245                script_runner=self._script_runner,
246                logger=self._logger,
247            )
248            connection.fill_credentials_if_needed()
249
250            if self._on_connection_opened is not None:
251                self._on_connection_opened(connection)
252
253            self._logger(f"SAP connection opened: {connection.description}", False)
254            return connection
255
256        except SAPConnectionException:
257            raise
258        except Exception as exc:
259            raise SAPConnectionException(
260                f"Failed to open SAP connection '{self._config.connection_description}': {exc}",
261                critical=True,
262            ) from exc

 33class SAPConnection:
 34    """Represents an open SAP GUI connection.
 35
 36    This class encapsulates a SAP connection exposed via COM and provides a
 37    simplified business API for manipulating its sessions and performing
 38    standard operations like closing the connection or logging in.
 39
 40    It relies on a combination of raw COM objects, custom session wrappers,
 41    and business configurations.
 42
 43    Attributes:
 44        MAX_SESSIONS (int): The maximum number of sessions allowed for a single 
 45            SAP connection (SAP GUI limit is 6).
 46        _application (SAPApplication): The parent SAP application instance.
 47        _com_connection (Any): The underlying COM GuiConnection object.
 48        _config (SAPConfig): The configuration settings for this connection.
 49        _script_runner (VBScriptRunner): Executor for VBScript files.
 50        _logger (Callable[[str, bool], None]): The logging function.
 51
 52    Example:
 53        >>> connection = application.open_connection()
 54        >>> session = connection.first_session()
 55        >>> new_session = connection.create_session()
 56        >>> connection.close()
 57    """
 58
 59    MAX_SESSIONS = 6
 60    """The maximum number of sessions a user can have open simultaneously on a single connection."""
 61
 62    def __init__(
 63        self,
 64        *,
 65        application: SAPApplication,
 66        com_connection: Any,
 67        config: SAPConfig,
 68        script_runner: VBScriptRunner,
 69        logger: Callable[[str, bool], None] | None = None,
 70    ) -> None:
 71        """Initializes a SAP connection wrapper.
 72
 73        Args:
 74            application: Parent SAP application instance that spawned this connection.
 75            com_connection: COM object representing an existing active SAP connection.
 76            config: SAP configuration associated with this specific connection.
 77            script_runner: Component responsible for executing VBScripts.
 78            logger: Logging function. If None, :func:`~pysapmanager.utils.default_logger`
 79                is used. All output is subject to the library-wide switch
 80                controlled by :func:`pysapmanager.set_logging_enabled`.
 81        """
 82        self._application = application
 83        self._com_connection = com_connection
 84        self._config = config
 85        self._script_runner = script_runner
 86        self._logger = resolve_logger(logger)
 87
 88    @property
 89    def application(self) -> SAPApplication:
 90        """SAPApplication: The parent SAP GUI Scripting application."""
 91        return self._application
 92
 93    @property
 94    def com_object(self) -> Any:
 95        """Any: The raw COM GuiConnection object."""
 96        return self._com_connection
 97
 98    @property
 99    def name(self) -> str:
100        """str: The technical name of the SAP connection."""
101        return self._com_connection.Name
102
103    @property
104    def description(self) -> str:
105        """str: The business description of the SAP connection."""
106        return self._com_connection.Description
107
108    @property
109    def session_count(self) -> int:
110        """int: Number of sessions currently open in the connection."""
111        return self._com_connection.Children.Count
112
113    def sessions(self) -> list[SAPSession]:
114        """Returns all sessions currently open in the connection.
115
116        This method materializes the collection of SAP sessions as a Python list.
117        It is appropriate for the SAP GUI context, where a connection can contain
118        a maximum of six sessions.
119
120        Returns:
121            list[SAPSession]: A list of all active SAP sessions.
122
123        Raises:
124            SAPSessionException: If a session cannot be retrieved or wrapped 
125                correctly due to a COM communication issue.
126        """
127        return [self.session(i) for i in range(self.session_count)]
128
129    def session(self, index: int) -> SAPSession:
130        """Returns the session at the specified index.
131
132        Args:
133            index: The 0-based index of the session to retrieve.
134
135        Returns:
136            SAPSession: The SAP session at the given index.
137
138        Raises:
139            SAPSessionException: If the session cannot be retrieved or if 
140                the index is out of bounds.
141        """
142        try:
143            com_session = self._com_connection.Children(index)
144            return SAPSession(
145                connection=self,
146                com_session=com_session,
147                script_runner=self._script_runner,
148            )
149        except Exception as exc:
150            raise SAPSessionException(
151                f"Failed to retrieve SAP session at index {index}: {exc}",
152                critical=True,
153            ) from exc
154
155    def first_session(self) -> SAPSession:
156        """Returns the first session of the connection.
157
158        Returns:
159            SAPSession: The first active session (index 0).
160
161        Raises:
162            SAPSessionException: If the first session cannot be accessed.
163        """
164        return self.session(0)
165
166    def create_session(
167        self,
168        *,
169        timeout: float = 10.0,
170        poll_delay: float = 0.2,
171    ) -> SAPSession:
172        """Creates and returns a new SAP session.
173
174        Session creation is triggered from the first session of the connection.
175        The method then performs a polling loop to wait for the new session to 
176        appear in the connection's children collection.
177
178        Args:
179            timeout: Maximum time in seconds allowed for the new session to appear.
180                Defaults to 10.0.
181            poll_delay: Interval in seconds between checks for session existence.
182                Defaults to 0.2.
183
184        Returns:
185            SAPSession: The newly created SAP session.
186
187        Raises:
188            SAPSessionException: If the maximum session limit (MAX_SESSIONS) is 
189                reached, if the operation times out, or if a COM error occurs.
190        """
191        try:
192            initial_count = self.session_count
193
194            if initial_count >= self.MAX_SESSIONS:
195                raise SAPSessionException(
196                    f"Maximum number of sessions ({self.MAX_SESSIONS}) reached.",
197                    critical=True,
198                )
199
200            base_session = self._com_connection.Children(0)
201            base_session.CreateSession()
202
203            deadline = time.time() + timeout
204            while time.time() < deadline:
205                current_count = self.session_count
206                if current_count > initial_count:
207                    new_session = self.session(initial_count)
208                    self._logger(
209                        f"New SAP session created successfully: {new_session.name}.",
210                        False
211                    )
212                    return new_session
213                time.sleep(poll_delay)
214
215            raise SAPSessionException(
216                "Timeout during new SAP session creation.",
217                critical=True,
218            )
219
220        except SAPSessionException:
221            raise
222        except Exception as exc:
223            raise SAPSessionException(
224                f"Failed to create a new SAP session: {exc}",
225                critical=True,
226            ) from exc
227
228    def close(self) -> None:
229        """Closes the current SAP connection.
230
231        The method first attempts to close the connection via the native 
232        COM API `CloseConnection()`. If that fails, it attempts a fallback 
233        method by entering the '/nex' command into the SAP command field 
234        of the first session.
235
236        Raises:
237            SAPConnectionException: If all attempts to close the connection fail.
238        """
239        try:
240            self._com_connection.CloseConnection()
241            self._logger("SAP connection closed via CloseConnection().", False)
242            return
243
244        except Exception as close_exc:
245            self._logger(
246                f"CloseConnection() failed: {close_exc}. Attempting via '/nex'.", True
247            )
248
249            try:
250                com_session = self.first_session().com_object
251                com_session.findById("wnd[0]/tbar[0]/okcd").text = "/nex"
252                com_session.findById("wnd[0]").sendVKey(0)
253                self._logger("SAP connection closed via '/nex' command.", False)
254
255            except Exception as nex_exc:
256                raise SAPConnectionException(
257                    "Failed to close SAP connection. "
258                    f"CloseConnection() failed ({close_exc}) and "
259                    f"'/nex' failed ({nex_exc}).",
260                    critical=True,
261                ) from nex_exc
262
263    def fill_credentials_if_needed(self) -> None:
264        """Injects SAP credentials if the configuration requires it.
265
266        This method checks if the configuration mandates a manual login. If 
267        so, it locates the standard SAP fields (Client, User, Password, Language) 
268        in the first session and populates them.
269
270        Raises:
271            SAPConnectionException: If the credential fields cannot be found 
272                on the active screen or if an injection error occurs.
273        """
274        if not self._config.manual_login_required:
275            return
276
277        credentials = self._config.credentials
278        if credentials is None:
279            return
280
281        try:
282            com_session: Any = self.first_session().com_object
283
284            com_session.findById("wnd[0]/usr/txtRSYST-MANDT").text = credentials.client
285            com_session.findById("wnd[0]/usr/txtRSYST-BNAME").text = credentials.username
286            com_session.findById("wnd[0]/usr/pwdRSYST-BCODE").text = credentials.password
287            com_session.findById("wnd[0]/usr/txtRSYST-LANGU").text = credentials.language
288
289            self._logger("SAP credentials injected successfully.", False)
290        except Exception as exc:
291            raise SAPConnectionException(
292                f"Failed to inject SAP credentials: {exc}",
293                critical=True,
294            ) from exc