feat: improve example files handling in examples scripts (#193)

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

doc/changelog.d/193.added.md

@@ -0,0 +1 @@
+feat: improve example files handling in examples scripts

doc/source/conf.py

@@ -148,6 +148,7 @@
     "image_scrapers": (DynamicScraper(), "matplotlib"),
     "ignore_pattern": r"__init__\.py",
     "thumbnail_size": (350, 350),
+    "abort_on_example_error": True,
 }
 
 suppress_warnings = ["config.cache"]

examples/001_initialize_server_and_deal_with_license.py

@@ -97,7 +97,7 @@
 # Execute the PyAnsys Sound ``LoadWav`` operator several times in a row
 # and measure the execution time.
 
-path_flute_wav = download_flute_wav()
+path_flute_wav = download_flute_wav(server=my_server)
 
 for i in range(5):
     now = datetime.datetime.now()
@@ -131,6 +131,8 @@
 my_server = connect_to_or_start_server(use_license_context=True)
 
 # Execute the same and measure the execution time
+path_flute_wav = download_flute_wav(server=my_server)
+
 for i in range(5):
     now = datetime.datetime.now()
     wav_loader = LoadWav(path_flute_wav)

examples/002_load_resample_amplify_write_wav_files.py

@@ -57,7 +57,7 @@
 # in the DPF-Core API documentation.
 
 # Return the input data of the example file
-path_flute_wav = download_flute_wav()
+path_flute_wav = download_flute_wav(server=server)
 
 # Load the WAV file.
 wav_loader = LoadWav(path_flute_wav)

examples/003_compute_stft.py

@@ -59,7 +59,7 @@
 # in the DPF-Core API documentation.
 
 # Return the input data of the example file
-path_flute_wav = download_flute_wav()
+path_flute_wav = download_flute_wav(server=my_server)
 
 # Load the WAV file
 wav_loader = LoadWav(path_flute_wav)

examples/004_isolate_orders.py

@@ -129,7 +129,7 @@ def plot_stft(stft_class, vmax):
 # - The associated RPM profile
 
 # Return the input data of the example file
-path_accel_wav = download_accel_with_rpm_wav()
+path_accel_wav = download_accel_with_rpm_wav(server=my_server)
 
 # Load the WAV file.
 wav_loader = LoadWav(path_accel_wav)
@@ -249,8 +249,8 @@ def plot_stft(stft_class, vmax):
 # Obtain parent folder of the 'accel_with_rpm.wav' file
 parent_folder = pathlib.Path(path_accel_wav).parent.absolute()
 
-path_accel_wav_2 = download_accel_with_rpm_2_wav()
-path_accel_wav_3 = download_accel_with_rpm_3_wav()
+path_accel_wav_2 = download_accel_with_rpm_2_wav(server=my_server)
+path_accel_wav_3 = download_accel_with_rpm_3_wav(server=my_server)
 paths = (path_accel_wav, path_accel_wav_2, path_accel_wav_3)
 
 fft_sizes = [256, 2048, 4096]

examples/005_xtract_feature.py

