Plugin hooks (#351)

* Add doc page for plugins
* Add htmlcov to gitignore.
* Schemadef was missing from setup.py.

.gitignore

@@ -5,10 +5,11 @@ dist*
 *.egg-info
 .coverage
 .DS_store
+htmlcov
 
 # Pycharm metadata
 .idea/
 
 # These files are generated, don't put them into source control
 docs/api
-.tox
+.tox

docs/index.rst

@@ -43,11 +43,12 @@ Tutorials
    tutorials/otio-file-format-specification
    tutorials/otio-timeline-structure
    tutorials/time-ranges
-   tutorials/versioning-schemas
-   tutorials/wrapping-otio
    tutorials/write-an-adapter
    tutorials/write-a-media-linker
+   tutorials/write-a-hookscript
    tutorials/write-a-schemadef
+   tutorials/versioning-schemas
+   tutorials/wrapping-otio
 
 Use Cases
 ------------

docs/tutorials/write-a-hookscript.md

@@ -0,0 +1,80 @@
+# Writing a Hook Script
+
+OpenTimelineIO Hook Scripts are plugins that run at predefined points during the execution of various OTIO functions, for example after an adapter has read a file into memory but before the media linker has run.
+
+To write a new hook script, you create a python source file that defines a 
+a function named ``hook_function`` with signature:
+``hook_function :: otio.schema.Timeline, Dict => otio.schema.Timeline``
+
+The first argument is the timeline to process, and the second one is a dictionary of arguments that can be passed to it.  Only one hook function can be defined per python file.
+
+For example:
+```python
+
+def hook_function(tl, arg_dict):
+    for cl in tl.each_clip():
+        cl.metadata['example_hook_function_was_here'] = True
+    return tl
+```
+
+This will insert some extra metadata into each clip.
+
+This plugin can then be registered with the system by configuring a plugin manifest.
+
+## Registering Your Hook Script
+
+To create a new OTIO hook script, you need to create a file myhooks.py. Then add a manifest that points at that python file:
+
+```
+{
+    "OTIO_SCHEMA" : "PluginManifest.1",
+    "hook_scripts" : [
+        {
+            "OTIO_SCHEMA" : "HookScript.1",
+            "name" : "example hook",
+            "execution_scope" : "in process",
+            "filepath" : "example.py"
+        }
+    ],
+    "hooks" : {
+        "pre_adapter_write" : ["example hook"],
+        "post_adapter_read" : []
+    }
+}
+```
+
+The ``hook_scripts`` section will register the plugin with the system, and the ``hooks`` section will attach the scripts to hooks.
+
+Then you need to add this manifest to your `$OTIO_PLUGIN_MANIFEST_PATH` environment variable (which is "`:`" separated).  You may also define media linkers and adapters via the same manifest.
+
+## Running a Hook Script
+
+If you would like to call a hook script from a plugin, the hooks need not be one of the ones that otio pre-defines.  You can have a plugin adapter or media linker, for example, that defines its own hooks and calls your own custom studio specific hook scripts.  To run a hook script from your custom code, you can call:
+
+``otio.hooks.run("some_hook", some_timeline, optional_argument_dict)``
+
+This will call the ``some_hook`` hook script and pass in ``some_timeline`` and ``optional_argument_dict``.
+
+## Order of Hook Scripts
+
+To query which hook scripts are attached to a given hook, you can call:
+
+```
+import opentimelineio as otio
+hook_list = otio.hooks.scripts_attached_to("some_hook") 
+```
+
+Note that ``hook_list`` will be in order of execution.  You can rearrange this list, or edit it to change which scripts will run (or not run) and in which order.
+
+To Edit the order, change the order in the list:
+```
+hook_list[0], hook_list[2] = hook_list[2], hook_list[0]
+print hook_list # ['c','b','a']
+```
+
+Now c will run, then b, then a.
+
+To delete a function the list:
+```
+del hook_list[1]
+```

opentimelineio/__init__.py

@@ -39,7 +39,9 @@
     schema,
     schemadef,
     plugins,
+    media_linker,
     adapters,
+    hooks,
     algorithms,
     test_utils,
     console,

opentimelineio/adapters/adapter.py

@@ -32,6 +32,7 @@
     core,
     plugins,
     media_linker,
+    hooks,
 )
 
 
