Global: Example addons

openpype/modules/README.md

@@ -1,125 +1,143 @@
 # OpenPype modules/addons
-OpenPype modules should contain separated logic of specific kind of implementation, like Ftrack connection and usage code or Deadline farm rendering or may contain only special plugins. Addons work the same way currently there is no difference in module and addon.
+OpenPype modules should contain separated logic of specific kind of implementation, such as Ftrack connection and its usage code, Deadline farm rendering or may contain only special plugins. Addons work the same way currently, there is no difference between module and addon functionality.
 
 ## Modules concept
-- modules and addons are dynamically imported to virtual python module `openpype_modules` from which it is possible to import them no matter where is the modulo located
-- modules or addons should never be imported directly even if you know possible full import path
-  - it is because all of their content must be imported in specific order and should not be imported without defined functions as it may also break few implementation parts
+- modules and addons are dynamically imported to virtual python module `openpype_modules` from which it is possible to import them no matter where is the module located
+- modules or addons should never be imported directly, even if you know possible full import path
+ - it is because all of their content must be imported in specific order and should not be imported without defined functions as it may also break few implementation parts
 
 ### TODOs
 - add module/addon manifest
- - definition of module (not 100% defined content e.g. minimum require OpenPype version etc.)
- - defying that folder is content of a module or an addon
-- module/addon have it's settings schemas and default values outside OpenPype
-- add general setting of paths to modules
+ - definition of module (not 100% defined content e.g. minimum required OpenPype version etc.)
+ - defining a folder as a content of a module or an addon
 
 ## Base class `OpenPypeModule`
 - abstract class as base for each module
-- implementation should be module's api withou GUI parts
-- may implement `get_global_environments` method which should return dictionary of environments that are globally appliable and value is the same for whole studio if launched at any workstation (except os specific paths)
+- implementation should contain module's api without GUI parts
+- may implement `get_global_environments` method which should return dictionary of environments that are globally applicable and value is the same for whole studio if launched at any workstation (except os specific paths)
 - abstract parts:
-  - `name` attribute - name of a module
-  - `initialize` method - method for own initialization of a module (should not override `__init__`)
-  - `connect_with_modules` method - where module may look for it's interfaces implementations or check for other modules
-- `__init__` should not be overriden and `initialize` should not do time consuming part but only prepare base data about module
-  - also keep in mind that they may be initialized in headless mode
+ - `name` attribute - name of a module
+ - `initialize` method - method for own initialization of a module (should not override `__init__`)
+ - `connect_with_modules` method - where module may look for it's interfaces implementations or check for other modules
+- `__init__` should not be overridden and `initialize` should not do time consuming part but only prepare base data about module
+ - also keep in mind that they may be initialized in headless mode
 - connection with other modules is made with help of interfaces
 
+## Addon class `OpenPypeAddOn`
+- inherits from `OpenPypeModule` but is enabled by default and doesn't have to implement `initialize` and `connect_with_modules` methods
+ - that is because it is expected that addons don't need to have system settings and `enabled` value on it (but it is possible...)
+
+## How to add addons/modules
+- in System settings go to `modules/addon_paths` (`Modules/OpenPype AddOn Paths`) where you have to add path to addon root folder
+- for openpype example addons use `{OPENPYPE_REPOS_ROOT}/openpype/modules/example_addons`
+
+## Addon/module settings
+- addons/modules may have defined custom settings definitions with default values
+- it is based on settings type `dynamic_schema` which has `name`
+ - that item defines that it can be replaced dynamically with any schemas from module or module which won't be saved to openpype core defaults
+ - they can't be added to any schema hierarchy
+ - item must not be in settings group (under overrides) or in dynamic item (e.g. `list` of `dict-modifiable`)
+ - addons may define it's dynamic schema items
+- they can be defined with class which inherits from `BaseModuleSettingsDef`
+ - it is recommended to use pre implemented `JsonFilesSettingsDef` which defined structure and use json files to define dynamic schemas, schemas and default values
+ - check it's docstring and check for `example_addon` in example addons
+- settings definition returns schemas by dynamic schemas names
+
 # Interfaces
-- interface is class that has defined abstract methods to implement and may contain preimplemented helper methods
+- interface is class that has defined abstract methods to implement and may contain pre implemented helper methods
 - module that inherit from an interface must implement those abstract methods otherwise won't be initialized