@@ -141,7 +141,7 @@ def plot_stft(stft_class, SPLmax, title="STFT", maximum_frequency=MAX_FREQUENCY_
 # The WAV file contains harmonics and shocks.
 
 # Return the input data of the example file
-path_xtract_demo_signal_1 = download_xtract_demo_signal_1_wav()
+path_xtract_demo_signal_1 = download_xtract_demo_signal_1_wav(my_server)
 
 # Load the WAV file
 wav_loader = LoadWav(path_to_wav=path_xtract_demo_signal_1)
@@ -292,7 +292,7 @@ def plot_stft(stft_class, SPLmax, title="STFT", maximum_frequency=MAX_FREQUENCY_
 # all previous classes.
 
 
-path_xtract_demo_signal_2 = download_xtract_demo_signal_2_wav()
+path_xtract_demo_signal_2 = download_xtract_demo_signal_2_wav(my_server)
 
 paths = [path_xtract_demo_signal_1, path_xtract_demo_signal_2]
 

examples/006_calculate_PR_and_TNR.py

@@ -146,7 +146,7 @@
 # Use the PowerSpectralDensity class to calculate a PSD, and compute Prominence Ratio (PR).
 
 # Load example data from WAV file.
-path_flute_wav = download_flute_wav()
+path_flute_wav = download_flute_wav(server=my_server)
 wav_loader = LoadWav(path_flute_wav)
 wav_loader.process()
 flute_signal = wav_loader.get_output()[0]

examples/007_calculate_psychoacoustic_indicators.py

@@ -87,7 +87,7 @@
 # in the DPF-Core API documentation.
 
 # Load example data from WAV file
-path_flute_wav = download_flute_wav()
+path_flute_wav = download_flute_wav(server=my_server)
 wav_loader = LoadWav(path_flute_wav)
 wav_loader.process()
 fc_signal = wav_loader.get_output()
@@ -117,7 +117,7 @@
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Load another WAV file and store it along with the first one.
 
-path_flute2_wav = download_flute_2_wav()
+path_flute2_wav = download_flute_2_wav(server=my_server)
 wav_loader = LoadWav(path_flute2_wav)
 wav_loader.process()
 
@@ -151,7 +151,7 @@
 # Calculate ISO 532-1 loudness for a non-stationary sound
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Load a new signal (non-stationary) from a WAV file.
-path_accel_wav = download_accel_with_rpm_wav()
+path_accel_wav = download_accel_with_rpm_wav(server=my_server)
 wav_loader = LoadWav(path_accel_wav)
 wav_loader.process()
 f_signal = wav_loader.get_output()[0]  # Field 0 only, because the RPM profile is useless here.

src/ansys/sound/core/examples_helpers/download.py

@@ -25,6 +25,7 @@
 import os
 import shutil
 
+from ansys.dpf.core import upload_file_in_tmp_folder
 import platformdirs
 import requests
 
@@ -66,16 +67,40 @@ def delete_downloads():  # pragma no cover
     return True
 
 
-def _get_file_url(filename, directory=None):  # pragma no cover
-    if directory:
-        return (
-            f"https://github.com/ansys/example-data/raw/master/{directory}/{filename}"  # noqa: E231
-        )
-    return f"https://github.com/ansys/example-data/raw/master/{filename}"  # noqa: E231
+def _get_example_file_url(filename):  # pragma no cover
+    """Get the URL of the example file in the PyAnsys Sound examples repository.
+
+    Parameters
+    ----------
+    filename : str
+        File in https://github.com/ansys/example-data/raw/master/pyansys-sound/
+
+    Returns
+    -------
+    File url
+    """
+    return (
+        f"https://github.com/ansys/example-data/raw/master/pyansys-sound/{filename}"  # noqa: E231
+    )
 
 
 @check_directory_exist(EXAMPLES_PATH)
-def _retrieve_file(url, filename, _test=False):  # pragma no cover
+def _download_file_in_local_tmp_folder(url, filename):  # pragma no cover
+    """Download a file from the PyAnsys Sound examples repository to the local tmp folder.
+
+    Parameters
+    ----------
+    url : str
+        Url of the file to download.
+        This url can be provided using _get_example_file_url() function.
+
+    filename : str
+        File name in the local tmp folder.
+
+    Returns
+    -------
+    Local path of the downloaded file.
+    """
     # First check if file has already been downloaded
     local_path = os.path.join(EXAMPLES_PATH, os.path.basename(filename))
     local_path_no_zip = local_path.replace(".zip", "")
@@ -93,17 +118,32 @@ def _retrieve_file(url, filename, _test=False):  # pragma no cover
     return local_path
 
 
-def _download_file(filename, directory=None, _test=False):  # pragma no cover
-    url = _get_file_url(filename, directory)
-    try:
-        local_path = _retrieve_file(url, filename, _test)
+def _download_example_file_to_server_tmp_folder(filename, server=None):  # pragma no cover
+    """Download a file from the PyAnsys Sound examples repository and upload it to the DPF server.
 
-        # In case of CI/CD pipelines
-        port_in_env = os.environ.get("ANSRV_DPF_SOUND_PORT")
-        if port_in_env is not None:
-            return "C:\\data\\" + filename
-        else:
-            return local_path
+    Parameters
+    ----------
+    filename : str
+        Example file name.
+
+    server : ansys.dpf.core.server.Server, optional
+        DPF server to which to upload the file.
+        If None, attempts to use the global server.
+
+    Returns
+    -------
+    str
+        Path of the file on the DPF server.
+    """
+    # get file url in git repo
+    url = _get_example_file_url(filename)
+    try:
+        # download file locally
+        local_path = _download_file_in_local_tmp_folder(url, filename)
+        # upload file to DPF server,
+        # so that we are independent on the server configuration
+        server_path = upload_file_in_tmp_folder(file_path=local_path, server=server)
+        return server_path
 
     except Exception as e:  # Generate exception
         raise RuntimeError(
@@ -119,6 +159,9 @@ def _download_file(filename, directory=None, _test=False):  # pragma no cover
 def download_flute_psd():
     """Download the PSD of the ``flute.wav`` file.
 
+    As flute_psd.txt file is opened using python 'open' function,
+    we need the local path of the file.
+
     Examples
     --------
     >>> from ansys.sound.core.examples_helpers import download_flute_psd
@@ -128,89 +171,96 @@ def download_flute_psd():
     -------
     str
         Local path for the ``flute_psd.txt`` file.
-    str
-        Path on the Docker container for the ``flute_psd.txt`` file.
-
     """
-    filename = "flute_psd.txt"
-    directory = "pyansys-sound"
-    url = _get_file_url(filename, directory)
-    local_path = _retrieve_file(url, filename, False)
+    url = _get_example_file_url("flute_psd.txt")
+    try:
+        # download file locally
+        local_path = _download_file_in_local_tmp_folder(url, "flute_psd.txt")
+    except Exception as e:  # Generate exception # pragma no cover
+        raise RuntimeError(
+            "For the reason that follows, retrieving the file failed.\n"
+            "You can download this file from:\n"
+            f"{url}\n"
+            "\n"
+            "The reported error message is:\n"
+            f"{str(e)}"
+        )
+
     return local_path
 
 
-def download_flute_wav():
+def download_flute_wav(server=None):
     """Download the ``flute.wav`` file.
 
     Returns
     -------
     str
         Path for the ``flute.wav`` file.
     """
-    return _download_file("flute.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("flute.wav", server=server)
 
 
-def download_flute_2_wav():
+def download_flute_2_wav(server=None):
     """Download the ``flute2.wav`` file.
 
     Returns
     -------
     str
         Path for the ``flute2.wav`` file.
     """
-    return _download_file("flute2.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("flute2.wav", server=server)
 
 
-def download_accel_with_rpm_wav():
+def download_accel_with_rpm_wav(server=None):
     """Download the ``accel_with_rpm.wav`` file.
 
     Returns
     -------
     str
         Path for the ``accel_with_rpm.wav`` file.
     """
-    return _download_file("accel_with_rpm.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("accel_with_rpm.wav", server=server)
 
 
-def download_accel_with_rpm_2_wav():
+def download_accel_with_rpm_2_wav(server=None):
     """Download the ``accel_with_rpm_2.wav`` file.
 
     Returns
     -------
     str
         Path for the ``accel_with_rpm_2.wav`` file.
     """
-    return _download_file("accel_with_rpm_2.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("accel_with_rpm_2.wav", server=server)
 
 
-def download_accel_with_rpm_3_wav():
+def download_accel_with_rpm_3_wav(server=None):
     """Download the ``accel_with_rpm_3.wav`` file.
 
     Returns
     -------
     str
         Path for the ``accel_with_rpm_3.wav`` file.
     """
-    return _download_file("accel_with_rpm_3.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("accel_with_rpm_3.wav", server=server)
 
 
-def download_xtract_demo_signal_1_wav():
+def download_xtract_demo_signal_1_wav(server=None):
     """Download the ``xtract_demo_signal_1.wav`` file.
 
     Returns
     -------
     str
         Path for the ``xtract_demo_signal_1.wav`` file.
     """
-    return _download_file("xtract_demo_signal_1.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("xtract_demo_signal_1.wav", server=server)
 
 
-def download_xtract_demo_signal_2_wav():
+def download_xtract_demo_signal_2_wav(server=None):
     """Download the ``xtract_demo_signal_2.wav`` file.
 
     Returns
     -------
     str
         Path for the ``xtract_demo_signal_2.wav`` file.
     """
-    return _download_file("xtract_demo_signal_2.wav", "pyansys-sound")
+    return _download_example_file_to_server_tmp_folder("xtract_demo_signal_2.wav", server=server)