Plugins can now yield PluginExit events.

Author: GraylinKim

docs/source/articles/creatingagameengineplugin.rst

@@ -0,0 +1,84 @@
+Creating a GameEngine Plugin
+================================
+
+Handling Events
+--------------------
+
+Plugins can opt in to handle events with methods with the following naming convention::
+
+	def handleEventName(self, event, replay)
+
+In addition to handling specific event types, plugins can also handle events more generally by handling built-in parent classes from the list below:
+
+* handleEvent - called for every single event of all types
+* handleMessageEvent - called for events in replay.message.events
+* handleGameEvent - called for events in replay.game.events
+* handleTrackerEvent - called for events in replay.tracker.events
+* handlePlayerActionEvent - called for all game events indicating player actions
+* handleAbilityEvent - called for all types of ability events
+* handleHotkeyEvent - called for all player hotkey events
+
+For every event in a replay, the GameEngine will loop over all of its registered plugins looking for functions to handle that event. Matching handlers are called in order of plugin registration from most general to most specific.
+
+Given the following plugins::
+
+    class Plugin1():
+        def handleAbilityEvent(self, event, replay):
+            pass
+
+    class Plugin2():
+        def handleEvent(self, event, replay):
+            pass
+
+        def handleTargetAbilityEvent(self, event, replay):
+            pass
+
+An engine handling a ``TargetAbilityEvent`` would call handlers in the following order::
+
+    Plugin1.handleAbilityEvent(event, replay)
+    Plugin2.handleEvent(event, replay)
+    Plugin2.handleTargetAbilityEvent(event, replay)
+
+Setup and Cleanup
+---------------------
+
+Plugins may also handle special ``InitGame`` and ``EndGame`` events. These handlers for these events are called directly before and after the processing of the replay events:
+
+* handleInitGame - is called prior to processing a new replay to provide
+  an opportunity for the plugin to clear internal state and set up any
+  replay state necessary.
+
+* handleEndGame - is called after all events have been processed and
+  can be used to perform post processing on aggrated data or clean up
+  intermediate data caches.
+
+Message Passing
+--------------------
+
+Event handlers can choose to ``yield`` additional events which will be injected into the event stream directly after the event currently being processed. This feature allows for message passing between plugins. An ExpansionTracker plugin could notify all other plugins of a new ExpansionEvent that they could opt to process::
+
+	def handleUnitDoneEvent(self, event, replay):
+		if event.unit.name == 'Nexus':
+			yield ExpansionEvent(event.frame, event.unit)
+		...
+
+Early Exits
+--------------------
+
+If a plugin wishes to stop processing a replay it can yield a PluginExit event::
+
+	def handleEvent(self, event, replay):
+		if len(replay.tracker_events) == 0:
+			yield PluginExit(self, code=0, details=dict(msg="tracker events required"))
+		...
+
+	def handleAbilityEvent(self, event, replay):
+		try:
+			possibly_throwing_error()
+		catch Error as e:
+			logger.error(e)
+			yield PluginExit(self, code=0, details=dict(msg="Unexpected exception"))
+
+The GameEngine will intercept this event and remove the plugin from the list of active plugins for this replay. The exit code and details will be available from the replay::
+
+	code, details = replay.plugins['MyPlugin']

sc2reader/engine/__init__.py

@@ -2,7 +2,8 @@
 from __future__ import absolute_import, print_function, unicode_literals, division
 
 import sys
-from sc2reader.engine.engine import GameEngine
+from sc2reader.engine.engine import GameEngine, PluginExit
+from sc2reader.engine.utils import GameState
 from sc2reader.engine.plugins.apm import APMTracker
 from sc2reader.engine.plugins.selection import SelectionTracker
 from sc2reader.engine.plugins.context import ContextLoader

sc2reader/engine/engine.py

@@ -13,6 +13,15 @@ class EndGameEvent(object):
     name = 'EndGame'
 
 