-- it is easy to find which module object inherited from which interfaces withh 100% chance they have implemented required methods
+- it is easy to find which module object inherited from which interfaces with 100% chance they have implemented required methods
 - interfaces can be defined in `interfaces.py` inside module directory
-  - the file can't use relative imports or import anything from other parts
-  of module itself at the header of file
-  - this is one of reasons why modules/addons can't be imported directly without using defined functions in OpenPype modules implementation
+ - the file can't use relative imports or import anything from other parts
+ of module itself at the header of file
+ - this is one of reasons why modules/addons can't be imported directly without using defined functions in OpenPype modules implementation
 
 ## Base class `OpenPypeInterface`
 - has nothing implemented
 - has ABCMeta as metaclass
 - is defined to be able find out classes which inherit from this base to be
-  able tell this is an Interface
+ able tell this is an Interface
 
 ## Global interfaces
 - few interfaces are implemented for global usage
 
 ### IPluginPaths
-- module want to add directory path/s to avalon or publish plugins
+- module wants to add directory path/s to avalon or publish plugins
 - module must implement `get_plugin_paths` which must return dictionary with possible keys `"publish"`, `"load"`, `"create"` or `"actions"`
-  - each key may contain list or string with path to directory with plugins
+ - each key may contain list or string with a path to directory with plugins
 
 ### ITrayModule
-- module has more logic when used in tray
-  - it is possible that module can be used only in tray
+- module has more logic when used in a tray
+ - it is possible that module can be used only in the tray
 - abstract methods
-  - `tray_init` - initialization triggered after `initialize` when used in `TrayModulesManager` and before `connect_with_modules`
-  - `tray_menu` - add actions to tray widget's menu that represent the module
-  - `tray_start` - start of module's login in tray
-  - module is initialized and connected with other modules
-  - `tray_exit` - module's cleanup like stop and join threads etc.
-  - order of calling is based on implementation this order is how it works with `TrayModulesManager`
-  - it is recommended to import and use GUI implementaion only in these methods
+ - `tray_init` - initialization triggered after `initialize` when used in `TrayModulesManager` and before `connect_with_modules`
+ - `tray_menu` - add actions to tray widget's menu that represent the module
+ - `tray_start` - start of module's login in tray
+ - module is initialized and connected with other modules
+ - `tray_exit` - module's cleanup like stop and join threads etc.
+ - order of calling is based on implementation this order is how it works with `TrayModulesManager`
+ - it is recommended to import and use GUI implementation only in these methods
 - has attribute `tray_initialized` (bool) which is set to False by default and is set by `TrayModulesManager` to True after `tray_init`
-  - if module has logic only in tray or for both then should be checking for `tray_initialized` attribute to decide how should handle situations
+ - if module has logic only in tray or for both then should be checking for `tray_initialized` attribute to decide how should handle situations
 
 ### ITrayService
-- inherit from `ITrayModule` and implement `tray_menu` method for you
-  - add action to submenu "Services" in tray widget menu with icon and label
-- abstract atttribute `label`
-  - label shown in menu
-- interface has preimplemented methods to change icon color
-  - `set_service_running` - green icon
-  - `set_service_failed` - red icon
-  - `set_service_idle` - orange icon
-  - these states must be set by module itself `set_service_running` is default state on initialization
+- inherits from `ITrayModule` and implements `tray_menu` method for you
+ - adds action to submenu "Services" in tray widget menu with icon and label
+- abstract attribute `label`
+ - label shown in menu
+- interface has pre implemented methods to change icon color
+ - `set_service_running` - green icon
+ - `set_service_failed` - red icon
+ - `set_service_idle` - orange icon
+ - these states must be set by module itself `set_service_running` is default state on initialization
 
 ### ITrayAction
-- inherit from `ITrayModule` and implement `tray_menu` method for you
-  - add action to tray widget menu with label
-- abstract atttribute `label`
-  - label shown in menu
+- inherits from `ITrayModule` and implements `tray_menu` method for you
+ - adds action to tray widget menu with label
+- abstract attribute `label`
+ - label shown in menu
 - abstract method `on_action_trigger`
