fix: make type annotations runtime-safe for bear-type compatibility

doc/changelog.d/4973.fixed.md

@@ -0,0 +1 @@
+Make type annotations runtime-safe for bear-type compatibility

pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
 dependencies = [
     "ansys-api-fluent>=0.3.37",
     "ansys-platform-instancemanagement~=1.1",
+    "beartype>=0.18.0",
     "ansys-tools-common>=0.4.0",
     "ansys-tools-filetransfer>=0.2,<1.0",
     "ansys-units~=0.10.0",

src/ansys/fluent/core/__init__.py

@@ -22,6 +22,13 @@
 
 """A package providing Fluent's Solver and Meshing capabilities in Python."""
 
+# NOTE: beartype_this_package() is intentionally NOT used here.
+# `ansys` and `ansys.fluent` are implicit PEP 420 namespace packages
+# (no __init__.py at those levels). beartype's package-level hook
+# requires a regular package with __init__.py at the namespace root.
+# The @beartype decorator is applied manually to public API functions instead.
+# Upstream tracking: https://github.com/beartype/beartype/issues/286
+
 import os
 import pydoc
 import warnings

src/ansys/fluent/core/_types.py

@@ -26,10 +26,8 @@
 This module centralizes reusable typing constructs
 """
 
-from __future__ import annotations
-
 import os
 from typing import TypeAlias
 
-PathType: TypeAlias = "os.PathLike[str] | os.PathLike[bytes] | str | bytes"
+PathType: TypeAlias = os.PathLike[str] | os.PathLike[bytes] | str | bytes
 """Type alias for file system paths."""

src/ansys/fluent/core/codegen/builtin_settingsgen.py

@@ -116,9 +116,11 @@ def generate(version: str):
                 f.write(f", {named_object}: str")
             f.write(", settings_source: SettingsBase | Solver | None = None")
             if kind == "NonCreatableNamedObject":
-                f.write(", name: str = None")
+                f.write(", name: str | None = None")
             elif kind == "CreatableNamedObject":
-                f.write(", name: str = None, new_instance_name: str = None")
+                f.write(
+                    ", name: str | None = None, new_instance_name: str | None = None"
+                )
             f.write("):\n")
             f.write("        super().__init__(settings_source=settings_source")
             if kind == "NonCreatableNamedObject":

src/ansys/fluent/core/examples/downloads.py

@@ -73,7 +73,7 @@ def _get_file_url(file_name: str, directory: str | None = None) -> str:
 def _retrieve_file(
     url: str,
     file_name: str,
-    save_path: "PathType | None" = None,
+    save_path: PathType | None = None,
     return_without_path: bool | None = False,
 ) -> str:
     """Download specified file from specified URL."""
@@ -120,7 +120,7 @@ def _retrieve_file(
 def download_file(
     file_name: str,
     directory: str | None = None,
-    save_path: "PathType | None" = None,
+    save_path: PathType | None = None,
     return_without_path: bool | None = None,
 ) -> str:
     """Download specified example file from the Ansys example data repository.

src/ansys/fluent/core/field_data_interfaces.py

@@ -113,7 +113,7 @@ class BaseFieldInfo(ABC):
 
     @abstractmethod
     def get_scalar_field_range(
-        self, field: str, node_value: bool = False, surface_ids: List[int] = None
+        self, field: str, node_value: bool = False, surface_ids: List[int] | None = None
     ) -> List[float]:
         """
         Retrieve the range (minimum and maximum values) of a scalar field.
@@ -412,14 +412,14 @@ def __init__(self, available_field_names, field_info):
         self._field_info = field_info
 
     def range(
-        self, field: str, node_value: bool = False, surface_ids: list[int] = None
+        self, field: str, node_value: bool = False, surface_ids: list[int] | None = None
     ) -> list[float]:
         """Get the range (minimum and maximum values) of the field.
 
         Parameters
         ----------
         field: str
-            Field name
+            Field namex
         node_value: bool
         surface_ids : List[int], optional
             List of surface IDS for the surface data.

src/ansys/fluent/core/file_session.py

@@ -966,7 +966,7 @@ def __init__(self, file_session):
         self._file_session = file_session
 
     def get_scalar_field_range(
-        self, field: str, node_value: bool = False, surface_ids: List[int] = None
+        self, field: str, node_value: bool = False, surface_ids: List[int] | None = None
     ) -> List[float]:
         """Get the range (minimum and maximum values) of the field.
 
@@ -990,7 +990,7 @@ def get_scalar_field_range(
         return self._get_scalar_field_range(field, node_value, surface_ids)
 
     def _get_scalar_field_range(
-        self, field: str, node_value: bool = False, surface_ids: List[int] = None
+        self, field: str, node_value: bool = False, surface_ids: List[int] | None = None
     ) -> List[float]:
         minimum = None
         maximum = None

src/ansys/fluent/core/filereader/case_file.py

@@ -617,8 +617,8 @@ class CaseFile(RPVarProcessor):
 
     def __init__(
         self,
-        case_file_name: "PathType | None" = None,
-        project_file_name: "PathType | None" = None,
+        case_file_name: PathType | None = None,
+        project_file_name: PathType | None = None,
     ) -> None:
         """Initialize a CaseFile object. Exactly one file path argument must be
         specified.

src/ansys/fluent/core/fluent_connection.py

@@ -22,8 +22,6 @@
 
 """Provides a module for Fluent connection functionality."""
 
-from __future__ import annotations
-
 from contextlib import suppress
 import ctypes
 from ctypes import c_int, sizeof

src/ansys/fluent/core/launcher/launcher.py

@@ -29,9 +29,11 @@
 import inspect
 import logging
 import os
-from typing import Any, Dict
+from typing import Any
 from warnings import warn
 
+from beartype import beartype
+
 from ansys.fluent.core._types import PathType
 from ansys.fluent.core.exceptions import DisallowedValuesError
 from ansys.fluent.core.fluent_connection import FluentConnection
@@ -77,8 +79,9 @@
 logger = logging.getLogger("pyfluent.launcher")
 
 
+@beartype
 def create_launcher(
-    fluent_launch_mode: LaunchMode = LaunchMode.STANDALONE, **kwargs
+    fluent_launch_mode: LaunchMode = LaunchMode.STANDALONE, **kwargs: Any
 ) -> DockerLauncher | PIMLauncher | SlurmLauncher | StandaloneLauncher:
     """Use the factory function to create a launcher for supported launch modes.
 
@@ -170,15 +173,16 @@ def _custom_converter_dimension(kwargs):
     version="v0.22.0",
     converter=_custom_converter_dimension,
 )
+@beartype
 def launch_fluent(
     product_version: FluentVersion | str | float | int | None = None,
     dimension: Dimension | int | None = None,
     precision: Precision | str | None = None,
     processor_count: int | None = None,
     journal_file_names: None | str | list[str] = None,
-    start_timeout: int = None,
+    start_timeout: int | None = None,
     additional_arguments: str = "",
-    env: Dict[str, Any] | None = None,
+    env: dict[str, Any] | None = None,
     start_container: bool | None = None,
     container_dict: dict | None = None,
     dry_run: bool = False,
@@ -188,14 +192,14 @@ def launch_fluent(
     graphics_driver: (
         FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str | None
     ) = None,
-    case_file_name: "PathType | None" = None,
-    case_data_file_name: "PathType | None" = None,
+    case_file_name: PathType | None = None,
+    case_data_file_name: PathType | None = None,
     lightweight_mode: bool | None = None,
     mode: FluentMode | str | None = None,
     py: bool | None = None,
     gpu: bool | list[int] | None = None,
-    cwd: "PathType | None" = None,
-    fluent_path: "PathType | None" = None,
+    cwd: PathType | None = None,
+    fluent_path: PathType | None = None,
     topy: str | list | None = None,
     start_watchdog: bool | None = None,
     scheduler_options: dict | None = None,
@@ -410,6 +414,7 @@ def _mode_to_launcher_type(fluent_launch_mode: LaunchMode):
     return launcher()
 
 
+@beartype
 def connect_to_fluent(
     ip: str | None = None,
     port: int | None = None,

src/ansys/fluent/core/launcher/slurm_launcher.py

@@ -321,7 +321,7 @@ def done(self) -> bool:
         return self._get_state() in ["", "CANCELLED", "COMPLETED"]
 
     def result(
-        self, timeout: int = None
+        self, timeout: int | None = None
     ) -> Meshing | PureMeshing | Solver | SolverIcing:
         """Return the session instance corresponding to the Fluent launch. If Fluent
         hasn't yet launched, then this method will wait up to timeout seconds. If Fluent
@@ -345,7 +345,7 @@ def result(
         """
         return self._future.result(timeout)
 
-    def exception(self, timeout: int = None) -> Exception:
+    def exception(self, timeout: int | None = None) -> Exception:
         """Return the exception raised by the Fluent launch. If Fluent hasn't yet
         launched, then this method will wait up to timeout seconds. If Fluent hasn't
         launched in timeout seconds, then a TimeoutError will be raised. If timeout is
@@ -397,13 +397,13 @@ def __init__(
         env: Dict[str, Any] | None = None,
         cleanup_on_exit: bool = True,
         start_transcript: bool = True,
-        case_file_name: "PathType | None" = None,
-        case_data_file_name: "PathType | None" = None,
+        case_file_name: PathType | None = None,
+        case_data_file_name: PathType | None = None,
         lightweight_mode: bool | None = None,
         py: bool | None = None,
         gpu: bool | None = None,
-        cwd: "PathType | None" = None,
-        fluent_path: "PathType | None" = None,
+        cwd: PathType | None = None,
+        fluent_path: PathType | None = None,
         topy: str | list | None = None,
         start_watchdog: bool | None = None,
         scheduler_options: dict | None = None,

src/ansys/fluent/core/launcher/standalone_launcher.py

@@ -40,7 +40,9 @@
 import os
 from pathlib import Path
 import subprocess
-from typing import Any, Dict
+from typing import Any
+
+from beartype import beartype
 
 from ansys.fluent.core._types import PathType
 from ansys.fluent.core.launcher.error_handler import (
@@ -77,12 +79,13 @@
 class StandaloneLauncher:
     """Instantiates Fluent session in standalone mode."""
 
+    @beartype
     def __init__(
         self,
         mode: FluentMode | str | None = None,
         ui_mode: UIMode | str | None = None,
         graphics_driver: (
-            FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str
+            FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str | None
         ) = None,
         product_version: FluentVersion | str | float | int | None = None,
         dimension: Dimension | int | None = None,
@@ -91,17 +94,17 @@ def __init__(
         journal_file_names: None | str | list[str] = None,
         start_timeout: int = 60,
         additional_arguments: str = "",
-        env: Dict[str, Any] | None = None,
+        env: dict[str, Any] | None = None,
         cleanup_on_exit: bool = True,
         dry_run: bool = False,
         start_transcript: bool = True,
-        case_file_name: "PathType | None" = None,
-        case_data_file_name: "PathType | None" = None,
+        case_file_name: PathType | None = None,
+        case_data_file_name: PathType | None = None,
         lightweight_mode: bool | None = None,
         py: bool | None = None,
         gpu: bool | None = None,
-        cwd: "PathType | None" = None,
-        fluent_path: "PathType | None" = None,
+        cwd: PathType | None = None,
+        fluent_path: PathType | None = None,
         topy: str | list | None = None,
         start_watchdog: bool | None = None,
         file_transfer_service: Any | None = None,

src/ansys/fluent/core/meshing/meshing_workflow.py

@@ -23,8 +23,6 @@
 """Meshing workflow specialization of the Workflow module that wraps and extends the
 core functionality."""
 
-from __future__ import annotations
-
 from enum import Enum
 import os
 

src/ansys/fluent/core/meshing/meshing_workflow_new.py

@@ -23,8 +23,6 @@
 """Meshing workflow specialization of the Workflow module that wraps and extends the
 core functionality."""
 
-from __future__ import annotations
-
 from enum import Enum
 import os
 
@@ -271,7 +269,7 @@ def __init__(
         workflow: PyMenuGeneric,
         meshing: PyMenuGeneric,
         fluent_version: FluentVersion,
-        file_path: PathType = None,
+        file_path: PathType | None = None,
         initialize: bool = True,
     ) -> None:
         """Initialize a ``LoadWorkflow`` instance.

src/ansys/fluent/core/search.py

@@ -420,7 +420,7 @@ def _search_whole_word(
     search_string: str,
     match_case: bool = False,
     match_whole_word: bool = True,
-    api_tree_data: dict = None,
+    api_tree_data: dict | None = None,
     api_path: str | None = None,
 ):
     """Perform exact search for a word through the Fluent's object hierarchy.

src/ansys/fluent/core/services/field_data.py

@@ -176,7 +176,7 @@ def __init__(
         self._is_data_valid = is_data_valid
 
     def get_scalar_field_range(
-        self, field: str, node_value: bool = False, surface_ids: List[int] = None
+        self, field: str, node_value: bool = False, surface_ids: List[int] | None = None
     ) -> List[float]:
         """Get the range (minimum and maximum values) of the field.
 
@@ -200,7 +200,7 @@ def get_scalar_field_range(
         return self._get_scalar_field_range(field, node_value, surface_ids)
 
     def _get_scalar_field_range(
-        self, field: str, node_value: bool = False, surface_ids: List[int] = None
+        self, field: str, node_value: bool = False, surface_ids: List[int] | None = None
     ) -> List[float]:
         if not surface_ids:
             surface_ids = []
@@ -1105,7 +1105,7 @@ class ChunkParser:
         field : numpy array
     """
 
-    def __init__(self, callbacks_provider: object = None):
+    def __init__(self, callbacks_provider: object | None = None):
         """__init__ method of ChunkParser class."""
         self._callbacks_provider = callbacks_provider
 

src/ansys/fluent/core/services/scheme_eval.py

@@ -88,7 +88,7 @@ def string_eval(
     def scheme_eval(
         self,
         request: SchemeEvalProtoModule.SchemeEvalRequest,
-        metadata: list[tuple[str, str]] = None,
+        metadata: list[tuple[str, str]] | None = None,
     ) -> SchemeEvalProtoModule.SchemeEvalResponse:
         """SchemeEval RPC of SchemeEval service."""
         new_metadata = self.__metadata