+class PluginExit(object):
+    name = 'PluginExit'
+
+    def __init__(self, plugin, code=0, details=None):
+        self.plugin = plugin
+        self.code = code
+        self.details = details or {}
+
+
 class GameEngine(object):
     """ GameEngine Specification
         --------------------------
@@ -80,8 +89,35 @@ def handleEventName(self, event, replay)
             intermediate data caches.
 
         Event handlers can choose to ``yield`` additional events which will be injected
-        into the event stream directly after the event currently being processed. This is
-        a great way to send messages to downstream plugins.
+        into the event stream directly after the event currently being processed. This
+        feature allows for message passing between plugins. An ExpansionTracker plugin
+        could notify all other plugins of a new ExpansionEvent that they could opt to
+        process::
+
+            def handleUnitDoneEvent(self, event, replay):
+                if event.unit.name == 'Nexus':
+                    yield ExpansionEvent(event.frame, event.unit)
+                ....
+
+        If a plugin wishes to stop processing a replay it can yield a PluginExit event::
+
+            def handleEvent(self, event, replay):
+                if len(replay.tracker_events) == 0:
+                    yield PluginExit(self, code=0, details=dict(msg="tracker events required"))
+                ...
+
+            def handleAbilityEvent(self, event, replay):
+                try:
+                    possibly_throwing_error()
+                catch Error as e:
+                    logger.error(e)
+                    yield PluginExit(self, code=0, details=dict(msg="Unexpected exception"))
+
+        The GameEngine will intercept this event and remove the plugin from the list of
+        active plugins for this replay. The exit code and details will be available from the
+        replay::
+
+            code, details = replay.plugins['MyPlugin']
     """
     def __init__(self, plugins=[]):
         self._plugins = list()
@@ -102,6 +138,13 @@ def run(self, replay):
         # ranked from most generic to most specific
         handlers = dict()
 
+        # Create a local copy of the plugins list. As plugins exit we can
+        # remove them from this list and regenerate event handlers.
+        plugins = list(self._plugins)
+
+        # Create a dict for storing plugin exit codes and details
+        replay.plugins = dict()
+
         # Fill event event queue with the replay events, bookmarked by Init and End events.
         event_queue = collections.deque()
         event_queue.append(InitGameEvent())
@@ -113,9 +156,15 @@ def run(self, replay):
         while len(event_queue) > 0:
             event = event_queue.popleft()
 
+            if event.name == 'PluginExit':
+                # Remove the plugin and reset the handlers.
+                plugins.remove(event.plugin)
+                handlers.clear()
+                replay.plugins[event.plugin.name] = (event.code, event.details)
+
             # If we haven't compiled a list of handlers for this event yet, do so!
             if event.name not in handlers:
-                event_handlers = self._get_event_handlers(event)
+                event_handlers = self._get_event_handlers(event, plugins)
                 handlers[event.name] = event_handlers
             else:
                 event_handlers = handlers[event.name]
@@ -130,8 +179,13 @@ def run(self, replay):
             # need to reverse the list first to have them added in order.
             event_queue.extendleft(new_events)
 
-    def _get_event_handlers(self, event):
-        return sum([self._get_plugin_event_handlers(plugin, event) for plugin in self._plugins], [])
+        # For any plugins that didn't yield a PluginExit event, record a successful
+        # completion.
+        for plugin in plugins:
+            replay.plugins[plugin.name] = (0, dict())
+
+    def _get_event_handlers(self, event, plugins):
+        return sum([self._get_plugin_event_handlers(plugin, event) for plugin in plugins], [])
 
     def _get_plugin_event_handlers(self, plugin, event):
         handlers = list()

sc2reader/engine/plugins/apm.py

@@ -15,6 +15,7 @@ class APMTracker(object):
 
     APM is 0 for games under 1 minute in length.
     """
+    name = 'APMTracker'
 
     def handleInitGame(self, event, replay):
         for player in replay.players:

sc2reader/engine/plugins/context.py

@@ -8,6 +8,7 @@
 
 @loggable
 class ContextLoader(object):
+    name='ContextLoader'
 
     def handleInitGame(self, event, replay):
         replay.units = set()

sc2reader/engine/plugins/selection.py

@@ -23,6 +23,8 @@ class SelectionTracker(object):
 
         # TODO: list a few error inducing sitations
     """
+    name = 'SelectionTracker'
+
     def handleInitGame(self, event, replay):
         for person in replay.entities:
             person.selection = dict()

test_replays/test_all.py

@@ -297,6 +297,10 @@ def test_engine_plugins(self):
             ])
         )
 
+        code, details = replay.plugins['ContextLoader']
+        self.assertEqual(code, 0)
+        self.assertEqual(details, dict())
+
     def test_factory_plugins(self):
         from sc2reader.factories.plugins.replay import APMTracker, SelectionTracker, toJSON