-  - what should happen when action is triggered
-- NOTE: It is good idea to implement logic in `on_action_trigger` to api method and trigger that methods on callbacks this gives ability to trigger that method outside tray
+ - what should happen when an action is triggered
+- NOTE: It is a good idea to implement logic in `on_action_trigger` to the api method and trigger that method on callbacks. This gives ability to trigger that method outside tray
 
 ## Modules interfaces
-- modules may have defined their interfaces to be able recognize other modules that would want to use their features
--
+- modules may have defined their own interfaces to be able to recognize other modules that would want to use their features
+
 ### Example:
-- Ftrack module has `IFtrackEventHandlerPaths` which helps to tell Ftrack module which of other modules want to add paths to server/user event handlers
-  - Clockify module use `IFtrackEventHandlerPaths` and return paths to clockify ftrack synchronizers
+- Ftrack module has `IFtrackEventHandlerPaths` which helps to tell Ftrack module which other modules want to add paths to server/user event handlers
+ - Clockify module use `IFtrackEventHandlerPaths` and returns paths to clockify ftrack synchronizers
 
-- Clockify has more inharitance it's class definition looks like
+- Clockify inherits from more interfaces. It's class definition looks like:
 ```
 class ClockifyModule(
-  OpenPypeModule, # Says it's Pype module so ModulesManager will try to initialize.
-  ITrayModule, # Says has special implementation when used in tray.
-  IPluginPaths, # Says has plugin paths that want to register (paths to clockify actions for launcher).
-  IFtrackEventHandlerPaths, # Says has Ftrack actions/events for user/server.
-  ITimersManager # Listen to other modules with timer and can trigger changes in other module timers through `TimerManager` module.
+ OpenPypeModule, # Says it's Pype module so ModulesManager will try to initialize.
+ ITrayModule, # Says has special implementation when used in tray.
+ IPluginPaths, # Says has plugin paths that want to register (paths to clockify actions for launcher).
+ IFtrackEventHandlerPaths, # Says has Ftrack actions/events for user/server.
+ ITimersManager # Listen to other modules with timer and can trigger changes in other module timers through `TimerManager` module.
 ):
 ```
 
 ### ModulesManager
-- collect module classes and tries to initialize them
+- collects module classes and tries to initialize them
 - important attributes
-  - `modules` - list of available attributes
-  - `modules_by_id` - dictionary of modules mapped by their ids
-  - `modules_by_name` - dictionary of modules mapped by their names
-  - all these attributes contain all found modules even if are not enabled
+ - `modules` - list of available attributes
+ - `modules_by_id` - dictionary of modules mapped by their ids
+ - `modules_by_name` - dictionary of modules mapped by their names
+ - all these attributes contain all found modules even if are not enabled
 - helper methods
-  - `collect_global_environments` to collect all global environments from enabled modules with calling `get_global_environments` on each of them
-  - `collect_plugin_paths` collect plugin paths from all enabled modules
-  - output is always dictionary with all keys and values as list
-  ```
-  {
-  "publish": [],
-  "create": [],
-  "load": [],
-  "actions": []
-  }
-  ```
+ - `collect_global_environments` to collect all global environments from enabled modules with calling `get_global_environments` on each of them
+ - `collect_plugin_paths` collects plugin paths from all enabled modules
+ - output is always dictionary with all keys and values as an list
+ ```
+ {
+ "publish": [],
+ "create": [],
+ "load": [],
+ "actions": []
+ }
+ ```
 
 ### TrayModulesManager
-- inherit from `ModulesManager`
-- has specific implementations for Pype Tray tool and handle `ITrayModule` methods
+- inherits from `ModulesManager`
+- has specific implementation for Pype Tray tool and handle `ITrayModule` methods

openpype/modules/base.py

@@ -495,6 +495,7 @@ def initialize_modules(self):
  if (
  not inspect.isclass(modules_item)
  or modules_item is OpenPypeModule
+ or modules_item is OpenPypeAddOn
  or not issubclass(modules_item, OpenPypeModule)
  ):
  continue

openpype/modules/example_addons/example_addon/__init__.py

@@ -0,0 +1,15 @@
+""" Addon class definition and Settings definition must be imported here.
+
+If addon class or settings definition won't be here their definition won't
+be found by OpenPype discovery.
+"""
+
+from .addon import (
+ AddonSettingsDef,
+ ExampleAddon
+)
+
+__all__ = (
+ "AddonSettingsDef",
+ "ExampleAddon"
+)

