fix: Local launcher fixes

Author: AlejandroFernandezLuces

doc/source/conf.py

@@ -123,3 +123,28 @@
 
 # Ignore files
 exclude_patterns = ["changelog/*.md"]
+
+# sphinx gallery options
+sphinx_gallery_conf = {
+    # convert rst to md for ipynb
+    "pypandoc": True,
+    # path to your examples scripts
+    "examples_dirs": ["../../examples"],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["examples"],
+    # Pattern to search for example files
+    "filename_pattern": r"\.py",
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": "FileNameSortKey",
+    # directory where function granular galleries are stored
+    "backreferences_dir": None,
+    # Modules for which function level galleries are created.  In
+    "doc_module": "ansys-tools-common",
+    "promote_jupyter_magic": True,
+    "image_scrapers": ("matplotlib",),
+    "ignore_pattern": r"__init__\.py",
+    "thumbnail_size": (350, 350),
+    "copyfile_regex": r".*\.rst",
+}

examples/local_launcher/example_httpserver_plugin/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "example_httpserver_plugin"
+authors = [{name = "ANSYS, Inc.", email = "[email protected]"}]
+dynamic = ["version", "description"]
+dependencies = ["ansys-tools-local-product-launcher", "requests"]
+
+[project.entry-points."ansys.tools.local_product_launcher.launcher"]
+"example_httpserver.direct" = "example_httpserver_plugin:Launcher"
+"example_httpserver.__fallback__" = "example_httpserver_plugin:Launcher"

examples/local_launcher/example_httpserver_plugin/src/example_httpserver_plugin/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Example plugin for ansys-tools-local-product-launcher."""
+
+from .launcher import Launcher, LauncherConfig
+
+__version__ = "0.1.0"
+__all__ = ["LauncherConfig", "Launcher"]

examples/local_launcher/example_httpserver_plugin/src/example_httpserver_plugin/launcher.py

@@ -0,0 +1,104 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Example launcher plugin, controlling an HTTP server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+import subprocess
+import sys
+
+import requests
+
+from ansys.tools.local_product_launcher.helpers.ports import find_free_ports
+from ansys.tools.local_product_launcher.interface import LauncherProtocol, ServerType
+
+
+# START_LAUNCHER_CONFIG
+@dataclass
+class LauncherConfig:
+    """Defines the configuration options for the HTTP server launcher."""
+
+    directory: str = field(default=os.getcwd())
+
+
+# END_LAUNCHER_CONFIG
+
+
+# START_LAUNCHER_CLS
+class Launcher(LauncherProtocol[LauncherConfig]):
+    """Implements launching an HTTP server."""
+
+    CONFIG_MODEL = LauncherConfig
+    SERVER_SPEC = {"main": ServerType.GENERIC}
+
+    def __init__(self, *, config: LauncherConfig):
+        """Instantiate the HTTP server launcher."""
+        self._config = config
+
+    def start(self) -> None:
+        """Start the HTTP server."""
+        port = find_free_ports()[0]
+        self._url = f"localhost:{port}"
+        self._process = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "http.server",
+                "--directory",
+                self._config.directory,
+                str(port),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+
+    def stop(self, *, timeout: float | None = None) -> None:
+        """Stop the HTTP server."""
+        self._process.terminate()
+        try:
+            self._process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self._process.kill()
+            self._process.wait()
+
+    def check(self, timeout: float | None = None) -> bool:
+        """Check if the server is running."""
+        try:
+            # As a simple check, we try to get the main page from the
+            # server. If it is accessible, we the server is running.
+            # If not, we assume it is not running.
+            requests.get(f"http://{self._url}")
+            return True
+        except requests.RequestException:
+            return False
+
+    @property
+    def urls(self) -> dict[str, str]:
+        """Addresses on which the server is serving content."""
+        return {"main": self._url}
+
+
+# END_LAUNCHER_CLS

examples/local_launcher/example_httpserver_plugin/src/example_httpserver_plugin/py.typed

@@ -0,0 +1,87 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Configure the launcher from the command line
+--------------------------------------------
+
+This example shows how to configure the ``example_httpserver`` plugin from the command line.
+It consists mostly of command-line interactions. With the exception of interactive commands,
+this example can be run when downloaded as a Jupyter notebook. The interactive commands and
+their outputs are simply shown as text.
+
+The configuration contains only a single value, ``directory``, which specifies the
+where the HTTP server is to serve files from.
+
+"""
+
+# %%
+# To see the list of launch modes for the ``example_httpserver`` product, run
+# this code:
+#
+# .. code-block:: bash
+#
+#   %%bash
+#   ansys-launcher configure example_httpserver
+#
+# Here is the output:
+#
+# ::
+#
+#   Usage: ansys-launcher configure example_httpserver [OPTIONS] COMMAND [ARGS]...
+#
+#   Options:
+#   --help  Show this message and exit.
+#
+#   Commands:
+#   direct
+
+# %%
+# Interactive configuration
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# To interactively specify the available configuration options, run
+# this command:
+#
+# .. code-block:: bash
+#
+#   ansys-launcher configure example_httpserver direct
+#
+# The preceding command might result in a session like this:
+#
+# ::
+#
+#   directory:
+#    [<current-working-directory>]: /path/to/directory
+#
+#   Updated /home/<your_username>/.config/ansys_tools_local_product_launcher/config.json
+
+# %%
+# Non-interactive configuration
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# Alternatively, you can specify the configuration fully from the command line (non-interactively):
+#
+# .. code-block:: bash
+#
+#   %%bash
+#   ansys-launcher configure example_httpserver direct --directory /path/to/directory

