libervia-backend: src/tools/xml

comparison src/tools/xml_tools.py @ 1444:8ce9924fa92c

tools (xml_tools): better PEP-8 compliance

author	souliane <souliane@mailoo.org>
date	Tue, 21 Jul 2015 15:36:40 +0200
parents	3265a2639182
children	a13be5c22334

comparison

equal deleted inserted replaced

-:32d1089df687
+:8ce9924fa92c
 from sat.core.i18n import _
 from sat.core.constants import Const as C
 from sat.core.log import getLogger
 log = getLogger(__name__)
 from xml.dom import minidom, NotFoundErr
 from wokkel import data_form
 from twisted.words.xish import domish
 from sat.core import exceptions
-"""This library help manage XML used in SàT (parameters, registration, etc) """
+"""This library help manage XML used in SàT (parameters, registration, etc)"""
 SAT_FORM_PREFIX = "SAT_FORM_"
-SAT_PARAM_SEPARATOR = "_XMLUI_PARAM_" # used to have unique elements names
+SAT_PARAM_SEPARATOR = "_XMLUI_PARAM_"  # used to have unique elements names
 # Helper functions
 def _dataFormField2XMLUIData(field, read_only=False):
-""" Get data needed to create an XMLUI's Widget from Wokkel's data_form's Field
+"""Get data needed to create an XMLUI's Widget from Wokkel's data_form's Field.
-field can be modified (if it's fixed and it has no value)
-@param field: data_form.Field (it uses field.value, field.fieldType, field.label and field.var)
+The attribute field can be modified (if it's fixed and it has no value).
-@param read_only: if True and it make sens, create a read only input widget
-@return: widget_type, widget_args, widget_kwargs
+@param field (data_form.Field): a field with attributes "value", "fieldType", "label" and "var"
+@param read_only (bool): if True and it makes sense, create a read only input widget
+@return: a tuple (widget_type, widget_args, widget_kwargs)
 """
 widget_args = [field.value]
 widget_kwargs = {}
 if field.fieldType == 'fixed' or field.fieldType is None:
 widget_type = 'text'
 if field.var:
 widget_kwargs["name"] = field.var
 return widget_type, widget_args, widget_kwargs
 def dataForm2Widgets(form_ui, form, read_only=False):
-"""Complete an existing XMLUI with widget converted frot XEP-0004 data forms
+"""Complete an existing XMLUI with widget converted from XEP-0004 data forms.
-@param form_ui: XMLUI instance
+@param form_ui (XMLUI): XMLUI instance
-@param form: Wokkel's implementation of data form
+@param form (data_form.Form): Wokkel's implementation of data form
-@return: completed xml_ui
+@param read_only (bool): if True and it makes sense, create a read only input widget
+@return: the completed XMLUI instance
 """
 if form.instructions:
 form_ui.addText('\n'.join(form.instructions), 'instructions')
 form_ui.changeContainer("pairs")
 form_ui.addWidget(widget_type, *widget_args, **widget_kwargs)
 return form_ui
 def dataForm2XMLUI(form, submit_id, session_id=None, read_only=False):
-"""Take a data form (xep-0004, Wokkel's implementation) and convert it to a SàT XML
+"""Take a data form (XEP-0004, Wokkel's implementation) and convert it to a SàT XMLUI.
-@param submit_id: callback id to call when submitting form
+@param form (data_form.Form): a Form instance
-@param session_id: id to return with the data
+@param submit_id (unicode): callback id to call when submitting form
+@param session_id (unicode): session id to return with the data
+@param read_only (bool): if True and it makes sense, create a read only input widget
+@return: XMLUI instance
 """
 form_ui = XMLUI("form", "vertical", submit_id=submit_id, session_id=session_id)
 return dataForm2Widgets(form_ui, form, read_only=read_only)
 def dataFormResult2AdvancedList(xmlui, form_xml):
-"""Take a raw data form (not parsed by XEP-0004) and convert it to an advanced list
+"""Take a raw data form (not parsed by XEP-0004) and convert it to an advanced list.
-raw data form is used because Wokkel doesn't manage result items parsing yet
-@param xmlui: the XMLUI where the AdvancedList will be added
+The raw data form is used because Wokkel doesn't manage result items parsing yet.
-@param form_xml: domish.Element of the data form
+@param xmlui (XMLUI): the XMLUI where the AdvancedList will be added
+@param form_xml (domish.Element): element of the data form
 @return: AdvancedList element
 """
 headers = {}
 try:
 reported_elt = form_xml.elements('jabber:x:data', 'reported').next()
 for elt in reported_elt.elements():
 if elt.name != "field":
 raise exceptions.DataError("Unexpected tag")
 name = elt["var"]
-label = elt.attributes.get('label','')
+label = elt.attributes.get('label', '')
 type_ = elt.attributes.get('type')
 headers[name] = (label, type_)
 if not headers:
 raise exceptions.DataError("No reported fields (see XEP-0004 §3.4)")
 widget_type, widget_args, widget_kwargs = _dataFormField2XMLUIData(field)
 xmlui.addWidget(widget_type, *widget_args, **widget_kwargs)
 return xmlui
 def dataFormResult2XMLUI(form_elt, session_id=None):
-"""Take a raw data form (not parsed by XEP-0004) and convert it to a SàT XMLUI
+"""Take a raw data form (not parsed by XEP-0004) and convert it to a SàT XMLUI.
-raw data form is used because Wokkel doesn't manage result items parsing yet
-@param form_elt: domish.Element of the data form
+The raw data form is used because Wokkel doesn't manage result items parsing yet.
-@return: XMLUI interface
+@param form_elt (domish.Element): element of the data form
-"""
+@param session_id (unicode): session id to return with the data
+@return: XMLUI instance
+"""
 xml_ui = XMLUI("window", "vertical", session_id=session_id)
 try:
 dataFormResult2AdvancedList(xml_ui, form_elt)
 except exceptions.DataError:
 parsed_form = data_form.Form.fromElement(form_elt)
 dataForm2Widgets(xml_ui, parsed_form, read_only=True)
 return xml_ui
 def _cleanValue(value):
-"""Workaround method to avoid DBus types with D-Bus bridge
+"""Workaround method to avoid DBus types with D-Bus bridge.
 @param value: value to clean
 @return: value in a non DBus type (only clean string yet)
 """
 # XXX: must be removed when DBus types will no cause problems anymore
 # FIXME: should be cleaned inside D-Bus bridge itself
 if isinstance(value, basestring):
 return unicode(value)
 return value
 def XMLUIResult2DataFormResult(xmlui_data):
-""" Extract form data from a XMLUI return
+""" Extract form data from a XMLUI return.
-@xmlui_data: data returned by frontends for XMLUI form
-@return: dict of data usable by Wokkel's dataform
+@param xmlui_data (dict): data returned by frontends for XMLUI form
+@return: dict of data usable by Wokkel's data form
 """
 return {key[len(SAT_FORM_PREFIX):]: _cleanValue(value) for key, value in xmlui_data.iteritems() if key.startswith(SAT_FORM_PREFIX)}
 def formEscape(name):
-""" Return escaped name for forms """
+"""Return escaped name for forms.
-return u"%s%s"  % (SAT_FORM_PREFIX, name)
+@param name (unicode): form name
+@return: unicode
+"""
+return u"%s%s" % (SAT_FORM_PREFIX, name)
 def XMLUIResultToElt(xmlui_data):
-""" Construct result domish.Element from XMLUI result
+"""Construct result domish.Element from XMLUI result.
-@xmlui_data: data returned by frontends for XMLUI form
+@param xmlui_data (dict): data returned by frontends for XMLUI form
+@return: domish.Element
 """
 form = data_form.Form('submit')
 form.makeFields(XMLUIResult2DataFormResult(xmlui_data))
 return form.toElement()
 def tupleList2dataForm(values):
-"""convert a list of tuples (name,value) to a wokkel submit data form"""
+"""Convert a list of tuples (name, value) to a wokkel submit data form.
+@param values (list): list of tuples
+@return: data_form.Form
+"""
 form = data_form.Form('submit')
 for value in values:
 field = data_form.Field(var=value[0], value=value[1])
 form.addField(field)
 return form
 def paramsXML2XMLUI(xml):
-"""Convert the xml for parameter to a SàT XML User Interface"""
+"""Convert the XML for parameter to a SàT XML User Interface.
+@param xml (unicode)
+@return: XMLUI
+"""
 params_doc = minidom.parseString(xml.encode('utf-8'))
 top = params_doc.documentElement
 if top.nodeName != 'params':
 raise exceptions.DataError(_('INTERNAL ERROR: parameters xml not valid'))
 return param_ui.toXml()
 def _getParamListOptions(param):
-"""Retrieve the options for list element. The <option/> tags
+"""Retrieve the options for list element.
-must be direct children of <param/>."""
+The <option/> tags must be direct children of <param/>.
+@param param (domish.Element): element
+@return: a tuple (options, selected_value)
+"""
 if len(param.getElementsByTagName("options")) > 0:
 raise exceptions.DataError(_("The 'options' tag is not allowed in parameter of type 'list'!"))
 elems = param.getElementsByTagName("option")
 if len(elems) == 0:
 return []
 options = [elem.getAttribute("value") for elem in elems]
 selected = [elem.getAttribute("value") for elem in elems if elem.getAttribute("selected") == 'true']
-return  (options, selected)
+return (options, selected)
 ## XMLUI Elements
 """ Base XMLUI element """
 type = None
 def __init__(self, xmlui, parent=None):
 """Create a container element
 @param xmlui: XMLUI instance
 @parent: parent element
 """
 assert(self.type) is not None
 if not hasattr(self, 'elem'):
 self.elem = xmlui.doc.documentElement
 super(TopElement, self).__init__(xmlui)
 class TabElement(Element):
-""" Used by TabsContainer to give name and label to tabs """
+""" Used by TabsContainer to give name and label to tabs."""
 type = 'tab'
 def __init__(self, parent, name, label):
 if not isinstance(parent, TabsContainer):
 raise exceptions.DataError(_("TabElement must be a child of TabsContainer"))
 while(not isinstance(current, (Container)) and
 current is not None):
 current = current.parent
 return current
 class VerticalContainer(Container):
 type = "vertical"
 class HorizontalContainer(Container):
 class AdvancedListContainer(Container):
 type = "advanced_list"
-def __init__(self, xmlui, callback_id=None, name=None, headers=None, items=None, columns=None, selectable = 'no', auto_index = False, parent=None):
+def __init__(self, xmlui, callback_id=None, name=None, headers=None, items=None, columns=None, selectable='no', auto_index=False, parent=None):
 """Create an advanced list
 @param headers: optional headers information
 @param callback_id: id of the method to call when selection is done
 @param items: list of widgets to add (just the first row)
 @param columns: number of columns in this table, or None to autodetect
 def addHeaders(self, headers):
 for header in headers:
 self.addHeader(header)
 def addHeader(self, header):
-pass # TODO
+pass  # TODO
 def addItems(self, items):
 for item in items:
 self.append(item)
 class LabelWidget(Widget):
 """Used for one line blob of text,
 most of time to display the desciption or name of the next widget
 """
-type='label'
+type = 'label'
 def __init__(self, xmlui, label, name=None, parent=None):
 super(LabelWidget, self).__init__(xmlui, name, parent)
 self.elem.setAttribute('value', label)
 class JidWidget(Widget):
 """Used to display a Jabber ID, some specific methods can be added"""
-type='jid'
+type = 'jid'
 def __init__(self, xmlui, jid, name=None, parent=None):
 super(JidWidget, self).__init__(xmlui, name, parent)
 try:
 self.elem.setAttribute('value', jid.full())
 if panel_type == C.XMLUI_DIALOG:
 if dialog_opt is None:
 dialog_opt = {}
 self._createDialog(dialog_opt)
 return
-self.main_container  = self._createContainer(container, TopElement(self))
+self.main_container = self._createContainer(container, TopElement(self))
 self.current_container = self.main_container
 def _introspect(self):
 """ Introspect module to find Widgets and Containers """
 self._containers = {}
 def __del__(self):
 self.doc.unlink()
 def __getattr__(self, name):
-if name.startswith("add") and name not in ('addWidget',): # addWidgetName(...) create an instance of WidgetName
+if name.startswith("add") and name not in ('addWidget',):  # addWidgetName(...) create an instance of WidgetName
 if self.type == C.XMLUI_DIALOG:
 raise exceptions.InternalError(_("addXXX can't be used with dialogs"))
-class_name = name[3:]+"Widget"
+class_name = name[3:] + "Widget"
 if class_name in globals():
 cls = globals()[class_name]
 if issubclass(cls, Widget):
 def createWidget(*args, **kwargs):
 if "parent" not in kwargs:
 kwargs["parent"] = self.current_container
-if "name" not in kwargs and issubclass(cls, InputWidget): # name can be given as first argument or in keyword arguments for InputWidgets
+if "name" not in kwargs and issubclass(cls, InputWidget):  # name can be given as first argument or in keyword arguments for InputWidgets
 args = list(args)
 kwargs["name"] = args.pop(0)
 return cls(self, *args, **kwargs)
 return createWidget
 return object.__getattribute__(self, name)
 if value is None:
 try:
 top_element.removeAttribute("submit")
 except NotFoundErr:
 pass
-elif value: # submit_id can be the empty string to bypass form restriction
+elif value:  # submit_id can be the empty string to bypass form restriction
 top_element.setAttribute("submit", value)
 @property
 def session_id(self):
 top_element = self.doc.documentElement
 @param message: body of the note
 @param title: title of the note
 @param level: one of C.XMLUI_DATA_LVL_*
 """
-note_xmlui = XMLUI(C.XMLUI_DIALOG, dialog_opt = {
+note_xmlui = XMLUI(C.XMLUI_DIALOG, dialog_opt={
 C.XMLUI_DATA_TYPE: C.XMLUI_DIALOG_NOTE,
 C.XMLUI_DATA_MESS: message,
 C.XMLUI_DATA_LVL: level},
 title=title
 )
 return note_xmlui
 # Misc other funtions

Mercurial > libervia-backend

comparison src/tools/xml_tools.py @ 1444:8ce9924fa92c