chore: migrate ansys-tools-path -> ansys-tools-common (#4307)

* chore: migrate ansys-tools-path -> ansys-tools-common

Update dependency, imports, docs, links, and tests to use ansys-tools-common
(ansys.tools.common.path) instead of ansys-tools-path. Add _HAS_ATC feature
flag and provide a backward-compatible _HAS_ATP alias. Adjust CLI/help text,
sphinx intersphinx mapping, workflow comment, and numerous test patches to
reflect the new package name.

* chore: adding changelog file 4307.maintenance.md [dependabot-skip]

* Update src/ansys/mapdl/core/report.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/workflows/test-local.yml

@@ -250,7 +250,7 @@ jobs:
           echo "ON_UBUNTU: $ON_UBUNTU"
           echo "ON_STUDENT: $ON_STUDENT"
 
-          # Because there is no 'ansys-tools-path' we need to input the
+          # Because there is no 'ansys-tools-common' we need to input the
           # executable path with the env var: PYMAPDL_MAPDL_EXEC.
 
           if [[ "${MAPDL_VERSION}" == *"latest-ubuntu"* ]] ; then

doc/changelog.d/4307.maintenance.md

@@ -0,0 +1 @@
+Migrate ansys-tools-path -> ansys-tools-common

doc/source/api/launcher.rst

@@ -4,7 +4,7 @@ Launcher
 ========
 Various PyMAPDL specific launcher commands.
 Most of these commands are called from the
-library `ansys-tools-path <ansys_tools_path_>`_.
+library `ansys-tools-common.path <ansys_tools_common_>`_.
 
 .. currentmodule:: ansys.mapdl.core.launcher
 
@@ -18,10 +18,10 @@ library `ansys-tools-path <ansys_tools_path_>`_.
    close_all_local_instances
 
 
-``ansys-tools-path`` functions
-------------------------------
+``ansys-tools-common.path`` functions
+--------------------------------------
 
-.. currentmodule:: ansys.tools.path
+.. currentmodule:: ansys.tools.common.path
 
 .. autosummary::
    :toctree: _autosummary

doc/source/conf.py

@@ -125,7 +125,7 @@
     "pypim": ("https://pypim.docs.pyansys.com/version/dev/", None),
     "ansys-dpf-core": ("https://dpf.docs.pyansys.com/version/stable/", None),
     "ansys-math-core": ("https://math.docs.pyansys.com/version/stable/", None),
-    "ansys-tools-path": ("https://path.tools.docs.pyansys.com/version/stable/", None),
+    "ansys-tools-common": ("https://tools.docs.pyansys.com/version/stable/", None),
     "pytwin": ("https://twin.docs.pyansys.com/version/stable/", None),
 }
 

doc/source/links.rst

@@ -14,7 +14,7 @@
 .. _dpf_post_docs: https://post.docs.pyansys.com
 .. _legacy_reader_docs: https://reader.docs.pyansys.com/
 .. _example_data_repo: https://github.com/ansys/example-data
-.. _ansys_tools_path: http://path.tools.docs.pyansys.com/
+.. _ansys_tools_path: https://tools.docs.pyansys.com/version/stable/user_guide/ansys_tools_path.html
 .. _pyansys_math: https://math.docs.pyansys.com/version/stable/
 .. _pyansys_math_api: https://math.docs.pyansys.com/version/stable/api/index.html
 .. _pytwin_docs: https://twin.docs.pyansys.com

doc/source/user_guide/troubleshoot.rst

@@ -725,7 +725,7 @@ If you want to see which Ansys installations PyMAPDL has detected, use:
 
 Student versions are provided as **negative** versions because the Python dictionary
 does not accept two equal keys. The result of the
-:func:`get_available_ansys_installations() <ansys.tools.path.get_available_ansys_installations>`
+:func:`get_available_ansys_installations() <ansys.tools.common.path.get_available_ansys_installations>`
 method lists higher versions first and student versions last.
 
 .. warning::

pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
   "ansys-mapdl-reader>=0.51.7",
   "ansys-math-core>=0.1.2",
   "ansys-platform-instancemanagement~=1.0",
-  "ansys-tools-path>=0.3.1",
+  "ansys-tools-common>=0.2.1",
   "click>=8.1.3",                              # for CLI interface
   "grpcio>=1.30.0",                            # tested up to grpcio==1.35
   "numpy>=1.14.0,<3.0.0",

src/ansys/mapdl/core/__init__.py

@@ -27,7 +27,6 @@
 import logging
 import os
 from typing import Dict, List, Tuple
-from warnings import warn
 
 from platformdirs import user_data_dir
 
@@ -64,7 +63,8 @@
 MINIMUM_PYTHON_VERSION: Tuple[int, int] = (3, 10)
 
 # Import related globals
-_HAS_ATP: bool = is_installed("ansys.tools.path")
+_HAS_ATC: bool = is_installed("ansys.tools.common")
+_HAS_ATP: bool = _HAS_ATC  # Backward compatibility alias
 _HAS_CLICK: bool = is_installed("click")
 _HAS_DPF: bool = is_installed("ansys.dpf.core")
 _HAS_MATPLOTLIB: bool = is_installed("matplotlib")
@@ -128,8 +128,8 @@
 # ==================
 #
 # For compatibility with other versions or for convenience
