refactor: annotate pymapdl part 1 (#3569)

* refactor: annotating version file

* refactor: annotate __init__

* refactor: annotate commands.py

* refactor: annotate common_grpc.py

* refactor: annotate components.py

* refactor: annotating convert.py

* refactor: annotating errors.py

* refactor: annotate information.py

* refactor: annotate cli files

* refactor: annotate examples module

* chore: explain better a variable comment

* refactor: annotate inline_functions

* refactor: annotate jupyter.py

* refactor: annotate krylov

* fix: missing imports

* chore: adding changelog file 3569.added.md [dependabot-skip]

* chore: update src/ansys/mapdl/core/cli/stop.py

Co-authored-by: Camille <[email protected]>

* fix: missing import

* feat: add missing import

* fix: requests import

* fix: missing import

* fix: missing imports and wrong literal

* fix: test_detach_examples_submodule

* fix: pandas

* test: testing examples

* fix: add missing import

* feat: fix pandas warning in docs. Also remove non-used function and adding _HAS_PANDAS to globals

* fix: import

* fix: import

* ci: auto fixes from pre-commit.com hooks.

for more information, see https://pre-commit.ci

---------

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Camille <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

doc/changelog.d/3569.added.md

@@ -0,0 +1 @@
+refactor: annotate pymapdl part 1

src/ansys/mapdl/core/__init__.py

@@ -20,8 +20,6 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-import importlib.metadata as importlib_metadata
-
 ###############################################################################
 # Imports
 # =======
@@ -40,17 +38,16 @@
 #
 from ansys.mapdl.core.logging import Logger
 
-LOG = Logger(level=logging.ERROR, to_file=False, to_stdout=True)
+LOG: Logger = Logger(level=logging.ERROR, to_file=False, to_stdout=True)
 LOG.debug("Loaded logging module as LOG")
 
 ###############################################################################
 # Globals
 # =======
 #
+from ansys.mapdl.core._version import __version__
 from ansys.mapdl.core.helpers import is_installed, run_every_import, run_first_time
 
-__version__: str = importlib_metadata.version(__name__.replace(".", "-"))
-
 # A dictionary relating PyMAPDL server versions with the unified install ones
 VERSION_MAP: Dict[Tuple[int, int, int], str] = {
     (0, 0, 0): "2020R2",
@@ -69,17 +66,21 @@
 
 # Import related globals
 _HAS_ATP: bool = is_installed("ansys.tools.path")
+_HAS_CLICK: bool = is_installed("click")
 _HAS_PIM: bool = is_installed("ansys.platform.instancemanagement")
+_HAS_PANDAS: bool = is_installed("pandas")
 _HAS_PYANSYS_REPORT: bool = is_installed("ansys.tools.report")
 _HAS_PYVISTA: bool = is_installed("pyvista")
+_HAS_REQUESTS: bool = is_installed("requests")
 _HAS_TQDM: bool = is_installed("tqdm")
 _HAS_VISUALIZER: bool = is_installed("ansys.tools.visualization_interface")
 
+
 # Setup directories
 USER_DATA_PATH: str = user_data_dir(appname="ansys_mapdl_core", appauthor="Ansys")
-EXAMPLES_PATH = os.path.join(USER_DATA_PATH, "examples")
+EXAMPLES_PATH: str = os.path.join(USER_DATA_PATH, "examples")
 
-# Store local ports
+# Store ports occupied by local instances
 _LOCAL_PORTS: List[int] = []
 
 ###############################################################################

src/ansys/mapdl/core/_version.py

@@ -29,18 +29,15 @@
 version_info = 0, 58, 'dev0'
 
 """
-
-try:
-    import importlib.metadata as importlib_metadata
-except ModuleNotFoundError:  # pragma: no cover
-    import importlib_metadata
+import importlib.metadata as importlib_metadata
+from typing import Dict
 
 # Read from the pyproject.toml
 # major, minor, patch
-__version__ = importlib_metadata.version("ansys-mapdl-core")
+__version__: str = importlib_metadata.version("ansys-mapdl-core")
 
 # In descending order
-SUPPORTED_ANSYS_VERSIONS = {
+SUPPORTED_ANSYS_VERSIONS: Dict[int, str] = {
     252: "2025R2",
     251: "2025R1",
     242: "2024R2",

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

@@ -20,22 +20,16 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-try:
-    import click
-
-    _HAS_CLICK = True
-
-except ModuleNotFoundError:
-    _HAS_CLICK = False
-
+from ansys.mapdl.core import _HAS_CLICK
 
 if _HAS_CLICK:
     ###################################
     # PyMAPDL CLI
+    import click
 
     @click.group(invoke_without_command=True)
     @click.pass_context
-    def main(ctx):
+    def main(ctx: click.Context):
         pass
 
     from ansys.mapdl.core.cli.convert import convert

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

@@ -21,13 +21,14 @@
 # SOFTWARE.
 
 import os
+from typing import Any, List
 
 import click
 
-_USING_PIPE = [False]
+_USING_PIPE: List[bool] = [False]
 
 
-def get_input_source(ctx, param, value):
+def get_input_source(ctx: click.Context, param: Any, value: Any):
     if not value and not click.get_text_stream("stdin").isatty():
         _USING_PIPE[0] = True
         return click.get_text_stream("stdin").read().strip()
@@ -180,7 +181,7 @@ def convert(
     use_vtk: bool,
     clear_at_start: bool,
     check_parameter_names: bool,
-):
+) -> None:
     """Convert MAPDL code to PyMAPDL"""
     from ansys.mapdl.core.convert import convert_apdl_block, convert_script
 

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

@@ -65,7 +65,7 @@
     default=False,
     help="Print running location info.",
 )
-def list_instances(instances, long, cmd, location):
+def list_instances(instances, long, cmd, location) -> None:
     import psutil
     from tabulate import tabulate
 

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

@@ -191,7 +191,7 @@ def start(
     add_env_vars: Dict[str, str],  # ignored
     replace_env_vars: Dict[str, str],  # ignored
     version: Union[int, str],
-):
+) -> None:
     from ansys.mapdl.core.launcher import launch_mapdl
 
     if mode:

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

@@ -20,6 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+from typing import Optional
+
 import click
 
 
@@ -49,7 +51,21 @@
     default=False,
     help="Kill all MAPDL instances",
 )
-def stop(port, pid, all):
+def stop(port: int, pid: Optional[int], all: bool) -> None:
+    """Stop MAPDL instances running on a given port or with a given process id (PID).
+
+    This command stops MAPDL instances running on a given port or with a given process id (PID).
+    By default, it stops instances running on the port 50052.
+
+    Parameters
+    ----------
+    port : int
+        Port where the MAPDL instance is running.
+    pid : Optional[int]
+        PID of the MAPDL instance
+    all : bool
+        If :class:`True`, kill all the instances regardless their port or PID.
+    """
     import psutil
 
     from ansys.mapdl.core.launcher import is_ansys_process