Format and document hooks.py

Author: theotherjimmy

tools/hooks.py

@@ -1,45 +1,48 @@
-# Configurable hooks in the build system. Can be used by various platforms
-# to customize the build process.
+""" Configurable hooks in the build system. Can be used by various platforms
+to customize the build process.
+"""
 
 ################################################################################
 # Hooks for the various parts of the build process
 
 # Internal mapping of hooks per tool
-_hooks = {}
+_HOOKS = {}
 
 # Internal mapping of running hooks
-_running_hooks = {}
+_RUNNING_HOOKS = {}
 
 # Available hook types
-_hook_types = ["binary", "compile", "link", "assemble"]
+_HOOK_TYPES = ["binary", "compile", "link", "assemble"]
 
 # Available hook steps
-_hook_steps = ["pre", "replace", "post"]
+_HOOK_STEPS = ["pre", "replace", "post"]
 
 # Hook the given function. Use this function as a decorator
 def hook_tool(function):
+    """Decorate a function as a tool that may be hooked"""
     tool = function.__name__
     tool_flag = "_" + tool + "_done"
     def wrapper(t_self, *args, **kwargs):
+        """The hooked function itself"""
         # if a hook for this tool is already running, it's most likely
         # coming from a derived class, so don't hook the super class version
-        if _running_hooks.get(tool, False):
+        if _RUNNING_HOOKS.get(tool, False):
             return function(t_self, *args, **kwargs)
-        _running_hooks[tool] = True
+        _RUNNING_HOOKS[tool] = True
         # If this tool isn't hooked, return original function
-        if not _hooks.has_key(tool):
+        if not _HOOKS.has_key(tool):
             res = function(t_self, *args, **kwargs)
-            _running_hooks[tool] = False
+            _RUNNING_HOOKS[tool] = False
             return res
-        tooldesc = _hooks[tool]
+        tooldesc = _HOOKS[tool]
         setattr(t_self, tool_flag, False)
         # If there is a replace hook, execute the replacement instead
         if tooldesc.has_key("replace"):
             res = tooldesc["replace"](t_self, *args, **kwargs)
         # If the replacement has set the "done" flag, exit now
         # Otherwise continue as usual
         if getattr(t_self, tool_flag, False):
-            _running_hooks[tool] = False
+            _RUNNING_HOOKS[tool] = False
             return res
         # Execute pre-function before main function if specified
         if tooldesc.has_key("pre"):
@@ -49,76 +52,162 @@ def wrapper(t_self, *args, **kwargs):
         # Execute post-function after main function if specified
         if tooldesc.has_key("post"):
             post_res = tooldesc["post"](t_self, *args, **kwargs)
-            _running_hooks[tool] = False
+            _RUNNING_HOOKS[tool] = False
             return post_res or res
         else:
-            _running_hooks[tool] = False
+            _RUNNING_HOOKS[tool] = False
             return res
     return wrapper
 
-class Hook:
+class Hook(object):
+    """A compiler class that may be hooked"""
     def __init__(self, target, toolchain):
-        _hooks.clear()
+        _HOOKS.clear()
         self._cmdline_hooks = {}
         self.toolchain = toolchain
         target.init_hooks(self, toolchain.__class__.__name__)
 
     # Hook various functions directly
-    def _hook_add(self, hook_type, hook_step, function):
-        if not hook_type in _hook_types or not hook_step in _hook_steps:
+    @staticmethod
+    def _hook_add(hook_type, hook_step, function):
+        """Add a hook to a compile function
+
+        Positional arguments:
+        hook_type - one of the _HOOK_TYPES
+        hook_step - one of the _HOOK_STEPS
+        function - the function to add to the list of hooks
+        """
+        if hook_type not in _HOOK_TYPES or hook_step not in _HOOK_STEPS:
             return False
