feat: Move ansys-tools-path

.github/workflows/cicd.yml

@@ -39,9 +39,15 @@ jobs:
             operating-system: ${{ matrix.os }}
             python-version: ${{ matrix.python-version }}
             whitelist-license-check: "termcolor"  # Has MIT license, but it's not recognized
-    tests:
-      name: Run tests
+
+    build-tests:
+      name: Build and Testing
       runs-on: ubuntu-latest
+      needs: [smoke-tests]
+      env:
+        ANSYS_LOCAL: false
+        ON_UBUNTU: true
+
       steps:
         - name: Run tests
           uses: ansys/actions/tests-pytest@v10

.github/workflows/run_mapdl_tests.yml

@@ -0,0 +1,46 @@
+name: MAPDL dependent tests for paths tool
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+    branches:
+      - main
+
+env:
+    PACKAGE_NAME: ansys-tools-common
+    MAIN_PYTHON_VERSION: 3.13
+
+jobs:
+  build-tests:
+    name: Build and Testing
+    runs-on: ubuntu-22.04
+    container:
+        image: ghcr.io/ansys/pymapdl/mapdl:v22.2-ubuntu
+        options: "-u=0:0 --entrypoint /bin/bash"
+        credentials:
+            username: ${{ secrets.GH_USERNAME }}
+            password: ${{ secrets.GH_TOKEN }}
+    env:
+        ANSYS_LOCAL: true
+        ON_UBUNTU: true
+
+    steps:
+        - uses: actions/checkout@v4
+        - name: Setup Python
+          uses: actions/setup-python@v5
+          with:
+            python-version: ${{ env.MAIN_PYTHON_VERSION }}
+        - name: Install library, with test extra
+          run: python -m pip install .[tests]
+
+        - name: Unit testing
+          run: |
+            python -m pytest -vx --cov=${{ env.PACKAGE_NAMESPACE }} --cov-report=term --cov-report=xml:.cov/coverage.xml --cov-report=html:.cov/html
+
+        - name: Upload coverage reports to Codecov
+          uses: codecov/codecov-action@v5
+          with:
+            files: .cov/coverage.xml

doc/source/user_guide/ansys_downloader.rst

@@ -6,7 +6,7 @@ Ansys example downloader
 You can use any of the functions available in the
 to identify the path of the local Ansys installation.
 
-For example you can use :func:`find_ansys <ansys.tools.path.find_ansys>`
+For example you can use :func:`find_ansys <ansys.tools.common.path.find_ansys>`
 to locate the path of the latest Ansys installation available:
 
 .. code:: pycon

doc/source/user_guide/ansys_tools_path.rst

@@ -11,11 +11,11 @@ How to use
 You can use any of the functions available in the
 to identify the path of the local Ansys installation.
 
-For example you can use :func:`find_ansys <ansys.tools.path.find_ansys>`
+For example you can use :func:`find_ansys <ansys.tools.common.path.find_ansys>`
 to locate the path of the latest Ansys installation available:
 
 .. code:: pycon
 
-   >>> from ansys.tools.path import find_ansys
+   >>> from ansys.tools.common.path import find_ansys
    >>> find_ansys()
    'C:/Program Files/ANSYS Inc/v211/ANSYS/bin/winx64/ansys211.exe', 21.1

pyproject.toml