openpype/modules/example_addons/example_addon/addon.py

@@ -0,0 +1,132 @@
+"""Addon definition is located here.
+
+Import of python packages that may not be available should not be imported
+in global space here until are required or used.
+- Qt related imports
+- imports of Python 3 packages
+ - we still support Python 2 hosts where addon definition should available
+"""
+
+import os
+
+from openpype.modules import (
+ JsonFilesSettingsDef,
+ OpenPypeAddOn
+)
+# Import interface defined by this addon to be able find other addons using it
+from openpype_interfaces import (
+ IExampleInterface,
+ IPluginPaths,
+ ITrayAction
+)
+
+
+# Settings definition of this addon using `JsonFilesSettingsDef`
+# - JsonFilesSettingsDef is prepared settings definition using json files
+# to define settings and store default values
+class AddonSettingsDef(JsonFilesSettingsDef):
+ # This will add prefixes to every schema and template from `schemas`
+ # subfolder.
+ # - it is not required to fill the prefix but it is highly
+ # recommended as schemas and templates may have name clashes across
+ # multiple addons
+ # - it is also recommended that prefix has addon name in it
+ schema_prefix = "example_addon"
+
+ def get_settings_root_path(self):
+ """Implemented abstract class of JsonFilesSettingsDef.
+
+ Return directory path where json files defying addon settings are
+ located.
+ """
+ return os.path.join(
+ os.path.dirname(os.path.abspath(__file__)),
+ "settings"
+ )
+
+
+class ExampleAddon(OpenPypeAddOn, IPluginPaths, ITrayAction):
+ """This Addon has defined it's settings and interface.
+
+ This example has system settings with an enabled option. And use
+ few other interfaces:
+ - `IPluginPaths` to define custom plugin paths
+ - `ITrayAction` to be shown in tray tool
+ """
+ label = "Example Addon"
+ name = "example_addon"
+
+ def initialize(self, settings):
+ """Initialization of addon."""
+ module_settings = settings[self.name]
+ # Enabled by settings
+ self.enabled = module_settings.get("enabled", False)
+
+ # Prepare variables that can be used or set afterwards
+ self._connected_modules = None
+ # UI which must not be created at this time
+ self._dialog = None
+
+ def tray_init(self):
+ """Implementation of abstract method for `ITrayAction`.
+
+ We're definitely in tray tool so we can pre create dialog.
+ """
+
+ self._create_dialog()
+
+ def connect_with_modules(self, enabled_modules):
+ """Method where you should find connected modules.
+
+ It is triggered by OpenPype modules manager at the best possible time.
+ Some addons and modules may required to connect with other modules
+ before their main logic is executed so changes would require to restart
+ whole process.
+ """
+ self._connected_modules = []
+ for module in enabled_modules:
+ if isinstance(module, IExampleInterface):
+ self._connected_modules.append(module)
+
+ def _create_dialog(self):
+ # Don't recreate dialog if already exists
+ if self._dialog is not None:
+ return
+
+ from .widgets import MyExampleDialog
+
+ self._dialog = MyExampleDialog()
+
+ def show_dialog(self):
+ """Show dialog with connected modules.
+
+ This can be called from anywhere but can also crash in headless mode.
+ There is no way to prevent addon to do invalid operations if he's
+ not handling them.
+ """
+ # Make sure dialog is created
+ self._create_dialog()
+ # Change value of dialog by current state
+ self._dialog.set_connected_modules(self.get_connected_modules())
+ # Show dialog
+ self._dialog.open()
+
+ def get_connected_modules(self):
+ """Custom implementation of addon."""
+ names = set()
+ if self._connected_modules is not None:
+ for module in self._connected_modules:
+ names.add(module.name)
+ return names
+
+ def on_action_trigger(self):
+ """Implementation of abstract method for `ITrayAction`."""
+ self.show_dialog()
+
+ def get_plugin_paths(self):
+ """Implementation of abstract method for `IPluginPaths`."""
+ current_dir = os.path.dirname(os.path.abspath(__file__))
+
+ return {
+ "publish": [os.path.join(current_dir, "plugins", "publish")]
+ }