Plug-in package with third-party dependencies#

This tutorial shows how to create, load and use a custom plug-in package with third-party dependencies

Create the plug-in package#

To create a plug-in package with multiple operators or with complex routines, you write a Python package.

A plug-in package with dependencies consists of a folder with the necessary files. Assume that the name of your plug-in package is custom_plugin. A folder with this name would contain four files:

  • __init__.py

  • operators.py

  • operators_loader.py

  • common.py

__init__.py file

The __init__.py file contains this code:

from operators_loader import load_operators

operators.py file

The operators.py file contains code like this:

operators_loader.py file

The operators_loader.py file contains code like this:

from custom_plugin import operators
from ansys.dpf.core.custom_operator import record_operator


def load_operators(*args):
    record_operator(operators.CustomOperator, *args)

common.py file

The common.py file contains the Python routines as classes and functions:

#write needed python routines as classes and functions here.

Third-party dependencies#

To add third-party modules as dependencies to a plugin package, create and reference a folder or ZIP file with the sites of the dependencies in an XML file located next to the folder for the plugin package. The XML file must have the same name as the plugin package plus an .xml extension.

When the ansys.dpf.core.core.load_library() method is called, PyDPF-Core uses the site Python module to add custom sites to the path for the Python interpreter.

To create these custom sites:

  1. Install the requirements of the plugin package in a Python virtual environment.

  2. Remove unnecessary folders from the site packages and compress them into a ZIP file.

  3. Place the ZIP file in the plugin package.

  4. Reference the path to the ZIP file in the XML file as indicated above.

To simplify this step, you can add a requirements file in the plugin package:

wheel
pygltflib

For this approach, do the following:

  1. Download the script for your operating system:

    • For Windows, download this PowerShell script.

    • For Linux, download this Shell script.

  1. Run the downloaded script with the mandatory arguments:

    • -pluginpath: Path to the folder with the plugin package.

    • -zippath: Path and name for the ZIP file.

    Optional arguments are:

    • -pythonexe: Path to a Python executable of your choice.

    • -tempfolder: Path to a temporary folder to work in. The default is the environment variable TEMP on Windows and /tmp/ on Linux.

  2. Run the command for your operating system.

  • From Windows PowerShell, run:

    create_sites_for_python_operators.ps1 -pluginpath /path/to/plugin -zippath /path/to/plugin/assets/winx64.zip

  • From Linux Shell, run:

    create_sites_for_python_operators.sh -pluginpath /path/to/plugin -zippath /path/to/plugin/assets/linx64.zip

Assume once again that the name of your plug-in package is custom_plugin. A folder with this name would contain these files:

  • __init__.py

  • operators.py

  • operators_loader.py

  • common.py

  • winx64.zip

  • linx64.zip

  • custom_plugin.xml

__init__.py file

The __init__.py file contains this code:

from operators_loader import load_operators

operators.py file

The operators.py file contains code like this:

operators_loader.py file

The operators_loader.py file contains code like this:

from custom_plugin import operators
from ansys.dpf.core.custom_operator import record_operator


def load_operators(*args):
    record_operator(operators.CustomOperator, *args)


def load_operators(*args):
            record_operator(operators.CustomOperator, *args)

common.py file

The common.py file contains the Python routines as classes and functions:

#write needed python routines as classes and functions here.

requirements.txt file

The requirements.txt file contains code like this:

wheel
pygltflib

The ZIP files for Windows and Linux are included as assets:

  • winx64.zip

  • linx64.zip

custom_plugin.xml file

The custom_plugin.xml file contains code like this:

<?xml version="1.0"?>
<Environment>
	<Windows>
		<CUSTOM_SITE>$(THIS_XML_FOLDER)/custom_plugin/assets/winx64.zip;$(CUSTOM_SITE)</CUSTOM_SITE>
		<LOAD_DEFAULT_DPF_SITE>true</LOAD_DEFAULT_DPF_SITE>
	</Windows>
	<Linux>
		<CUSTOM_SITE>$(THIS_XML_FOLDER)/custom_plugin/assets/linx64.zip:$(CUSTOM_SITE)</CUSTOM_SITE>
		<LOAD_DEFAULT_DPF_SITE>true</LOAD_DEFAULT_DPF_SITE>
	</Linux>
</Environment>

Load the plug-in package#

Use the load_library() method to load plug-in package.

  • The first argument is the path to the directory where the plug-in package is located.

  • The second argument is py_<package> where <package> is the name identifying the plug-in package.

  • The third argument is the name of the function exposed in the __init__ file for the plug-in package that is used to record operators.

dpf.load_library(
r"path/to/plugins/custom_plugin",
"py_my_custom_plugin", #if the load_operators function is defined in path/to/plugins/custom_plugin/__init__.py
"load_operators")

Use the custom operators#

Once the plugin is loaded, you can instantiate the custom operator:

new_operator = dpf.Operator("custom_operator") # if "custom_operator" is what is returned by the ``name`` property

References#

For more information, see ref_custom_operator in the API reference and Examples of creating custom operator plugins in Examples.