diff options
| -rw-r--r-- | doc/Hooks | 40 | ||||
| -rw-r--r-- | doc/Howto_Write_Plugins | 54 | ||||
| -rw-r--r-- | portato/gui/gtk/windows.py | 2 | ||||
| -rw-r--r-- | portato/gui/gui_helper.py | 4 | ||||
| -rw-r--r-- | portato/gui/qt/windows.py | 2 | ||||
| -rw-r--r-- | portato/plugin.py | 10 |
6 files changed, 108 insertions, 4 deletions
diff --git a/doc/Hooks b/doc/Hooks new file mode 100644 index 0000000..58dabd7 --- /dev/null +++ b/doc/Hooks @@ -0,0 +1,40 @@ +List of hooks currently being supported by Portato +================================================== + +am_i_root +--------- +Called: When checking whether the current user is root (ie. uid == 0). +Parameters: None +Return if override: Boolean signaling whether we are root. + + +emerge: +------- +Called: When emerge or every other command given by e.g. the synccmd preference is being called. +Parameters: + - string[] packages: Packages to emerge (includes "world", "system"). + - string[] command: The exact command to execute. + - portato.gui.wrapper.Console console: The console the output will be written to. + +Return if override: Nothing + + +after_emerge: +------------- +Called: When the emerge process (or other - see emerge hook) is finished. +Parameters: + - string[] packages: The list of cpv's (plus "world", "system") which have been emerged. (Or not if it failed.) + - int retcode: The return code of the command. + +Return if override: Nothing +Comment: This uses an extra hook as emerge is started in an extra thread and thus all plugins being wanting to come "after" will be called while emerge is still running. + +open_ebuild: +------------ +Called: When an ebuild window is opened. +Parameters: + - portato.backend.Package package: The current package whose is going to be displayed. + - Window parent: The parent window. Exact type depends on the frontend. + +Return if override: Window-object which can be called by the frontends. Please see the explicit code to see what is expected. +Comment: If you want to override - do this only for ONE specific frontend. diff --git a/doc/Howto_Write_Plugins b/doc/Howto_Write_Plugins new file mode 100644 index 0000000..660b45b --- /dev/null +++ b/doc/Howto_Write_Plugins @@ -0,0 +1,54 @@ +HowTo Write A Plugin For Portato +================================= + +(NOTE: The XML schema is likely to change in the future.) + +Writing a plugin is (quite) simple. You have to provide a XML file which tells portato how to communicate with the plugin and in most cases a Python module doing the actual work. This howto is not going to cover the writing of the plugin, but only the XML. + +General +------- + +So - how is a plugin is working in general? Portato defines a set of hooks (see the Hooks file for a complete list) to which your plugin can connect. For each hook you have three choices: To connect before, after or instead of the function being hooked. (Of course you can connect several times to one hook ...) The latter one should be used only if you really know what you are doing as it is likely that Portato won't work any longer after this. Also have in mind, that only one plugin can override. Thus: if several plugins want to override one hook, a randomly chosen one will get the allowance. + +For each of the "before" and "after" mode a queue exists, holding the plugins to execute. A plugin is allowed to state another plugin which should be executed after (in "before" mode) or before (in "after" mode) your plugin. The star * exists to note that this should be applied to ALL other plugins. Portato TRIES to satisfy your request... + +When you now have chosen the connect(s) to chose you write an appropriate function (or better: a Python callable) which will be given in the XML-definition to be called by Portato with the hook's arguments. (Hint: All arguments will be passed as keyword parameters. So you can easily pick the ones you need and add a "**kwargs" argument, which will take the rest. As a nice side effect you do not have to reflect any API changes which will come with additional parameters :)). + +Finally: Add an import tag stating the module to import to execute the function(s) given - and you are done. + +Sample XML +---------- + +At the point of writing this, there is no XSD or DTD - so you cannot validate the file. But this will change at some point of time ;). + +<?xml version="1.0" encoding="UTF-8" ?> +<plugin + author="Joe Smith" + name="Some small sample plugin"> + <import>plugins.sample.small</import> + + <hook + hook = "a_hook" + call = "the_calling_function"> + <connect type="after" /> + </hook> +</plugin> + +Notes: + +- The author and name attributes are mandatory. +- If you want to specify a dependency plugin the connect tag has to be like: <connect type = "after"> The other plugin we depend on </connect>. +- It is possible of course to have more than one "hook" tag. + +Additional Tags +--------------- + +Menu: + It is possible, that your plugin gets an entry in the "Plugin"-menu. Therefore you have to provide (one or more) "menu" tags: + <menu label="The Small _Plugin" call = "the_calling_menu_function" /> + + Note, that the underscore in front of a character will make it be underlined in the menu and thus accessible by a shortcut. + +Disabled: + Sometimes you don't want the plugin to be enabled by default but only if the user explicitly says so. This can be archieved by just adding the "disabled" tag: + <disabled /> diff --git a/portato/gui/gtk/windows.py b/portato/gui/gtk/windows.py index 7e4dab2..3ce8ae2 100644 --- a/portato/gui/gtk/windows.py +++ b/portato/gui/gtk/windows.py @@ -750,7 +750,7 @@ class PackageTable: return True def cb_package_ebuild_clicked(self, button): - hook = plugin.hook("open_ebuild", self.actual_package(), self.window) + hook = plugin.hook("open_ebuild", package = self.actual_package(), parent = self.window) hook(EbuildWindow)(self.window, self.actual_package()) return True diff --git a/portato/gui/gui_helper.py b/portato/gui/gui_helper.py index 3c9edce..e827a22 100644 --- a/portato/gui/gui_helper.py +++ b/portato/gui/gui_helper.py @@ -477,9 +477,9 @@ class EmergeQueue: """Calls emerge and updates the terminal. @param options: options to send to emerge - @type options: list + @type options: string[] @param packages: packages to emerge - @type packages: list + @type packages: string[] @param it: Iterators which point to these entries whose children will be removed after completion. @type it: Iterator[] @param command: the command to execute - default is "/usr/bin/python /usr/bin/emerge" diff --git a/portato/gui/qt/windows.py b/portato/gui/qt/windows.py index 7c1726e..3bd9296 100644 --- a/portato/gui/qt/windows.py +++ b/portato/gui/qt/windows.py @@ -509,7 +509,7 @@ class PackageDetails: return self.packages[self.window.versCombo.currentIndex()] def cb_ebuild_clicked (self): - hook = plugin.hook("open_ebuild", self.actual_package(), self.window) + hook = plugin.hook("open_ebuild", package = self.actual_package(), parent = self.window) hook(EbuildDialog)(self.window, self.actual_package()).exec_() def cb_emerge_clicked (self): diff --git a/portato/plugin.py b/portato/plugin.py index 8a54c11..abdf86c 100644 --- a/portato/plugin.py +++ b/portato/plugin.py @@ -10,6 +10,8 @@ # # Written by René 'Necoro' Neumann <necoro@necoro.net> +"""A module containing the management of the plugin system.""" + import os, os.path from xml.dom.minidom import parse @@ -505,11 +507,19 @@ class PluginQueue: __plugins = None def load_plugins(frontend): + """Loads the plugins for a given frontend. + @param frontend: The frontend. See L{constants.FRONTENDS} for the correct list of values. + @type frontend: string""" + global __plugins if __plugins is None or __plugins.frontend != frontend: __plugins = PluginQueue(frontend) def get_plugin_queue(): + """Returns the actual L{PluginQueue}. If it is C{None}, they are not being loaded yet. + + @returns: the actual L{PluginQueue} or C{None} + @rtype: PluginQueue""" return __plugins def hook(hook, *args, **kwargs): |