changes in the others functions

src/ansys/dpf/core/data_sources.py

@@ -397,7 +397,12 @@ def add_domain_file_path(
             self, str(filepath), key, domain_id
         )
 
-    def add_file_path_for_specified_result(self, filepath, key="", result_key=""):
+    def add_file_path_for_specified_result(
+        self,
+        filepath: Union[str, os.PathLike],
+        key: Optional[str] = "",
+        result_key: Optional[str] = "",
+    ):
         """Add a file path for a specified result file key to the data sources.
 
         This method can be used when results files with different keys (extensions) are
@@ -406,13 +411,13 @@ def add_file_path_for_specified_result(self, filepath, key="", result_key=""):
 
         Parameters
         ----------
-        filepath : str or os.PathLike object
+        filepath
             Path of the file.
-        key : str, optional
+        key
             Extension of the file, which is used as a key for choosing the correct
             plugin when a result is requested by an operator. The default is ``""``,
             in which case the key is found directly.
-        result_key: str, optional
+        result_key
             Extension of the results file that the specified file path belongs to.
             The default is ``""``, in which case the key is found directly.
         """
@@ -425,20 +430,46 @@ def add_file_path_for_specified_result(self, filepath, key="", result_key=""):
             self, str(filepath), key, result_key
         )
 
-    def add_upstream(self, upstream_data_sources, result_key=""):
-        """Add upstream data sources.
+    def add_upstream(
+        self, upstream_data_sources: DataSources, result_key: Optional[str] = ""
+    ) -> None:
+        """Add upstream data sources to the main DataSources object.
 
         This is used to add a set of path creating an upstream for
         recursive workflows.
 
         Parameters
         ----------
-        upstream_data_sources : DataSources
+        upstream_data_sources
             Set of paths creating an upstream for recursive workflows.
 
-        result_key: str, optional
+        result_key
             Extension of the result file group with which this upstream belongs
 
