docs: event streaming callback

doc/source/conf.py

@@ -197,12 +197,12 @@ def _stop_fluent_container(gallery_conf, fname):
     "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "navigation_depth": -1,
     "collapse_navigation": True,
-    "cheatsheet": {
-        "file": "cheatsheet/cheat_sheet.qmd",
-        "pages": ["index", "getting_started/index", "user_guide/index"],
-        "title": "PyFluent cheat sheet",
-        "version": __version__,
-    },
+    # "cheatsheet": {
+    #     "file": "cheatsheet/cheat_sheet.qmd",
+    #     "pages": ["index", "getting_started/index", "user_guide/index"],
+    #     "title": "PyFluent cheat sheet",
+    #     "version": __version__,
+    # },
 }
 
 # -- Options for HTMLHelp output ---------------------------------------------

doc/source/user_guide/events.rst

@@ -18,20 +18,27 @@ The following code triggers a callback at the end of every iteration.
 
 .. code-block:: python
 
-  >>> from ansys.fluent.core import SolverEvent
+  >>> from ansys.fluent.core import SolverEvent, IterationEndedEventInfo
   >>>
-  >>> def on_iteration_ended(session, event_info):
+  >>> def on_iteration_ended(session, event_info: IterationEndedEventInfo):
   >>>     print("Iteration ended. Index = ", event_info.index)
   >>>
   >>> callback_id = solver.events.register_callback(SolverEvent.ITERATION_ENDED, on_iteration_ended)
-  >>> 
+
+The general signature of the callback function is cb(\*args, session, event_info), where session is the session instance
+and event_info instance holds information about the event. The event_info classes for each event are documented in the
+API reference of the :obj:`~ansys.fluent.core.streaming_services.events_streaming` module. See the callback function
+on_case_loaded_with_args() in the below examples for an example of how to pass additional arguments to the callback
+function via the args parameter.
+
 
 Examples
 --------
 
 .. code-block:: python
 
   >>> from ansys.fluent.core import MeshingEvent, SolverEvent
+  >>> from ansys.fluent.core import CaseLoadedEventInfo, DataLoadedEventInfo, SolutionInitializedEventInfo, IterationEndedEventInfo
   >>> from ansys.fluent.core.utils.event_loop import execute_in_event_loop_threadsafe
   >>> from ansys.fluent.visualization.matplotlib import matplot_windows_manager
   >>> from ansys.fluent.visualization.pyvista import pyvista_windows_manager
@@ -48,26 +55,26 @@ Examples
   >>> contour2.surfaces_list = ["symmetry"]
   >>> 
   >>> @execute_in_event_loop_threadsafe
-  >>> def auto_refersh_call_back_iteration(session, event_info):
+  >>> def auto_refersh_call_back_iteration(session, event_info: IterationEndedEventInfo):
   >>>   if event_info.index % 5 == 0:
   >>>       pyvista_windows_manager.refresh_windows(session.id, ["contour-1", "contour-2"])
   >>>       matplot_windows_manager.refresh_windows("", ["residual"])
   >>>
   >>> callback_itr_id = solver.events.register_callback(SolverEvent.ITERATION_ENDED, auto_refersh_call_back_iteration)
   >>>
   >>> @execute_in_event_loop_threadsafe
-  >>> def initialize_call_back(session, event_info):
+  >>> def initialize_call_back(session, event_info: SolutionInitializedEventInfo | DataLoadedEventInfo):
   >>>     pyvista_windows_manager.refresh_windows(session.id, ["contour-1", "contour-2"])
   >>>     matplot_windows_manager.refresh_windows("", ["residual"])
   >>>
   >>> callback_init_id = solver.events.register_callback(SolverEvent.SOLUTION_INITIALIZED, initialize_call_back)
   >>>
   >>> callback_data_read_id = solver.events.register_callback(SolverEvent.DATA_LOADED, initialize_call_back)
   >>>
-  >>> def on_case_loaded(session, event_info):
+  >>> def on_case_loaded(session, event_info: CaseLoadedEventInfo):
   >>>     print("Case loaded. Index = ", event_info.index)
   >>>
-  >>> def on_case_loaded_with_args(x, y, session, event_info):
+  >>> def on_case_loaded_with_args(x, y, session, event_info: CaseLoadedEventInfo):
   >>>     print(f"Case loaded with {x}, {y}. Index = ", event_info.index)
   >>>
   >>> callback = meshing.events.register_callback(MeshingEvent.CASE_LOADED, on_case_loaded)

src/ansys/fluent/core/streaming_services/events_streaming.py

