Examples/refactor custom plugin examples (#1946)

* Create examples.download_average_filter_plugin

* Create examples.download_gltf_plugin

* Create examples.download_easy_statistics

* Apply suggestions from code review

* Add testing

examples/08-python-operators/00-wrapping_numpy_capabilities.py

@@ -56,16 +56,9 @@
 #
 # Download and display the Python script.
 
-from ansys.dpf.core import examples
-
+from ansys.dpf.core.examples import download_easy_statistics
 
-GITHUB_SOURCE_URL = (
-    "https://github.com/ansys/pydpf-core/raw/master/doc/source/examples/07-python-operators/plugins"
-)
-EXAMPLE_FILE = GITHUB_SOURCE_URL + "/easy_statistics.py"
-operator_file_path = examples.downloads._retrieve_file(
-    EXAMPLE_FILE, "easy_statistics.py", "python_plugins"
-)
+operator_file_path = download_easy_statistics()
 
 with open(operator_file_path, "r") as f:
     for line in f.readlines():

examples/08-python-operators/01-package_python_operators.py

@@ -54,35 +54,9 @@
 #
 # Download the ``average_filter_plugin`` plug-in package that has already been
 # created for you.
-
-import os
-
 from ansys.dpf.core import examples
 
-
-print("\033[1m average_filter_plugin")
-file_list = [
-    "average_filter_plugin/__init__.py",
-    "average_filter_plugin/operators.py",
-    "average_filter_plugin/operators_loader.py",
-    "average_filter_plugin/common.py",
-]
-plugin_folder = None
-GITHUB_SOURCE_URL = (
-    "https://github.com/ansys/pydpf-core/raw/"
-    "master/doc/source/examples/07-python-operators/plugins/"
-)
-
-for file in file_list:
-    EXAMPLE_FILE = GITHUB_SOURCE_URL + file
-    operator_file_path = examples.downloads._retrieve_file(EXAMPLE_FILE, file, "python_plugins")
-    plugin_folder = os.path.dirname(operator_file_path)
-    print(f"\033[1m {file}:\n \033[0m")
-    with open(operator_file_path, "r") as f:
-        for line in f.readlines():
-            print("\t\t\t" + line)
-    print("\n\n")
-
+plugin_folder = examples.download_average_filter_plugin()
 
 ###############################################################################
 # Load the plug-in package

examples/08-python-operators/02-python_operators_with_dependencies.py

@@ -61,37 +61,8 @@
 
 from ansys.dpf.core import examples
 
-
-print("\033[1m gltf_plugin")
-file_list = [
-    "gltf_plugin/__init__.py",
-    "gltf_plugin/operators.py",
-    "gltf_plugin/operators_loader.py",
-    "gltf_plugin/requirements.txt",
-    "gltf_plugin/gltf_export.py",
-    "gltf_plugin/texture.png",
-    "gltf_plugin.xml",
-]
-plugin_path = None
+plugin_path = examples.download_gltf_plugin()
 folder_root = os.path.join(os.getcwd().rsplit("pydpf-core", 1)[0], "pydpf-core")
-GITHUB_SOURCE_URL = (
-    "https://github.com/ansys/pydpf-core/raw/"
-    "master/doc/source/examples/07-python-operators/plugins/"
-)
-
-for file in file_list:
-    EXAMPLE_FILE = GITHUB_SOURCE_URL + file
-    operator_file_path = examples.downloads._retrieve_file(EXAMPLE_FILE, file, "python_plugins")
-    print(f"\033[1m {file}\n \033[0m")
-    if (
-        os.path.splitext(file)[1] == ".py" or os.path.splitext(file)[1] == ".xml"
-    ) and file != "gltf_plugin/gltf_export.py":
-        with open(operator_file_path, "r") as f:
-            for line in f.readlines():
-                print("\t\t\t" + line)
-        print("\n\n")
-        if plugin_path is None:
-            plugin_path = os.path.dirname(operator_file_path)
 
 # %%
 # To add third-party modules as dependencies to a plug-in package, you must

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

@@ -28,10 +28,17 @@
 import os
 import urllib.request
 import warnings
+from typing import Union
+
 from ansys.dpf.core.examples.examples import find_files
 
 EXAMPLE_REPO = "https://github.com/ansys/example-data/raw/master/"
 
+GITHUB_SOURCE_URL = (
+    "https://github.com/ansys/pydpf-core/raw/"
+    "master/doc/source/examples/07-python-operators/plugins/"
+)
+
 
 def delete_downloads(verbose=True):
     """Delete all downloaded examples to free space or update the files"""
@@ -1993,3 +2000,142 @@ def find_distributed_msup_folder(
         return_local_path,
     )
     return os.path.dirname(path)
+
+
+def download_average_filter_plugin(
+    should_upload: bool = True, server=None, return_local_path=False
+) -> Union[str, None]:
+    """Make the plugin available server side, if the server is remote the plugin is uploaded
+    server side. Returns the path of the plugin folder.
+
+    Parameters
+    ----------
+    should_upload:
+        Whether the file should be uploaded server side when the server is remote.
+    server:
+        Server with channel connected to the remote or local instance. When
+        ``None``, attempts to use the global server.
+    return_local_path:
+        If ``True``, the local path is returned as is, without uploading, nor searching
+        for mounted volumes.
+
+    Returns
+    -------
+    str
+        Path to the plugin folder.
+
+    Examples
+    --------
+
+    >>> from ansys.dpf.core import examples
+    >>> path = examples.download_average_filter_plugin()
+
+    """
+    file_list = [
+        "average_filter_plugin/__init__.py",
+        "average_filter_plugin/operators.py",
+        "average_filter_plugin/operators_loader.py",
+        "average_filter_plugin/common.py",
+    ]
+    return _retrieve_plugin(
+        file_list=file_list,
+        should_upload=should_upload,
+        server=server,
+        return_local_path=return_local_path,
+    )
+
+
+def download_gltf_plugin(
+    should_upload: bool = True, server=None, return_local_path=False
+) -> Union[str, None]:
+    """Make the plugin available server side, if the server is remote the plugin is uploaded
+    server side. Returns the path of the plugin folder.
+
+    Parameters
+    ----------
+    should_upload:
+        Whether the file should be uploaded server side when the server is remote.
+    server:
+        Server with channel connected to the remote or local instance. When
+        ``None``, attempts to use the global server.
+    return_local_path:
+        If ``True``, the local path is returned as is, without uploading, nor searching
+        for mounted volumes.
+
+    Returns
+    -------
+    str
+        Path to the plugin folder.
+
+    Examples
+    --------
+
+    >>> from ansys.dpf.core import examples
+    >>> path = examples.download_gltf_plugin()
+
+    """
+    file_list = [
+        "gltf_plugin.xml",
+        "gltf_plugin/__init__.py",
+        "gltf_plugin/operators.py",
+        "gltf_plugin/operators_loader.py",
+        "gltf_plugin/requirements.txt",
+        "gltf_plugin/gltf_export.py",
+        "gltf_plugin/texture.png",
+    ]
+    return _retrieve_plugin(
+        file_list=file_list,
+        should_upload=should_upload,
+        server=server,
+        return_local_path=return_local_path,
+    )
+
+
+def download_easy_statistics(
+    should_upload: bool = True, server=None, return_local_path=False
+) -> Union[str, None]:
+    """Make the plugin available server side, if the server is remote the plugin is uploaded
+    server side. Returns the path of the plugin folder.
+
+    Parameters
+    ----------
+    should_upload:
+        Whether the file should be uploaded server side when the server is remote.
+    server:
+        Server with channel connected to the remote or local instance. When
+        ``None``, attempts to use the global server.
+    return_local_path:
+        If ``True``, the local path is returned as is, without uploading, nor searching
+        for mounted volumes.
+
+    Returns
+    -------
+    str
+        Path to the plugin folder.
+
+    Examples
+    --------
+
+    >>> from ansys.dpf.core import examples
+    >>> path = examples.download_easy_statistics()
+
+    """
+    file_name = "easy_statistics.py"
+    EXAMPLE_FILE = GITHUB_SOURCE_URL + file_name
+    operator_file_path = _retrieve_file(
+        EXAMPLE_FILE, filename=file_name, directory="python_plugins"
+    )
+    return find_files(operator_file_path, should_upload, server, return_local_path)
+
+
+def _retrieve_plugin(
+    file_list: list[str], should_upload: bool = True, server=None, return_local_path=False
+) -> Union[str, None]:
+    path = None
+    for file in file_list:
+        EXAMPLE_FILE = GITHUB_SOURCE_URL + file
+        operator_file_path = _retrieve_file(EXAMPLE_FILE, file, directory="python_plugins")
+        path = os.path.dirname(
+            find_files(operator_file_path, should_upload, server, return_local_path)
+        )
+    return path

tests/test_examples.py

@@ -194,3 +194,15 @@ def test_get_example_required_minimum_dpf_version(tmp_path):
     p = tmp_path / "test_example_version_1.py"
     p.write_text(example_header)
     assert examples.get_example_required_minimum_dpf_version(p) == "0.0"
+
+
+def test_download_easy_statistics():
+    assert os.path.exists(examples.download_easy_statistics(return_local_path=True))
+
+
+def test_download_average_filter_plugin():
+    assert os.path.exists(examples.download_average_filter_plugin(return_local_path=True))
+
+
+def test_download_gltf_plugin():
+    assert os.path.exists(examples.download_gltf_plugin(return_local_path=True))