@@ -22,7 +22,10 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
-dependencies = []
+dependencies = [
+    "platformdirs>=3.6.0",
+    "click>=8.1.3",        # for CLI interface
+]
 
 [project.optional-dependencies]
 all = [
@@ -40,6 +43,8 @@ filetransfer = [
 
 tests = [
     "pytest==8.4.0",
+    "pytest-cov==6.1.1",
+    "pyfakefs==5.8.0",
     "hypothesis==6.135.10",
     "grpcio==1.73.0",
 ]
@@ -54,6 +59,9 @@ doc = [
     "sphinx-jinja==2.0.2",
 ]
 
+[project.scripts]
+save-ansys-path = "ansys.tools.common.path.save:cli"
+
 [project.urls]
 Source = "https://github.com/ansys/ansys-tools-common"
 Issues = "https://github.com/ansys/ansys-tools-common/issues"

src/ansys/tools/common/path/__init__.py

@@ -0,0 +1,81 @@
+# 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.
+
+"""
+Tools to find/cache installed Ansys products.
+
+WARNING: This is not concurrent-safe (multiple python processes might race on this data.)
+"""
+
+from ansys.tools.common.path.path import (
+    LOG,
+    SETTINGS_DIR,
+    SUPPORTED_ANSYS_VERSIONS,
+    change_default_ansys_path,  # deprecated
+    change_default_dyna_path,
+    change_default_mapdl_path,
+    change_default_mechanical_path,
+    clear_configuration,
+    find_ansys,  # deprecated
+    find_dyna,
+    find_mapdl,
+    find_mechanical,
+    get_ansys_path,  # deprecated
+    get_available_ansys_installations,
+    get_dyna_path,
+    get_latest_ansys_installation,
+    get_mapdl_path,
+    get_mechanical_path,
+    get_saved_application_path,
+    save_ansys_path,  # deprecated
+    save_dyna_path,
+    save_mapdl_path,
+    save_mechanical_path,
+    version_from_path,
+)
+
+__all__ = [
+    "LOG",
+    "SETTINGS_DIR",
+    "SUPPORTED_ANSYS_VERSIONS",
+    "change_default_mapdl_path",
+    "change_default_mechanical_path",
+    "change_default_dyna_path",
+    "clear_configuration",
+    "find_mapdl",
+    "find_mechanical",
+    "find_dyna",
+    "get_available_ansys_installations",
+    "get_latest_ansys_installation",
+    "get_mapdl_path",
+    "get_mechanical_path",
+    "get_saved_application_path",
+    "get_dyna_path",
+    "save_mapdl_path",
+    "save_mechanical_path",
+    "save_dyna_path",
+    "version_from_path",
+    "change_default_ansys_path",
+    "find_ansys",
+    "get_ansys_path",
+    "save_ansys_path",
+]

src/ansys/tools/common/path/applications/__init__.py

@@ -0,0 +1,49 @@
+# 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.
+
+"""
+Application plugin for ansys-tools-path.
+
+This defines the interface of a plugin, which is implemented using a module.
+"""
+
+# TODO - consider using pluggy?
+# TODO: Remove?
+
+
+class ApplicationPlugin:
+    """Class for application plugins."""
+
+    def is_valid_executable_path(self, exe_loc: str) -> bool:
+        r"""Check if the executable path is valid for the application.
+
+        Parameters
+        ----------
+        exe_loc : str
+            The path to the executable file.
+
+        Returns
+        -------
+        bool
+            ``True`` if the path is valid for the application, ``False`` otherwise.
+        """
+        raise Exception("This is just a base class.")

src/ansys/tools/common/path/applications/dyna.py

@@ -0,0 +1,41 @@
+# 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.
+
+"""dyna-specific logic for ansys-tools-path."""
+
+
+# TODO: Remove?
+def is_valid_executable_path(exe_loc: str) -> bool:
+    """Check if the executable path is valid for Ansys Dyna.
+
+    Parameters
+    ----------
+    exe_loc : str
+        The path to the executable file.
+
+    Returns
+    -------
+    bool
+        ``True`` if the path is valid for Ansys Dyna, ``False`` otherwise.
+    """
+    # dyna paths can be anything
+    return True

src/ansys/tools/common/path/applications/mapdl.py

@@ -0,0 +1,43 @@
+# 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.
+
+"""MAPDL-specific logic for ansys-tools-path."""
+
+from pathlib import Path
+import re
+
+
+def is_valid_executable_path(exe_loc: str) -> bool:
+    """Check if the executable path is valid for Ansys MAPDL.
+
+    Parameters
+    ----------
+    exe_loc : str
+        The path to the executable file.
+
+    Returns
+    -------
+    bool
+        ``True`` if the path is valid for Ansys MAPDL, ``False`` otherwise.
+    """
+    path = Path(exe_loc)
+    return path.is_file() and re.search(r"ansys\d{3}", path.name) is not None

src/ansys/tools/common/path/applications/mechanical.py

@@ -0,0 +1,46 @@
+# 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.
+
+"""Mechanical-specific logic for ansys-tools-path."""
+
+import os
+from pathlib import Path
+import re
+
+
+def is_valid_executable_path(exe_loc: str) -> bool:
+    """Check if the executable path is valid for Ansys Mechanical.
+
+    Parameters
+    ----------
+    exe_loc : str
+        The path to the executable file.
+
+    Returns
+    -------
+    bool
+        ``True`` if the path is valid for Ansys Mechanical, ``False`` otherwise.
+    """
+    path = Path(exe_loc)
+    if os.name == "nt":  # pragma: no cover
+        return path.is_file() and re.search("AnsysWBU.exe", path.name, re.IGNORECASE) is not None
+    return path.is_file() and re.search(r"\.workbench$", path.name) is not None