ansys-tools-common 0.2.0__py3-none-any.whl

ansys/tools/common/__init__.py

@@ -0,0 +1,26 @@
+# Copyright (C) 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.
+"""Main module."""
+
+import importlib.metadata as importlib_metadata
+
+__version__ = importlib_metadata.version("ansys-tools-common")

ansys/tools/common/abstractions/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (C) 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.
+"""Initialization module for abstractions."""
+
+from .connection import AbstractGRPCConnection  # noqa F401
+from .launcher import LauncherProtocol  # noqa F401

ansys/tools/common/abstractions/connection.py

@@ -0,0 +1,105 @@
+# Copyright (C) 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.
+"""Module for abstract connection class."""
+
+from abc import ABC, abstractmethod
+
+try:
+    import grpc
+except ImportError:  # pragma: no cover
+    import warnings
+
+    warnings.warn(
+        "grpc module is not available - reach out to the library maintainers to include it into their dependencies"
+    )
+
+
+class AbstractGRPCConnection(ABC):
+    """Abstract class for managing gRPC connections.
+
+    Parameters
+    ----------
+    host : str
+        Host where the gRPC server is running.
+    port : str
+        Port where the gRPC server is listening.
+    """
+
+    @abstractmethod
+    def __init__(self, host: str, port: str) -> None:
+        """Initialize the gRPC connection with host and port."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish a connection to the gRPC server."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def close(self) -> None:
+        """Disconnect from the gRPC server."""
+        pass  # pragma: no cover
+
+    @property
+    @abstractmethod
+    def service(self):
+        """GRPC stub for making requests."""
+        pass  # pragma: no cover
+
+    @property
+    def _host(self) -> str:
+        """Host for the gRPC connection."""
+        return self.__host
+
+    @_host.setter
+    def _host(self, value: str) -> None:
+        """Set the host for the gRPC connection."""
+        self.__host = value
+
+    @property
+    def _port(self) -> str:
+        """Return the port for the gRPC connection."""
+        return self.__port
+
+    @_port.setter
+    def _port(self, value: str) -> None:
+        """Set the port for the gRPC connection."""
+        self.__port = value
+
+    @property
+    def _channel(self, options: list = None) -> grpc.Channel:
+        """Return the gRPC channel."""
+        return grpc.insecure_channel(f"{self._host}:{self._port}", options=options)
+
+    @property
+    def is_closed(self) -> bool:
+        """Flag indicating if the connection is closed.
+
+        Returns
+        -------
+        bool
+            ``True`` if the connection is closed, ``False`` otherwise.
+        """
+        try:
+            return self._channel._connectivity_state != grpc.ChannelConnectivity.READY
+        except grpc.RpcError:
+            return True

ansys/tools/common/abstractions/launcher.py

@@ -0,0 +1,175 @@
+# Copyright (C) 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.
+
+"""Interface definitions for implementing a local product launcher.
+
+A plugin for the local product launcher must implement the :class:`LauncherProtocol` class and register it.
+"""
+
+from enum import Enum, auto
+from typing import Any, ClassVar, Protocol, TypeVar
+
+__all__ = [
+    "DataclassProtocol",
+    "FALLBACK_LAUNCH_MODE_NAME",
+    "LAUNCHER_CONFIG_T",
+    "LauncherProtocol",
+    "METADATA_KEY_DOC",
+    "METADATA_KEY_NOPROMPT",
+    "ServerType",
+]
+
+METADATA_KEY_DOC = "launcher_doc"
+"""Key used in the :py:class:`dataclasses.Field` ``metadata`` for the option description."""
+
+METADATA_KEY_NOPROMPT = "launcher_noprompt"
+"""
+Key used in the :py:class:`dataclasses.Field` ``metadata`` to skip prompting for the option by default.
+"""
+
+FALLBACK_LAUNCH_MODE_NAME = "__fallback__"
+
+
+class DataclassProtocol(Protocol):
+    """Provides the ``Protocol`` class for Python dataclasses."""
+
+    __dataclass_fields__: ClassVar[dict[str, Any]]
+
+
+LAUNCHER_CONFIG_T = TypeVar("LAUNCHER_CONFIG_T", bound=DataclassProtocol)
+# This docstring is commented-out because numpydoc causes the documentation build to fail when
+# it is included.
+# """Type variable for launcher configuration objects."""
+
+
+class ServerType(Enum):
+    """Defines which protocols the server supports.
+
+    The ``ServerType`` class is used as values in the :attr:`LauncherProtocol.SERVER_SPEC`
+    attribute to define the capabilities of the servers started with a given product and launch method.
+    """
+
+    GENERIC = auto()
+    """Generic server, which responds at a given URL and port.
+
+    The generic server type can be used for any server. It does not
+    include information about which protocol should be used.
+    """
+
+    GRPC = auto()
+    """Server that can be accessed via gRPC.
+
+    Servers of this type are accessible via the :attr:`.ProductInstance.channels`
+    attribute.
+    """
+
+
+class LauncherProtocol(Protocol[LAUNCHER_CONFIG_T]):
+    """Provides the interface for managing a local product instance.
+
+    A plugin to the local product launcher must implement the interface defined in this class.
+
+    To check for compatibility, you should derive from this
+    class. For example ``MyLauncher(LauncherProtocol[MyConfigModel])``.
+    Check the resulting code with `Mypy <https://mypy.readthedocs.io>`_.
+
+    The ``__init__`` method should accept exactly one keyword-only
+    parameter: ``config``. Note that this is `not enforced by
+    Mypy <https://bugs.python.org/issue44807>`_.
+
+    Parameters
+    ----------
+    config :
+        Configuration options used to start the product. This parameter must be an instance of ``CONFIG_MODEL``.
+    """
+
+    CONFIG_MODEL: type[LAUNCHER_CONFIG_T]
+    """Defines the configuration options for the launcher.
+
+    The configuration options that this launcher accepts, specified
+    as a :py:func:`dataclass <dataclasses.dataclass>`. Note that
+    the ``default`` and ``metadata[METADATA_KEY_DOC]`` of the
+    fields are used in the configuration CLI, if available.
+    """
+
+    SERVER_SPEC: dict[str, ServerType]
+    """Defines the server types that are started.
+
+    Examples
+    --------
+    This code defines a server that is accessible via a URL
+    at the ``"MAIN"`` key and a server accessible via gRPC
+    at the ``"FILE_TRANSFER"`` key.
+
+    .. code:: python
+
+        SERVER_SPEC = {"MAIN": ServerType.GENERIC, "FILE_TRANSFER": ServerType.GRPC}
+
+    The :attr:`.ProductInstance.urls` attribute then has keys
+    ``{"MAIN", "FILE_TRANSFER"}``, whereas the
+    :attr:`.ProductInstance.channels` attribute has only the
+    key ``"FILE_TRANSFER"``.
+    """
+
+    def __init__(self, *, config: LAUNCHER_CONFIG_T):
+        pass  # pragma: no cover
+
+    def start(self) -> None:
+        """Start the product instance."""
+
+    def stop(self, *, timeout: float | None = None) -> None:
+        """Stop the product instance.
+
+        Parameters
+        ----------
+        timeout :
+            Time after which the instance can be forcefully stopped.
+            The timeout should be interpreted as a hint to the implementation.
+            It is *not required* to trigger a force-shutdown, but the stop *must* return within a finite time.
+        """
+
+    def check(self, *, timeout: float | None = None) -> bool:
+        """Check if the product instance is responding to requests.
+
+        Parameters
+        ----------
+        timeout :
+            Timeout in seconds for the check.
+            The timeout should be interpreted as a hint to the implementation.
+            It is *not required* to return within the given time,
+            but the check *must* return within a finite time,
+            meaning it must not hang indefinitely.
+
+        Returns
+        -------
+        bool
+            Whether the product instance is responding.
+        """
+
+    @property
+    def urls(self) -> dict[str, str]:
+        """Dictionary of URLs that the server is listening on.
+
+        The keys of the returned dictionary must correspond
+        to the keys defined in the
+        :attr:`.LauncherProtocol.SERVER_SPEC` attribute.
+        """

ansys/tools/common/example_download.py

@@ -0,0 +1,213 @@
+# Copyright (C) 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.
+"""Module for downloading examples from the PyAnsys Github ``example-data`` repository."""
+
+from pathlib import Path
+import tempfile
+from threading import Lock
+from typing import Optional
+from urllib.parse import urljoin, urlparse
+
+import requests
+
+__all__ = ["DownloadManager"]
+
+BASE_URL = "https://github.com/ansys/example-data/raw/main"
+
+
+class DownloadManagerMeta(type):
+    """Provides a thread-safe implementation of ``Singleton``.
+
+    https://refactoring.guru/design-patterns/singleton/python/example#example-1.
+    """
+
+    _instances = {}
+    _lock: Lock = Lock()
+
+    def __call__(cls, *args, **kwargs):
+        """Call to the class."""
+        with cls._lock:
+            if cls not in cls._instances:
+                instance = super().__call__(*args, **kwargs)
+                cls._instances[cls] = instance
+        return cls._instances[cls]
+
+
+class DownloadManager(metaclass=DownloadManagerMeta):
+    """Manages downloads of example files.
+
+    Manages the download of example from the ``example-data``
+    repository, which is at https://github.com/ansys/example-data.
+    """
+
+    def __init__(self):
+        """Initialize the download manager."""
+        self._downloads_list = []
+
+    def clear_download_cache(self):
+        """Remove downloaded example files from the local path."""
+        for file in self._downloads_list:
+            Path(file).unlink()
+        self._downloads_list.clear()
+
+    def download_file(
+        self, filename: str, directory: str, destination: Optional[str] = None, force: bool = False
+    ) -> str:
+        """Download an example file from the ``example-data`` repository.
+
+        Parameters
+        ----------
+        filename : str
+            Name of the example file to download.
+        directory : str
+            Path under the ``example-data`` repository.
+        destination : str, default: None
+            Path to download the example file to. The default
+            is ``None``, in which case the default path for app data
+            is used.
+        force : bool, default: False
+            Whether to always download the example file. The default is
+            ``False``, in which case if the example file is cached, it
+            is reused.
+
+        Returns
+        -------
+        tuple[str, str]
+            Tuple containing the filepath to use and the local
+            filepath of the downloaded directory. The two are
+            different in case of containers.
+        """
+        # Convert to Path object
+        destination_path = Path(destination) if destination is not None else None
+
+        # If destination is not a dir, create it
+        if destination_path is not None and not destination_path.exists():
+            destination_path.mkdir(parents=True, exist_ok=True)
+
+        # Check if it was able to create the dir, very rare case
+        if destination_path is not None and not destination_path.is_dir():
+            raise ValueError("Destination directory provided does not exist.")  # pragma: no cover
+
+        url = self._get_filepath_on_default_server(filename, directory)
+        local_path = self._retrieve_data(url, filename, dest=destination, force=force)
+
+        # add path to downloaded files
+        self._add_file(local_path)
+        return local_path
+
+    def _add_file(self, file_path: str):
+        """Add the path for a downloaded example file to a list.
+
+        This list keeps track of where example files are
+        downloaded so that a global cleanup of these files can be
+        performed when the client is closed.
+
+        Parameters
+        ----------
+        file_path : str
+            Local path of the downloaded example file.
+        """
+        if file_path not in self._downloads_list:
+            self._downloads_list.append(file_path)
+
+    def _joinurl(self, base: str, directory: str) -> str:
+        """Join multiple paths to a base URL.
+
+        Parameters
+        ----------
+        base : str
+            Base URL to append the directory path to.
+            If this URL doesn't end with '/', then it is added automatically.
+        directory : str
+            Directory path to append to the base URL.
+
+        Returns
+        -------
+        str
+            Joined URL with the base and paths.
+        """
+        if base[-1] != "/":
+            base += "/"
+        return urljoin(base, directory)
+
+    def _get_filepath_on_default_server(self, filename: str, directory: str = None) -> str:
+        """Get the full URL of the file on the default repository.
+
+        Parameters
+        ----------
+        filename : str
+            Name of the file to download.
+        directory : str, default: None
+            Path under the ``example-data`` repository.
+
+        Returns
+        -------
+        str
+            Full URL of the file on the default repository.
+        """
+        if directory:
+            if directory[-1] != "/":
+                directory += "/"
+            return self._joinurl(BASE_URL, directory + filename)
+        else:
+            return self._joinurl(BASE_URL, filename)
+
+    def _retrieve_data(self, url: str, filename: str, dest: str = None, force: bool = False) -> str:
+        """Retrieve data from a URL and save it to a local file.
+
+        Parameters
+        ----------
+        url : str
+            URL to download the file from.
+        filename : str
+            Name of the file to save the downloaded content as.
+        dest : str, default: None
+            Destination path of the file.
+        force : bool, default: False
+            Whether to force downloading to avoid cached examples.
+
+        Returns
+        -------
+        str
+            Local path where the file was saved.
+        """
+        if dest is None:
+            dest = tempfile.gettempdir()
+        local_path = Path(dest) / Path(filename).name
+
+        if not force and local_path.is_file():
+            return str(local_path)
+
+        parsed_url = urlparse(url)
+        if parsed_url.scheme not in ("http", "https"):
+            raise ValueError(f"Unsafe URL scheme: {parsed_url.scheme}")
+
+        response = requests.get(url, timeout=60)
+        response.raise_for_status()
+
+        Path(local_path).write_bytes(response.content)
+
+        return str(local_path)
+
+
+# Create a singleton instance of DownloadManager
+download_manager = DownloadManager()

ansys/tools/common/exceptions.py

@@ -0,0 +1,136 @@
+# Copyright (C) 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.
+"""Exceptions module."""
+
+
+class AnsysError(Exception):
+    """Base class for all exceptions raised by the Ansys API.
+
+    You can use this base class to catch all Ansys-related exceptions.
+    """
+
+    def __init__(self, message: str) -> None:
+        """Initialize the exception with a message."""
+        super().__init__(message)
+        self.message = message
+
+
+class ProductInstanceError(AnsysError):
+    """Custom exception for ProductInstance lifecycle errors."""
+
+
+class AnsysHostnameValueError(AnsysError):
+    """Error raised when hostname value is not valid."""
+
+    def __init__(self, msg):
+        """Initialize the exception.
+
+        Parameters
+        ----------
+        msg : str
+            The message to be raised for the exception.
+
+        """
+        super().__init__(msg)
+
+
+class AnsysPortValueError(AnsysError):
+    """Error raised when port value is not valid."""
+
+    def __init__(self, msg):
+        """Initialize the exception.
+
+        Parameters
+        ----------
+        msg : str
+            The message to be raised for the exception.
+
+        """
+        super().__init__(msg)
+
+
+class AnsysTypeError(AnsysError):
+    """Error raised when an argument is of the wrong type.
+
+    This exception is raised when Python-wise types would work, but internal
+    Ansys-specific typing is not right.
+
+    Parameters
+    ----------
+    expected_type : str | type
+        Expected type of the argument.
+    actual_type : str | type
+        Actual type of the argument.
+    """
+
+    def __init__(self, expected_type: str | type, actual_type: str | type = None) -> None:
+        """Initialize the exception with expected and actual types."""
+        expected_type = expected_type if isinstance(expected_type, str) else expected_type.__name__
+        actual_type = actual_type if isinstance(actual_type, str) else actual_type.__name__
+        message = f"Expected type {expected_type}, but got {actual_type}."
+        super().__init__(message)
+        self.expected_type = expected_type
+        self.actual_type = actual_type
+
+
+class AnsysLogicError(AnsysError):
+    """Exception raised when an unexpected logical condition occurs.
+
+    Parameters
+    ----------
+    message : str
+        Error message.
+    """
+
+    def __init__(self, message: str) -> None:
+        """Initialize the exception with a message."""
+        super().__init__(message)
+
+
+class VersionSyntaxError(AnsysError):
+    """An exception raised when an invalid version syntax is found."""
+
+    def __init__(self, msg):
+        """Initialize the exception.
+
+        Parameters
+        ----------
+        msg : str
+            Message to raise for the exception.
+
+        """
+        super().__init__(msg)
+
+
+class VersionError(AnsysError):
+    """An exception raised when a version is not valid."""
+
+    def __init__(self, msg):
+        """Initialize the exception.
+
+        Parameters
+        ----------
+        msg : str
+            Message to raise for the exception.
+
+        """
+        super().__init__(msg)