@@ -128,6 +128,7 @@ def __getattr__(self, name):
 @dataclass
 class TimestepStartedEventInfo(EventInfoBase, event=SolverEvent.TIMESTEP_STARTED):
     """Information about the event triggered when a timestep is started.
+
     Attributes
     ----------
     index : int
@@ -143,6 +144,7 @@ class TimestepStartedEventInfo(EventInfoBase, event=SolverEvent.TIMESTEP_STARTED
 @dataclass
 class TimestepEndedEventInfo(EventInfoBase, event=SolverEvent.TIMESTEP_ENDED):
     """Information about the event triggered when a timestep is ended.
+
     Attributes
     ----------
     index : int
@@ -158,6 +160,7 @@ class TimestepEndedEventInfo(EventInfoBase, event=SolverEvent.TIMESTEP_ENDED):
 @dataclass
 class IterationEndedEventInfo(EventInfoBase, event=SolverEvent.ITERATION_ENDED):
     """Information about the event triggered when an iteration is ended.
+
     Attributes
     ----------
     index : int
@@ -190,6 +193,7 @@ class CalculationsResumedEventInfo(
 @dataclass
 class AboutToLoadCaseEventInfo(EventInfoBase, event=SolverEvent.ABOUT_TO_LOAD_CASE):
     """Information about the event triggered just before a case file is loaded.
+
     Attributes
     ----------
     case_file_name : str
@@ -202,6 +206,7 @@ class AboutToLoadCaseEventInfo(EventInfoBase, event=SolverEvent.ABOUT_TO_LOAD_CA
 @dataclass
 class CaseLoadedEventInfo(EventInfoBase, event=SolverEvent.CASE_LOADED):
     """Information about the event triggered after a case file is loaded.
+
     Attributes
     ----------
     case_file_name : str
@@ -214,6 +219,7 @@ class CaseLoadedEventInfo(EventInfoBase, event=SolverEvent.CASE_LOADED):
 @dataclass
 class AboutToLoadDataEventInfo(EventInfoBase, event=SolverEvent.ABOUT_TO_LOAD_DATA):
     """Information about the event triggered just before a data file is loaded.
+
     Attributes
     ----------
     data_file_name : str
@@ -226,6 +232,7 @@ class AboutToLoadDataEventInfo(EventInfoBase, event=SolverEvent.ABOUT_TO_LOAD_DA
 @dataclass
 class DataLoadedEventInfo(EventInfoBase, event=SolverEvent.DATA_LOADED):
     """Information about the event triggered after a data file is loaded.
+
     Attributes
     ----------
     data_file_name : str
@@ -252,6 +259,7 @@ class ReportDefinitionUpdatedEventInfo(
     EventInfoBase, event=SolverEvent.REPORT_DEFINITION_UPDATED
 ):
     """Information about the event triggered when a report definition is updated.
+
     Attributes
     ----------
     report_name : str
@@ -266,6 +274,7 @@ class ReportPlotSetUpdatedEventInfo(
     EventInfoBase, event=SolverEvent.REPORT_PLOT_SET_UPDATED
 ):
     """Information about the event triggered when a report plot set is updated.
+
     Attributes
     ----------
     plot_set_name : str
@@ -288,6 +297,7 @@ class SettingsClearedEventInfo(EventInfoBase, event=SolverEvent.SETTINGS_CLEARED
 @dataclass
 class SolutionPausedEventInfo(EventInfoBase, event=SolverEvent.SOLUTION_PAUSED):
     """Information about the event triggered when solution is paused.
+
     Attributes
     ----------
     level : str
@@ -303,6 +313,7 @@ class SolutionPausedEventInfo(EventInfoBase, event=SolverEvent.SOLUTION_PAUSED):
 @dataclass
 class ProgressUpdatedEventInfo(EventInfoBase, event=SolverEvent.PROGRESS_UPDATED):
     """Information about the event triggered when progress is updated.
+
     Attributes
     ----------
     message : str
@@ -320,6 +331,7 @@ class SolverTimeEstimateUpdatedEventInfo(
     EventInfoBase, event=SolverEvent.SOLVER_TIME_ESTIMATE_UPDATED
 ):
     """Information about the event triggered when solver time estimate is updated.
+
     Attributes
     ----------
     hours : float
@@ -338,6 +350,7 @@ class SolverTimeEstimateUpdatedEventInfo(
 @dataclass
 class FatalErrorEventInfo(EventInfoBase, event=SolverEvent.FATAL_ERROR):
     """Information about the event triggered when a fatal error occurs.
+
     Attributes
     ----------
     message : str