-if _HAS_ATP:
-    from ansys.tools.path.path import (
+if _HAS_ATC:
+    from ansys.tools.common.path import (
         change_default_ansys_path,
         find_mapdl,
         get_available_ansys_installations,

src/ansys/mapdl/core/cli/start.py

@@ -165,7 +165,7 @@
     "--version",
     default=None,
     type=str,
-    help="Version of MAPDL to launch. If ``None``, the latest version is used. Versions can be provided as integers (i.e. ``version=222``) or floats (i.e. ``version=22.2``). To retrieve the available installed versions, use the function :meth:`ansys.tools.path.path.get_available_ansys_installations`.",
+    help="Version of MAPDL to launch. If ``None``, the latest version is used. Versions can be provided as integers (i.e. ``version=222``) or floats (i.e. ``version=22.2``). To retrieve the available installed versions, use the function :meth:`ansys.tools.common.path.get_available_ansys_installations`.",
 )
 def start(
     exec_file: str,

src/ansys/mapdl/core/launcher.py

@@ -52,7 +52,7 @@
 import psutil
 
 from ansys.mapdl import core as pymapdl
-from ansys.mapdl.core import _HAS_ATP, _HAS_PIM, LOG  # type: ignore
+from ansys.mapdl.core import _HAS_ATC, _HAS_PIM, LOG  # type: ignore
 from ansys.mapdl.core._version import SUPPORTED_ANSYS_VERSIONS
 from ansys.mapdl.core.errors import (
     LockFileException,
@@ -77,8 +77,8 @@
 if _HAS_PIM:
     import ansys.platform.instancemanagement as pypim  # type: ignore
 
-if _HAS_ATP:
-    from ansys.tools.path import version_from_path as _version_from_path
+if _HAS_ATC:
+    from ansys.tools.common.path import version_from_path as _version_from_path
 
     @wraps(_version_from_path)
     def version_from_path(*args: Any, **kwargs: Any) -> int | None:
@@ -919,7 +919,7 @@ def get_default_ansys() -> Union[Tuple[str, float], Tuple[Literal[""], Literal["
     >>> get_default_ansys()
     (/usr/ansys_inc/v211/ansys/bin/ansys211, 21.1)
     """
-    from ansys.tools.path import find_mapdl
+    from ansys.tools.common.path import find_mapdl
 
     return find_mapdl(supported_versions=SUPPORTED_ANSYS_VERSIONS)
 
@@ -976,11 +976,11 @@ def get_default_ansys_version():
 
 def check_valid_ansys() -> bool:
     """Checks if a valid version of ANSYS is installed and preconfigured"""
-    if not _HAS_ATP:
+    if not _HAS_ATC:
         raise ModuleNotFoundError(
-            "The package 'ansys-tools-path' is required to use this function."
+            "The package 'ansys-tools-common' is required to use this function."
         )
-    from ansys.tools.path import get_mapdl_path
+    from ansys.tools.common.path import get_mapdl_path
 
     ansys_bin = get_mapdl_path(allow_input=False)  # type: ignore
     if ansys_bin is not None:
@@ -1041,11 +1041,11 @@ def set_MPI_additional_switches(
 
     # known issues with distributed memory parallel (DMP)
     if os.name == "nt" and "smp" not in add_sw_lower_case:  # pragma: no cover
-        if _HAS_ATP:
+        if _HAS_ATC:
             condition = not force_intel and version and (222 > version >= 210)
         else:
             warnings.warn(
-                "Because 'ansys-tools-path' is not installed, PyMAPDL cannot check\n"
+                "Because 'ansys-tools-common' is not installed, PyMAPDL cannot check\n"
                 "if this Ansys version requires the MPI fix, so if you are on Windows,\n"
                 "the fix is applied by default.\n"
                 "Use 'force_intel=True' to not apply the fix."
@@ -1388,7 +1388,7 @@ def launch_mapdl(
         Versions can be provided as integers (i.e. ``version=222``) or floats
         (i.e. ``version=22.2``).
         To retrieve the available installed versions, use the function
-        :func:`ansys.tools.path.get_available_ansys_installations`.
+        :func:`ansys.tools.common.path.get_available_ansys_installations`.
         You can also provide this value through the environment variable
         :envvar:`PYMAPDL_MAPDL_VERSION`. For instance:
 
@@ -2457,7 +2457,7 @@ def get_version(
 
     if not version:
         # verify version
-        if exec_file and _HAS_ATP:
+        if exec_file and _HAS_ATC:
             version = version_from_path("mapdl", exec_file, launch_on_hpc=launch_on_hpc)
             if version and version < 202:
                 raise VersionError(
@@ -2571,7 +2571,7 @@ def get_exec_file(args: Dict[str, Any]) -> None:
     Raises
     ------
     ModuleNotFoundError
-        'ansys-tools-path' library could not be found
+        'ansys-tools-common' library could not be found
     FileNotFoundError
         Invalid exec_file path or cannot load cached MAPDL path.
     FileNotFoundError
@@ -2585,13 +2585,13 @@ def get_exec_file(args: Dict[str, Any]) -> None:
         return
 
     if args["exec_file"] is None:
-        if not _HAS_ATP:
+        if not _HAS_ATC:
             raise ModuleNotFoundError(
-                "If you don't have 'ansys-tools-path' library installed, you need "
+                "If you don't have 'ansys-tools-common' library installed, you need "
                 "to input the executable path ('exec_file' argument) or use the "
                 "'PYMAPDL_MAPDL_EXEC' environment variable."
             )
-        from ansys.tools.path import get_mapdl_path
+        from ansys.tools.common.path import get_mapdl_path
 
         if args.get("_debug_no_launch", False):
             args["exec_file"] = ""