@@ -134,6 +135,9 @@ def read_from_file(
                 **adapter_argument_map
             )
 
+        # @TODO: pass arguments through?
+        result = hooks.run("post_adapter_read", result)
+
         if media_linker_name and (
             media_linker_name != media_linker.MediaLinkingPolicy.DoNotLinkMedia
         ):
@@ -143,6 +147,9 @@ def read_from_file(
                 media_linker_argument_map
             )
 
+        # @TODO: pass arguments through?
+        result = hooks.run("post_media_linker", result)
+
         return result
 
     def write_to_file(self, input_otio, filepath, **adapter_argument_map):
@@ -152,6 +159,9 @@ def write_to_file(self, input_otio, filepath, **adapter_argument_map):
         a trivial file object wrapper.
         """
 
+        # @TODO: pass arguments through?
+        input_otio = hooks.run("pre_adapter_write", input_otio)
+
         if (
             not self.has_feature("write_to_file") and
             self.has_feature("write_to_string")
@@ -183,6 +193,9 @@ def read_from_string(
             **adapter_argument_map
         )
 
+        # @TODO: pass arguments through?
+        result = hooks.run("post_adapter_read", result)
+
         if media_linker_name and (
             media_linker_name != media_linker.MediaLinkingPolicy.DoNotLinkMedia
         ):
@@ -192,11 +205,18 @@ def read_from_string(
                 media_linker_argument_map
             )
 
+        # @TODO: pass arguments through?
+        # @TODO: Should this run *ONLY* if the media linker ran?
+        result = hooks.run("post_media_linker", result)
+
         return result
 
     def write_to_string(self, input_otio, **adapter_argument_map):
         """Call the write_to_string function on this adapter."""
 
+        # @TODO: pass arguments through?
+        input_otio = hooks.run("pre_adapter_write", input_otio)
+
         return self._execute_function(
             "write_to_string",
             input_otio=input_otio,

opentimelineio/adapters/builtin_adapters.plugin_manifest.json

@@ -22,5 +22,10 @@
             "filepath" : "cmx_3600.py",
             "suffixes" : ["edl"]
         }
-    ]
+    ],
+    "hooks": {
+        "post_adapter_read" : [],
+        "post_media_linker" : [],
+        "pre_adapter_write" : []
+    }
 }

opentimelineio/hooks.py

@@ -0,0 +1,174 @@
+#
+# Copyright 2018 Pixar Animation Studios
+#
+# Licensed under the Apache License, Version 2.0 (the "Apache License")
+# with the following modification; you may not use this file except in
+# compliance with the Apache License and the following modification to it:
+# Section 6. Trademarks. is deleted and replaced with:
+#
+# 6. Trademarks. This License does not grant permission to use the trade
+#    names, trademarks, service marks, or product names of the Licensor
+#    and its affiliates, except as required to comply with Section 4(c) of
+#    the License and to reproduce the content of the NOTICE file.
+#
+# You may obtain a copy of the Apache License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the Apache License with the above modification is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the Apache License for the specific
+# language governing permissions and limitations under the Apache License.
+#
+
+from . import (
+    plugins,
+    core,
+)
+
+__doc__ = """
+HookScripts are plugins that run at defined points ("Hooks").
+
+They expose a hook_function with signature:
+hook_function :: otio.schema.Timeline, Dict -> otio.schema.Timeline
+
+Both hook scripts and the hooks they attach to are defined in the plugin
+manifest.
+
+You can attach multiple hook scripts to a hook.  They will be executed in list
+order, first to last.
+
+They are defined by the manifests HookScripts and hooks areas.
+
+>>>
+{
+    "OTIO_SCHEMA" : "PluginManifest.1",
+    "hook_scripts" : [
+        {
+            "OTIO_SCHEMA" : "HookScript.1",
+            "name" : "example hook",
+            "execution_scope" : "in process",
+            "filepath" : "example.py"
+        }
+    ],
+    "hooks" : {
+        "pre_adapter_write" : ["example hook"],
+        "post_adapter_read" : []
+    }
+}
+
+The 'hook_scripts' area loads the python modules with the 'hook_function's to
+call in them.  The 'hooks' area defines the hooks (and any associated
+scripts).  You can further query and modify these from python.
+
+>>> import opentimelineio as otio
+... hook_list = otio.hooks.scripts_attached_to("some_hook") # -> ['a','b','c']
+...
+... # to run the hook scripts:
+... otio.hooks.run("some_hook", some_timeline, optional_argument_dict)
+
+This will pass (some_timeline, optional_argument_dict) to 'a', which will
+a new timeline that will get passed into 'b' with optional_argument_dict,
+etc.
+
+To Edit the order, change the order in the list:
+
+>>> hook_list[0], hook_list[2] = hook_list[2], hook_list[0]
+... print hook_list # ['c','b','a']
+
+Now c will run, then b, then a.
+
+To delete a function the list:
+
+>>> del hook_list[1]
+"""
+
+
+@core.register_type
+class HookScript(plugins.PythonPlugin):
+    _serializable_label = "HookScript.1"
+
+    def __init__(
+        self,
+        name=None,
+        execution_scope=None,
+        filepath=None,
+    ):
+        """HookScript plugin constructor."""
+
+        plugins.PythonPlugin.__init__(self, name, execution_scope, filepath)
+
+    def run(self, in_timeline, argument_map={}):
+        """Run the hook_function associated with this plugin."""
+
+        # @TODO: should in_timeline be passed in place?  or should a copy be
+        #        made?
+        return self._execute_function(
+            "hook_function",
+            in_timeline=in_timeline,
+            argument_map=argument_map
+        )
+
+    def __str__(self):
+        return "HookScript({}, {}, {})".format(
+            repr(self.name),
+            repr(self.execution_scope),
+            repr(self.filepath)
+        )
+
+    def __repr__(self):
+        return (
+            "otio.hooks.HookScript("
+            "name={}, "
+            "execution_scope={}, "
+            "filepath={}"
+            ")".format(
+                repr(self.name),
+                repr(self.execution_scope),
+                repr(self.filepath)
+            )
+        )
+
+
+def names():
+    """Return a list of all the registered hooks."""
+
+    return plugins.ActiveManifest().hooks.keys()
+
+
+def available_hookscript_names():
+    """Return the names of HookScripts that have been registered."""
+
+    return [hs.name for hs in plugins.ActiveManifest().hook_scripts]
+
+
+def available_hookscripts():
+    """Return the HookScripts objects that have been registered."""
+    return plugins.ActiveManifest().hook_scripts
+
+
+def scripts_attached_to(hook):
+    """Return an editable list of all the hook scriptss that are attached to
+    the specified hook, in execution order.  Changing this list will change the
+    order that scripts run in, and deleting a script will remove it from
+    executing
+    """
+
+    # @TODO: Should this return a copy?
+    return plugins.ActiveManifest().hooks[hook]
+
+
+def run(hook, tl, extra_args=None):
+    """Run all the scripts associated with hook, passing in tl and extra_args.
+
+    Will return the return value of the last hook script.
+
+    If no hookscripts are defined, returns tl.
+    """
+
+    hook_scripts = plugins.ActiveManifest().hooks[hook]
+    for name in hook_scripts:
+        hs = plugins.ActiveManifest().from_name(name, "hook_scripts")
+        tl = hs.run(tl, extra_args)
+    return tl