+        Examples
+        --------
+        Add an upstream data to the main DataSources object of an expansion analysis
+
+        >>> from ansys.dpf import core as dpf
+        >>> from ansys.dpf.core import examples
+        >>>
+        >>> # Download the result files
+        >>> paths = examples.download_msup_files_to_dict()
+        >>> # Create the main DataSources object
+        >>> my_data_sources = dpf.DataSources()
+        >>> # Define the path where the main result data can be found
+        >>> my_data_sources.set_result_file_path(filepath=paths["rfrq"],  key='rfrq')
+        >>>
+        >>> # Create the DataSources object for the upstream data
+        >>> my_data_sources_upstream = dpf.DataSources()
+        >>> # Define the path where the main upstream data can be found
+        >>> my_data_sources_upstream.set_result_file_path(filepath=paths["mode"], key='mode')
+        >>> # Add the additional upstream data to the upstream DataSources object
+        >>> my_data_sources_upstream.add_file_path(filepath=paths["rst"], key='rst')
+        >>>
+        >>> # Add the upstream DataSources to the main DataSources object
+        >>> my_data_sources.add_upstream(upstream_data_sources=my_data_sources_upstream)
+
         """
         if result_key == "":
             self._api.data_sources_add_upstream_data_sources(self, upstream_data_sources)
@@ -447,20 +478,51 @@ def add_upstream(self, upstream_data_sources, result_key=""):
                 self, upstream_data_sources, result_key
             )
 
-    def add_upstream_for_domain(self, upstream_data_sources, domain_id):
-        """Add an upstream data sources for a given domain.
+    def add_upstream_for_domain(self, upstream_data_sources: DataSources, domain_id: int) -> None:
+        """Add an upstream data sources to the main DataSources object for a given domain.
 
         This is used to add a set of path creating an upstream for
         recursive workflows in a distributed solve.
 
         Parameters
         ----------
-        upstream_data_sources : DataSources
+        upstream_data_sources
             Set of paths creating an upstream for recursive workflows.
 
-        domain_id: int
+        domain_id
             Domain id for distributed files.
 
+        Examples
+        --------
+        Add an upstream data to the main DataSources object of an expansion distributed analysis
+
+        >>> from ansys.dpf import core as dpf
+        >>> from ansys.dpf.core import examples
+        >>>
+        >>> # Download the result files
+        >>> paths = examples.find_distributed_msup_folder()
+        >>> # Create the main DataSources object
+        >>> my_data_sources = dpf.DataSources()
+        >>> # Define the path where the main result file can be found and specify its domain
+        >>> # We use a format string here because the function used to define the path gives the path to a folder
+        >>> my_data_sources.set_domain_result_file_path(path=rf"{paths}\file_load_1.rfrq", key='rfrq', domain_id=0)
+        >>> # Add the additional result file to the DataSources object and specify its domain
+        >>> my_data_sources.add_domain_file_path(filepath=rf"{paths}\file_load_2.rfrq", key='rfrq', domain_id=1)
+        >>>
+        >>> # Create the DataSources object for the first and second upstream files
+        >>> my_data_sources_upstream_g0 = dpf.DataSources()
+        >>> my_data_sources_upstream_g1 = dpf.DataSources()
+        >>> # Define the path where the main upstream files can be found
+        >>> my_data_sources_upstream_g0.set_result_file_path(filepath=rf"{paths}\file0.mode", key='mode')
+        >>> my_data_sources_upstream_g1.set_result_file_path(filepath=rf"{paths}\file1.mode", key='mode')
+        >>> # Add the additional upstream files to the upstream DataSources objectS
+        >>> my_data_sources_upstream_g0.add_file_path(filepath=rf"{paths}\file0.rst", key='rst')
+        >>> my_data_sources_upstream_g1.add_file_path(filepath=rf"{paths}\file1.rst", key='rst')
+        >>>
+        >>> # Add the upstream DataSources to the main DataSources object and specify its domain
+        >>> my_data_sources.add_upstream_for_domain(upstream_data_sources=my_data_sources_upstream_g0, domain_id=0)
+        >>> my_data_sources.add_upstream_for_domain(upstream_data_sources=my_data_sources_upstream_g1, domain_id=1)
+
         """
         self._api.data_sources_add_upstream_domain_data_sources(
             self, upstream_data_sources, domain_id
@@ -475,6 +537,19 @@ def result_key(self):
         str
            Result key.
 
+        Examples
+        --------
+
+        >>> from ansys.dpf import core as dpf
+        >>>
+        >>> # Create the DataSources object
+        >>> my_data_sources = dpf.DataSources()
+        >>> # Define the path where the main result file can be found
+        >>> my_data_sources.set_result_file_path(filepath='/tmp/file.rst', key='rst')
+        >>> # Get the to the main result file
+        >>> my_data_sources.result_key
+        'rst'
+
         """
         return self._api.data_sources_get_result_key(self)
 
@@ -486,6 +561,64 @@ def result_files(self):
         ----------
         list
             List of result files.
+
+        Examples
+        --------
+        If you use the :func:`set_result_file_path() <ansys.dpf.core.data_sources.DataSources.set_result_file_path>`
+        function, it will return only the file path given as an argument to this function.
+
+        >>> from ansys.dpf import core as dpf
+        >>>
+        >>>  # Create the DataSources object
+        >>> my_data_sources = dpf.DataSources()
+        >>>  # Define the path where the main result file can be found
+        >>> my_data_sources.set_result_file_path(filepath='/tmp/file.cas', key='cas')
+        >>>  # Add the additional result file to the DataSources object
+        >>> my_data_sources.add_file_path(filepath='/tmp/ds.dat', key='dat')
+        >>>  # Get the path to the main result file
+        >>> my_data_sources.result_files
+        ['/tmp/file.cas']
+
+        If you added an upstream result file, it is not listed in the main ``DataSources`` object. You have to
+        check directly in the ``DataSources`` object created to define the upstream data.
+
+        >>> from ansys.dpf import core as dpf
+        >>>
+        >>>  # Create the main DataSources object with a main file path
+        >>> my_data_sources = dpf.DataSources(result_path='/tmp/file.rfrq')
+        >>>
+        >>>  # Create the DataSources object for the upstream data
+        >>> my_data_sources_upstream = dpf.DataSources(result_path='/tmp/file.mode')
+        >>>  # Add the additional upstream data to the upstream DataSources object
+        >>> my_data_sources_upstream.add_file_path(filepath='/tmp/file.rst', key='rst')
+        >>>
+        >>>  # Add the upstream DataSources to the main DataSources object
+        >>> my_data_sources.add_upstream(upstream_data_sources=my_data_sources_upstream)
+        >>>
+        >>>  # Get the path to the main result file of the main DataSources object
+        >>> my_data_sources.result_files
+        ['/tmp/file.rfrq']
+
+        If you are checking the DataSources object created to define the upstream data, only the first one is listed.
+
+        >>>  # Get the path to the upstream file of the upstream DataSources object
+        >>> my_data_sources_upstream.result_files
+        ['/tmp/file.mode']
+
+        If you have a ``DataSources`` object with more than one domain, a empty list is returned.
+
+        >>> from ansys.dpf import core as dpf
+        >>>
+        >>>  # Create the DataSources object
+        >>> my_data_sources = dpf.DataSources()
+        >>>  # Define the path where the main result data can be found and specify its domain
+        >>> my_data_sources.set_domain_result_file_path(path='/tmp/file0.rst', key='rst', domain_id=0)
+        >>> my_data_sources.set_domain_result_file_path(path='/tmp/file1.rst', key='rst', domain_id=1)
+        >>>
+        >>>  # Get the path to the main result files of the DataSources object
+        >>> my_data_sources.result_files
+        [None, None]
+
         """
         result_key = self.result_key
         if result_key == "":