examples/local_launcher/example_scripts/cli_configure.py

@@ -0,0 +1,14 @@
+Examples
+--------
+
+This section provides examples of how to use the Local Product Launcher to launch a product on
+a local machine. For these examples, the Python's built-in ``http.server`` is the application that is
+launched.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents
+
+    cli_configure
+    py_configure
+    plugin

examples/local_launcher/example_scripts/index.rst

@@ -0,0 +1,55 @@
+Define the HTTP Server launcher plugin
+--------------------------------------
+
+This example shows the launcher plugin that is used to start the Python HTTP server.
+The full source is available in the `examples/example_httpserver_plugin directory <https://github.com/ansys/ansys-tools-local-product-launcher/tree/main/examples/example_httpserver_plugin>`_
+on GitHub.
+
+While this example explains some aspects of the code, for information on how
+to create a plugin for the Local Product Launcher, see :ref:`plugin_creation`.
+
+Launcher code
+~~~~~~~~~~~~~
+
+The ``LauncherConfig`` class determines which options are available to the user when configuring the launcher. It exposes
+a single option ``directory``, which determines which directory the server is to serve files from.
+
+.. include:: ../../../examples/example_httpserver_plugin/src/example_httpserver_plugin/launcher.py
+    :literal:
+    :start-after: # START_LAUNCHER_CONFIG
+    :end-before: # END_LAUNCHER_CONFIG
+
+
+The ``Launcher`` class actually starts the server. It needs to fulfill the interface defined by the
+:class:`.LauncherProtocol` class. Namely, this interface consists of these endpoints:
+
+- The ``start`` and ``stop`` methods for starting and stopping the server.
+- The ``check`` method for checking if the server is running.
+- The ``urls`` property for getting the URLs that the the server is serving requests on.
+
+.. include:: ../../../examples/example_httpserver_plugin/src/example_httpserver_plugin/launcher.py
+    :literal:
+    :start-after: # START_LAUNCHER_CLS
+    :end-before: # END_LAUNCHER_CLS
+
+The local product launcher uses this minimal interface to construct a :class:`.ProductInstance` class,
+which adds some additional functionality on top. For example, the ``ProductInstance`` class automatically
+stops the server when the Python process terminates.
+
+
+Entrypoint configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Besides the launcher code, the plugin must be registered by adding an entrypoint to
+the ``pyproject.toml`` file, as described in :ref:`entrypoint`. In this example,
+``flit`` is used as a build tool. Thus, the ``pyproject.toml`` file looks like this:
+
+.. include:: ../../../examples/example_httpserver_plugin/pyproject.toml
+    :literal:
+
+Two entrypoints for the local product launcher are defined:
+
+- ``direct``: A launch mode that users can configure.
+- ``__fallback__``: A fallback mode that is used if no configuration is available.
+
+Both entrypoints use the same launcher class.