Source Code for Module entropy.core.settings.plugins.skel

  1  # -*- coding: utf-8 -*- 
  2  """ 
  3   
  4      @author: Fabio Erculiani <lxnay@sabayonlinux.org> 
  5      @contact: lxnay@sabayonlinux.org 
  6      @copyright: Fabio Erculiani 
  7      @license: GPL-2 
  8   
  9      B{Entropy Framework SystemSettings stub classes module}. 
 10   
 11      SystemSettingsPlugin is the base class for building valid SystemSettings 
 12      plugin modules (see entropy.client.interfaces.client or 
 13      entropy.server.interfaces for working examples). 
 14   
 15  """ 
 16   
 17 -class SystemSettingsPlugin(object): 
 18   
 19      BASE_PLUGIN_API_VERSION = 1 
 20   
 21      """ 
 22   
 23      This is a plugin base class for all SystemSettings plugins. 
 24      It allows to add extra parsers (though metadata) to 
 25      SystemSettings. 
 26      Just inherit from this class and call add_parser to add 
 27      your custom parsers. 
 28      SystemSettings will call the parse method, as explained below. 
 29   
 30      Sample code: 
 31   
 32          >>> # load SystemSettings 
 33          >>> from entropy.core.settings.base import SystemSettings 
 34          >>> from entropy.core.settings.plugins.skel import SystemSettingsPlugin 
 35          >>> system_settings = SystemSettings() 
 36          >>> class MyPlugin(SystemSettingsPlugin): 
 37          >>>      pass 
 38          >>> my_plugin = MyPlugin('mystuff', None) 
 39          >>> def myparsing_function(): 
 40          >>>     return {'abc': 1 } 
 41          >>> my_plugin.add_parser('parser_no_1', myparsing_function) 
 42          >>> system_settings.add_plugin(my_plugin) 
 43          >>> print(system_settings['mystuff']['parser_no_1']) 
 44          {'abc': 1 } 
 45          >>> # let's remove it 
 46          >>> system_settings.remove_plugin('mystuff') # through its plugin_id 
 47          >>> print(system_settings.get('mystuff')) 
 48          None 
 49   
 50      """ 
 51   
 52 -    def __init__(self, plugin_id, helper_interface): 
 53          """ 
 54          SystemSettingsPlugin constructor. 
 55   
 56          @param plugin_id: plugin identifier, must be unique 
 57          @type plugin_id: string 
 58          @param helper_interface: any Python object that could 
 59              be of help to your parsers 
 60          @type handler_instance: Python object 
 61          @rtype: None 
 62          @return: None 
 63          """ 
 64          self.__parsers = [] 
 65          self.__plugin_id = plugin_id 
 66          self._helper = helper_interface 
 67          parser_postfix = "_parser" 
 68          for method in sorted(dir(self)): 
 69              if method == "add_parser": 
 70                  continue 
 71              elif method.endswith(parser_postfix) and (method != parser_postfix): 
 72                  parser_id = method[:len(parser_postfix)*-1] 
 73                  self.__parsers.append((parser_id, getattr(self, method),)) 
 74   
 75 -    def get_id(self): 
 76          """ 
 77          Returns the unique plugin id passed at construction time. 
 78   
 79          @return: plugin identifier 
 80          @rtype: string 
 81          """ 
 82          return self.__plugin_id 
 83   
 84 -    def add_parser(self, parser_id, parser_callable): 
 85          """ 
 86          You must call this method in order to add your custom 
 87          parsers to the plugin. 
 88          Please note, if your parser method ends with "_parser" 
 89          it will be automatically added this way: 
 90   
 91          method: foo_parser 
 92              parser_id => foo 
 93          method: another_fabulous_parser 
 94              parser_id => another_fabulous 
 95   
 96          @param parser_id: parser identifier, must be unique 
 97          @type parser_id: string 
 98          @param parser_callable: any callable function which has 
 99              the following signature: callable(system_settings_instance) 
100              can return True to stop further parsers calls 
101          @type parser_callable: callable 
102          @return: None 
103          @rtype: None 
104          """ 
105          self.__parsers.append((parser_id, parser_callable,)) 
106   
107 -    def parse(self, system_settings_instance): 
108          """ 
109          This method is called by SystemSettings instance 
110          when building its settings metadata. 
111   
112          Returned data from parser will be put into the SystemSettings 
113          dict using plugin_id and parser_id keys. 
114          If returned data is None, SystemSettings dict won't be changed. 
115   
116          @param system_settings_instance: SystemSettings instance 
117          @type system_settings_instance: SystemSettings instance 
118          @return: None 
119          @rtype: None 
120          """ 
121          plugin_id = self.get_id() 
122          for parser_id, parser in self.__parsers: 
123              data = parser(system_settings_instance) 
124              if data is None: 
125                  continue 
126              obj = system_settings_instance.setdefault(plugin_id, {}) 
127              obj[parser_id] = data 
128   
129 -    def post_setup(self, system_settings_instance): 
130          """ 
131          This method is called by SystemSettings instance 
132          after having built all the SystemSettings metadata. 
133          You can reimplement this and hook your refinement code 
134          into this method. 
135   
136          @param system_settings_instance: SystemSettings instance 
137          @type system_settings_instance: SystemSettings instance 
138          @return: None 
139          @rtype: None 
140          """ 
141          pass 
142