UbuntuWiki:Upstream/Modules

{{#ifexist: :UbuntuWiki:Upstream/Modules/zh | | {{#ifexist: UbuntuWiki:Upstream/Modules/zh | | {{#ifeq: {{#titleparts:UbuntuWiki:Upstream/Modules|1|-1|}} | zh | | }} }} }} {{#ifeq: {{#titleparts:UbuntuWiki:Upstream/Modules|1|-1|}} | zh | | }}

This page is under cleanup.

Feature Specification for Upstream Submission Modules and the Module Importer

Ryan Zeigler, September 26, 2006

Submission Module Specification:

In order be considered a valid submission module, all submission modules must adhere to the following guidelines.

1. All modules must have the following fields available in the top level

  a. module_name – contains a module name
  b. module_description – contains a brief description of what this module does
  c. module_submit_url – contains the URL that this module submits to (this may or may not be
     identical to the actual url that is used, this is simply for presentation to the user, 
     generally, getting close to the real url should be considered acceptable

1. All submission modules must have at least a single method defined as:

       def execute(email, submission_message, dict_of_logs)

       This function should perform all of the work of actually submitting to a pastebin or whatever submission method is desirehd, and should return a SubmitModuleResult object or a subclass that shall be defined below and shall be defined in the SubmitModule module. The first parameter will contain the user supplied e-mail address, the second parameter will contain the user supplied support message and the third parameter will contain a dict of the form

       ( logname:logcontent_str)

1. The submission module is responsible for formatting the dict_of_logs into whatever form is necessary to submit to the pastebin, or other submission mode. ??? The SubmitModule module will contain a function that can format all of the logs in a dict into a user specified format ???
2. Any .py files in the specified submit modules dir that do not conform to this specification will not be loaded for presentation to client code that rely on the number of loge
3. As long as a valid SubmitModuleResult is returned, then the submit module may take whatever action it feels appropriate, however, displaying the returned page in a webbrowser should probably be delegated to the frontend that receives the result object. This is, after all, the purpose of the response_url and response_xml variables contained in the SubmitModuleResult class

Definition of SubmitModuleResult

class SubmitModuleResult:

      init(self, bool_ispastebin, bool_success, response_url=None, response_xml=None)

The exact functioning of the module is not defined, however, the following conditions will always be true about the submit module result

1. 1. 1. 1. If the attribute is available, then it will be stored in a self variable of the same name, for

       example, if we have a SubmitModuleResult object named obj, then the bool_ispastebin variable
        will be located at self.bool_ispastebin

1. 1. 1. 1. bool_ispastebin should always be defined, as should bool_success.
         2. If bool_success == True, then response_xml should always be defined. This will be the page

        that is returned from a pastebin server, or the xml returned by an xml-rpc call.

1. 1. 1. 1. If bool_success === True and bool_ispastebin === True, then response_url should be a valid URL

        pointing to the pastebin page where the data was posted to

1. 1. 1. 1. If, for example, bool_success === True, yet response_xml === None, then an

        InvalidSubmitModuleResultException will be raised (Possible a shorter name that is equally
        descriptive should be proposed).
        

Design of the Submit Module Loader

The submit module loader will be responsible for locating and loading a list of valid submission modules to the user. The module loader will be component of upstream-base, in submitmoduleloader.py it will have the following core functions: def add_submit_module_search_path(path): def get_all_submit_modules() def get_submit_module_by_name(name) add_submit_module_search_path will add a path to be searched for submission modules. Calling this method updates and reimports all modules, thus, to refresh the module listing without adding a new directory to search, this function can be called with None as its only parameter, and will thus, re-search the given search paths, and re-import all modules therein. get_all_submit_modules() returns a tuple of SubmitModule objects. The SubmitModule object describes a submission module, and shall be discussed more in detail. get_submit_module_by_name() returns the first occurrence of a submission module that has the given name. This will be contained in a SubmitModule. The SubmitModule will contain the following fields and methods that describe the submission module. module_name self.name will always equal module_name module_description module_submit_url module execute(email, submission_message, dict_of_logs) execute will return a SubmitModuleResult object. The actual design of the module loader will involve a global list of search paths to look for modules, as well as a global list of all .py files that are contained in those directories. All of these actions are dependant on the imp module (import module) and the glob module In order to find all of the modules, imp.find_module() will be executed on each *.py file that is located in the given directories using glob. The result will then be used to import a module using imp.load_module(). Finally, dir() will be used to ensure that the loaded .py files contains the required components required to make it a valid submission module. If this is the case, then the module will be properly wrapped in a SubmitModule object, and added to a global list of SubmitModule objects. This list of SubmitModule objects will be converted to a tuple and returned when get_all_submit_modules() is called.