-        if not hook_type in _hooks:
-            _hooks[hook_type] = {}
-        _hooks[hook_type][hook_step] = function
+        if hook_type not in _HOOKS:
+            _HOOKS[hook_type] = {}
+        _HOOKS[hook_type][hook_step] = function
         return True
 
     def hook_add_compiler(self, hook_step, function):
+        """Add a hook to the compiler
+
+        Positional Arguments:
+        hook_step - one of the _HOOK_STEPS
+        function - the function to add to the list of hooks
+        """
         return self._hook_add("compile", hook_step, function)
 
     def hook_add_linker(self, hook_step, function):
+        """Add a hook to the linker
+
+        Positional Arguments:
+        hook_step - one of the _HOOK_STEPS
+        function - the function to add to the list of hooks
+        """
         return self._hook_add("link", hook_step, function)
 
     def hook_add_assembler(self, hook_step, function):
+        """Add a hook to the assemble
+
+        Positional Arguments:
+        hook_step - one of the _HOOK_STEPS
+        function - the function to add to the list of hooks
+        """
         return self._hook_add("assemble", hook_step, function)
 
     def hook_add_binary(self, hook_step, function):
+        """Add a hook to the elf to binary tool
+
+        Positional Arguments:
+        hook_step - one of the _HOOK_STEPS
+        function - the function to add to the list of hooks
+        """
         return self._hook_add("binary", hook_step, function)
 
     # Hook command lines
     def _hook_cmdline(self, hook_type, function):
-        if not hook_type in _hook_types:
+        """Add a hook to a command line function
+
+        Positional arguments:
+        hook_type - one of the _HOOK_TYPES
+        function - the function to add to the list of hooks
+        """
+        if hook_type not in _HOOK_TYPES:
             return False
         self._cmdline_hooks[hook_type] = function
         return True
 
     def hook_cmdline_compiler(self, function):
+        """Add a hook to the compiler command line
+
+        Positional arguments:
+        function - the function to call
+        """
         return self._hook_cmdline("compile", function)
 
     def hook_cmdline_linker(self, function):
+        """Add a hook to the linker command line
+
+        Positional arguments:
+        function - the function to call
+        """
         return self._hook_cmdline("link", function)
 
     def hook_cmdline_assembler(self, function):
+        """Add a hook to the assembler command line
+
+        Positional arguments:
+        function - the function to call
+        """
         return self._hook_cmdline("assemble", function)
 
     def hook_cmdline_binary(self, function):
+        """Add a hook to the elf to bin tool command line
+
+        Positional arguments:
+        function - the function to call
+        """
         return self._hook_cmdline("binary", function)
 
     # Return the command line after applying the hook
     def _get_cmdline(self, hook_type, cmdline):
+        """Get the command line after running all hooks
+
+        Positional arguments:
+        hook_type - one of the _HOOK_TYPES
+        cmdline - the initial command line
+        """
         if self._cmdline_hooks.has_key(hook_type):
-            cmdline = self._cmdline_hooks[hook_type](self.toolchain.__class__.__name__, cmdline)
+            cmdline = self._cmdline_hooks[hook_type](
+                self.toolchain.__class__.__name__, cmdline)
         return cmdline
 
     def get_cmdline_compiler(self, cmdline):
+        """Get the compiler command line after running all hooks
+
+        Positional arguments:
+        cmdline - the initial command line
+        """
         return self._get_cmdline("compile", cmdline)
 
     def get_cmdline_linker(self, cmdline):
+        """Get the linker command line after running all hooks
+
+        Positional arguments:
+        cmdline - the initial command line
+        """
         return self._get_cmdline("link", cmdline)
 
     def get_cmdline_assembler(self, cmdline):
+        """Get the assmebler command line after running all hooks
+
+        Positional arguments:
+        cmdline - the initial command line
+        """
         return self._get_cmdline("assemble", cmdline)
 
     def get_cmdline_binary(self, cmdline):
+        """Get the binary command line after running all hooks
+
+        Positional arguments:
+        cmdline - the initial command line
+        """
         return self._get_cmdline("binary", cmdline)
 
 ################################################################################