API

This page contains the full reference to HookMan API.

HookMan

class hookman.hooks.HookMan(*, specs, plugin_dirs)

Main class of HookMan, this class holds all the information related to the plugins

get_hook_caller(ignored_plugins=())

Return a HookCaller class that holds all references for the functions implemented on the plugins.

When informed, the ignored_plugins must be a list with the names of the plugins (same as shared_lib_name) instead of the plugin caption.

get_plugins_available(ignored_plugins=())

Return a list of PluginInfo that are available on plugins_dirs

Optionally you can pass a list of plugins that should be ignored. When informed, the ignored_plugins must be a list with the names of the plugins (same as shared_lib_name) instead of the plugin caption.

The PluginInfo is a object that holds all information related to the plugin.

Return type:

Optional[List[PluginInfo]]

install_plugin(plugin_file_path, dest_path)

Extract the content of the zip file into dest_path. If the installation occurs successfully the name of the installed plugin will be returned.

The following checks will be executed to validate the consistency of the inputs:

1. The destination Path should be one of the paths informed during the initialization of HookMan (plugins_dirs field).

2. The plugins_dirs cannot have two plugins with the same name.

Plugin_file_path:

The Path for the .hmplugin

Dest_path:

The destination to where the plugin should be placed.

Return type:

str

remove_plugin(caption)

This method receives the name of the plugin as input, and will remove completely the plugin from plugin_dirs.

Caption:

Name of the plugin to be removed

HookSpecs

class hookman.hooks.HookSpecs(*, project_name, version, pyd_name=None, hooks, extra_includes=())

A class that holds the specification of the hooks, currently the following specification are available:

Parameters:

• project_name – This field will be used to identify the project and to name the hook functions. This is usually a project name in a user-friendly format, such as “My Project”.

• version (str) – The current version of the spec, when a new hook is created or modified this version should be changed.

• pyd_name (str) – Base name of the shared library for the bindings for the HookCaller class. If None, no bindings will be generated.

• hooks (List[function]) – A list with the hooks available for the project, each hook is a python function with type annotations.

• extra_includes (List[str]) – Extra #include directives that will be added to the generated HookCaller.hpp file.

PluginInfo

class hookman.plugin_config.PluginInfo(yaml_location, hooks_available)

Class that holds all information related to the plugin with some auxiliary methods

classmethod is_implemented_on_plugin(plugin_dll, hook_name)

Check if the given function name is available on the plugin_dll informed

Note

The hook_name should be the full name of the hook

Ex.: {project}_{version}_{hook_name} -> hookman_v4_friction_factor

Return type:

bool

classmethod validate_plugin_file(plugin_file_zip)

Check if the given plugin_file is valid, currently the only check that this method do is to verify if the id is available

HookManGenerator

class hookman.hookman_generator.HookManGenerator(hook_spec_file_path)

Class to assist in the process of creating necessary files for the hookman

generate_hook_specs_header(plugin_id, dst_path)

Generates the “hook_specs.h” file which is consumed by plugins to implement the hooks.

Parameters:

• plugin_id (str) – short name of the generated shared library

• dst_path (Union[str, Path]) – directory where to generate the file.

generate_plugin_package(package_name, plugin_dir, dst_path=None, extras_defaults=None, package_name_suffix=None)

Creates a .hmplugin file using the name provided on package_name argument. The file .hmplugin will be created with the content from the folder assets and artifacts.

In order to successfully creates a plugin, at least the following files should be present:

• plugin.yml

• shared library (.ddl or .so)

• readme.md

Per default, the package will be created inside the folder plugin_dir, however it’s possible to give another path filling the dst argument

Parameters:

• extras_defaults (Dict[str,str]) – (key, value) entries to be added to “extras” if not defined by the original input yaml.

• package_name_suffix (Optional[str]) – If not None this string is inserted after the plugin version in the filename.

generate_plugin_template(caption, plugin_id, author_email, author_name, dst_path, extra_includes=None, extra_body_lines=None, exclude_hooks=None, extras=None)

Generate a template with the necessary files and structure to create a plugin

Parameters:

caption (str) – the user-friendly name of the plugin, for example "Hydrates".

A folder with the same name as the plugin_id argument will be created, with the following files:

<plugin_folder>

• CMakeLists.txt

• compile.py

assets/

• plugin.yaml

• README.md

src/

• hook_specs.h

• {plugin_id}.cpp

• CMakeLists.txt

Parameters:

• extra_includes (Optional[List[str]]) – Extras include to be added on {plugin_id}.cpp as “default”, as an example is the includes for a SDK.

• extra_body_lines (Optional[List[str]]) – Extras lines to be added on {plugin_id}.cpp on the body, used for default implementations of hooks

• exclude_hooks (Optional[List[str]]) – List of hooks, that will not be inserted on the {plugin_id}.cpp

generate_project_files(dst_path)

Generate the following files on the dst_path: - HookCaller.hpp - HookCallerPython.cpp

Exception

exception hookman.exceptions.ArtifactsDirNotFoundError

Exception raised when the artifacts folder it’s not found on the root of the plugin folder

exception hookman.exceptions.AssetsDirNotFoundError

Exception raised when the assets folder it’s not found on the root of the plugin folder

exception hookman.exceptions.HookmanError

Base class for all hookman exceptions.

exception hookman.exceptions.InvalidDestinationPathError

Exception raised when the destination path to install the plugin is not one of the paths used by HookMan to find plugins already installed.

exception hookman.exceptions.PluginAlreadyInstalledError

Exception raise when a folder with the same name of the plugin already is placed on the destination folder informed.

exception hookman.exceptions.SharedLibraryNotFoundError

Exception raise when the file informed doesn’t contain a correct shared library Ex.: The user informed a linux plugin on a Windows application.