External Tools

To add an external tool to PyDM, you will need to subclass the following base class and customize its methods:

class pydm.tools.ExternalTool(icon, name, group, author='', use_with_widgets=True, use_without_widget=True)

Bases: object

PyDM base class for External Tools hook-up. This class offers a boilerplate for tools to be added to PyDM. Code available at PyDMApplication will automatically install the tool if available somewhere under PYDM_TOOLS_PATH or if explicitly installed.

Parameters:

• icon (QIcon) – The icon to be used when rendering the menu. Use None for no Icon.

• name (str) – The tool name. This must be unique across the combination group+name.

• group (str) – The group in which this action must be inserted. This becomes a QMenu with the tool as an action inside.

• author (str, optional) – This information is used to list the author name at the About screen.

• use_with_widgets (bool) – Whether or not this action should be rendered at a Custom Context Menu for the PyDMWidgets. If False the tool will be available at the Main Window menu only and will receive as a parameter channels as None and sender as the main_window object.

• use_without_widgets (bool) – Whether or not this action should be rendered at locations other than a widget Custom Context Menu.

call(channels, sender)

This method is invoked when the tool is selected at the menu.

Parameters:

• channels (list) – The list of channels in use at the widget.

• sender (PyDMWidget) – The PyDMWidget or Main Window that triggered the action.

from_json(content)

Recreate the tool based on the serialized information sent as parameter.

Parameters:

content (str) –

get_info()

Retrieve basic information about the External Tool in a format that is parsed and used at the About screen.

Returns:

Dictionary containing at least author, file, group and name of the External Tool.

Return type:

dict

is_compatible_with(widget)

Verify if the ExternalTool is compatible with the given widget.

Parameters:

widget (QWidget) – The widget for which the ExternalTool is being assembled.

Returns:

True if this ExternalTool is compatible with the widget, False otherwise.

Return type:

bool

to_json()

Serialize the information at this tool in order to make it possible to be added to another PyDM Application without user interference.

Return type:

str

Example:

from pydm.tools import ExternalTool
from pydm.utilities.iconfont import IconFont


class DummyTool(ExternalTool):

    def __init__(self):
        icon = IconFont().icon("cogs")
        name = "Dummy Tool"
        group = "Example"
        use_with_widgets = False
        super().__init__(
            icon=icon,
            name=name,
            group=group,
            use_with_widgets=use_with_widgets
        )

    def call(self, channels, sender):
        print("Called Dummy Tool from: {} with:".format(sender))
        print("Channels: ", channels)
        print("My info: ", self.get_info())

    def to_json(self):
        return ""

    def from_json(self, content):
        print("Received from_json: ", content)

    def get_info(self):
        ret = ExternalTool.get_info(self)
        ret.update({'file': __file__})
        return ret

Configuration

There are two options for telling PyDM where your external tools are.

The first is the PYDM_TOOLS_PATH environment variable, which is an delimited list of paths to search for files that match the pattern *_tool.py. They can be in the provided path or any subdirectory of that path. On Linux, the delimiter is “:” whereas on Windows it is “;”.

Alternatively, for Python packages that contain external tools, an entrypoint may be used to locate the tool class.

Here is an example setup.py that could be used to locate a PyDM external tool in your own Python package:

from setuptools import setup, find_packages

setup(
    name="my_package",
    # ... other settings will go here
    entry_points={
        "gui_scripts": ["my_package_gui=my_package.main:main"],
        "pydm.tool": [
            "my_package=my_package.tool_name:ToolClassName",
        ],
    },
    install_requires=[],
)

This would assume that you have the following:

1. A package named “my_package” with my_package/__init__.py and my_package/tool_name.py.

2. In my_package/tool_name.py, a ToolClassName that inherits from ExternalTool.

After running pip install on the package, it should be readily available in PyDM.