chore: Enable beta features (#4235)

Document beta features access.

Update behavior so that beta features are available but not usable
before switching.

---------

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: prmukherj

doc/changelog.d/4235.maintenance.md

@@ -0,0 +1 @@
+Enable beta features

doc/source/user_guide/beta_feature_access.rst

@@ -0,0 +1,71 @@
+.. _ref_beta_feature_access:
+
+Beta features
+=============
+
+PyFluent provides access to experimental capabilities of Fluent via **beta features**.
+These features are disabled by default and can be enabled at runtime by calling
+the `enable_beta_features()` method on a session object.
+Once activated, the additional beta methods and workflows become available.
+
+Currently, limited number of beta features are available in both **Meshing** and **Solver** sessions.
+
+Meshing Session
+---------------
+
+The **Topology-Based Meshing** workflow is available as a beta feature in meshing mode.
+
+To enable and access it:
+
+.. code-block:: python
+
+  >>> import ansys.fluent.core as pyfluent
+  >>> meshing_session = pyfluent.launch_fluent(mode="meshing")
+
+  >>> # Feature is available before enabling beta features, but unusable and raises 'BetaFeaturesNotEnabled'
+  >>> assert hasattr(meshing_session, "topology_based")
+  >>> assert "topology_based" in dir(meshing_session)
+
+  >>> topo_meshing = meshing_session.topology_based()
+  ansys.fluent.core.exceptions.BetaFeaturesNotEnabled: The feature 'topology_based' requires 'enable_beta_features' flag to be enabled.
+
+  >>> # Enable beta features
+  >>> meshing_session.enable_beta_features()
+
+  >>> # Feature is now usable
+  >>> topo_meshing = meshing_session.topology_based()
+  >>> topo_meshing
+  <ansys.fluent.core.meshing.meshing_workflow.TopologyBasedMeshingWorkflow object at 0x0000024D574410F0>
+
+
+Solver Session
+--------------
+
+The ability to **switch to meshing mode** from a solver session is a beta feature.
+
+To enable and use it:
+
+.. code-block:: python
+
+  >>> solver_session = pyfluent.launch_fluent()
+
+  >>> # Method available before enabling beta features, but unusable and raises 'BetaFeaturesNotEnabled'
+  >>> assert hasattr(solver_session, "switch_to_meshing")
+
+  >>> switched_meshing_session = solver_session.switch_to_meshing()
+  ansys.fluent.core.exceptions.BetaFeaturesNotEnabled: The feature 'switch_to_meshing' requires 'enable_beta_features' flag to be enabled.
+
+  >>> # Enable beta features
+  >>> solver_session.enable_beta_features()
+
+  >>> # Method is now usable
+  >>> switched_meshing_session = solver_session.switch_to_meshing()
+  >>> assert switched_meshing_session.is_active()
+  >>> assert not solver_session.is_active()
+
+
+.. note::
+
+   Beta features are subject to change and may not be fully supported in all versions of Fluent.
+   Use them with caution in production workflows. Feedback on beta features is encouraged and
+   helps improve future releases.

doc/source/user_guide/user_guide_contents.rst

@@ -25,6 +25,7 @@ User guide
    usability
    make_container_image
    legacy/legacy_contents
+   beta_feature_access
 
 
 Welcome to the PyFluent user guide. This guide helps you understand how to use PyFluent to

src/ansys/fluent/core/exceptions.py

@@ -34,7 +34,7 @@ def __init__(
         context: str | None = None,
         name: Any | None = None,
         allowed_values: Iterable[Any] | None = None,
-    ):
+    ) -> None:
         """Initialize DisallowedValuesError."""
         super().__init__(
             allowed_name_error_message(
@@ -50,3 +50,15 @@ class InvalidArgument(ValueError):
     """Raised when an argument value is inappropriate."""
 
     pass
+
+
+class BetaFeaturesNotEnabled(RuntimeError):
+    """Raised when a beta feature is accessed without enabling beta features."""
+
+    def __init__(self, feature_name: str | None = None) -> None:
+        message = (
+            f"The feature '{feature_name}' is not available until 'enable_beta_features()' has been called."
+            if feature_name
+            else "This feature is not available until 'enable_beta_features()' has been called."
+        )
+        super().__init__(message)

src/ansys/fluent/core/session_pure_meshing.py

@@ -27,6 +27,7 @@
 
 import ansys.fluent.core as pyfluent
 from ansys.fluent.core.data_model_cache import DataModelCache, NameKey
+from ansys.fluent.core.exceptions import BetaFeaturesNotEnabled
 from ansys.fluent.core.fluent_connection import FluentConnection
 from ansys.fluent.core.services import SchemeEval
 from ansys.fluent.core.session import BaseSession
@@ -179,7 +180,7 @@ def topology_based(self):
             If beta features are not enabled in Fluent.
         """
         if not self._is_beta_enabled:
-            raise AttributeError("Topology-based Meshing is a beta feature in Fluent.")
+            raise BetaFeaturesNotEnabled("Topology-based meshing")
         return self._base_meshing.topology_based_meshing_workflow()
 
     @property
@@ -237,8 +238,3 @@ def transfer_mesh_to_solvers(
             clean_up_mesh_file,
             overwrite_previous,
         )
-
-    def __dir__(self):
-        if self._fluent_connection is not None and self._is_beta_enabled is False:
-            return sorted(set(super().__dir__()) - {"topology_based"})
-        return super().__dir__()

src/ansys/fluent/core/session_solver.py

@@ -30,6 +30,7 @@
 
 from ansys.api.fluent.v0 import svar_pb2 as SvarProtoModule
 import ansys.fluent.core as pyfluent
+from ansys.fluent.core.exceptions import BetaFeaturesNotEnabled
 from ansys.fluent.core.pyfluent_warnings import PyFluentDeprecationWarning
 from ansys.fluent.core.services import SchemeEval, service_creator
 from ansys.fluent.core.services.field_data import ZoneInfo, ZoneType
@@ -358,8 +359,6 @@ def __dir__(self):
             "svar_info",
             "reduction",
         }
-        if self._fluent_connection is not None and self._is_beta_enabled is False:
-            return sorted(dir_list - {"switch_to_meshing"})
         return sorted(dir_list)
 
     def switch_to_meshing(self):
@@ -376,9 +375,7 @@ def switch_to_meshing(self):
         Meshing
         """
         if not self._is_beta_enabled:
-            raise AttributeError(
-                "Switching to meshing mode is a beta feature in Fluent."
-            )
+            raise BetaFeaturesNotEnabled("switch_to_meshing")
         from ansys.fluent.core.session_meshing import Meshing
 
         self.settings.switch_to_meshing_mode()

tests/test_session.py

@@ -39,6 +39,7 @@
 from ansys.api.fluent.v0.scheme_pointer_pb2 import SchemePointer
 import ansys.fluent.core as pyfluent
 from ansys.fluent.core import connect_to_fluent, examples, session
+from ansys.fluent.core.exceptions import BetaFeaturesNotEnabled
 from ansys.fluent.core.fluent_connection import FluentConnection, PortNotProvided
 from ansys.fluent.core.launcher.error_handler import LaunchFluentError
 from ansys.fluent.core.pyfluent_warnings import PyFluentDeprecationWarning
@@ -753,11 +754,13 @@ def test_solver_attr_lookup(new_solver_session):
 @pytest.mark.fluent_version(">=25.2")
 def test_beta_meshing_session(new_meshing_session_wo_exit):
     meshing = new_meshing_session_wo_exit
-    assert "topology_based" not in dir(meshing)
-    with pytest.raises(AttributeError):
+    assert "topology_based" in dir(meshing)
+    assert hasattr(meshing, "topology_based")
+    with pytest.raises(BetaFeaturesNotEnabled):
         tp = meshing.topology_based()
     meshing.enable_beta_features()
     assert "topology_based" in dir(meshing)
+    assert hasattr(meshing, "topology_based")
     tp = meshing.topology_based()
     assert tp
 
@@ -772,11 +775,13 @@ def test_beta_meshing_session(new_meshing_session_wo_exit):
 def test_beta_solver_session(new_solver_session_wo_exit):
     solver = new_solver_session_wo_exit
     assert solver.is_active() is True
-    assert "switch_to_meshing" not in dir(solver)
-    with pytest.raises(AttributeError):
+    assert "switch_to_meshing" in dir(solver)
+    assert hasattr(solver, "switch_to_meshing")
+    with pytest.raises(BetaFeaturesNotEnabled):
         meshing = solver.switch_to_meshing()
     solver.enable_beta_features()
     assert "switch_to_meshing" in dir(solver)
+    assert hasattr(solver, "switch_to_meshing")
     meshing = solver.switch_to_meshing()
 
     assert solver.is_active() is False