diff --git a/src/tools/xml_tools.py b/src/tools/xml_tools.py index 37f5ab6d..111e50f8 100644 --- a/src/tools/xml_tools.py +++ b/src/tools/xml_tools.py @@ -21,27 +21,29 @@ 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 - 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) - @param read_only: if True and it make sens, create a read only input widget - @return: widget_type, widget_args, widget_kwargs + """Get data needed to create an XMLUI's Widget from Wokkel's data_form's Field. + The attribute field can be modified (if it's fixed and it has no value). + + @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 = {} @@ -88,12 +90,14 @@ def _dataFormField2XMLUIData(field, read_only=False): 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 - @param form_ui: XMLUI instance - @param form: Wokkel's implementation of data form - @return: completed xml_ui +def dataForm2Widgets(form_ui, form, read_only=False): + """Complete an existing XMLUI with widget converted from XEP-0004 data forms. + + @param form_ui (XMLUI): XMLUI instance + @param form (data_form.Form): Wokkel's implementation of data form + @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') @@ -112,20 +116,26 @@ def dataForm2Widgets(form_ui, form, read_only=False): 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 - @param submit_id: callback id to call when submitting form - @param session_id: id to return with the data +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 XMLUI. + + @param form (data_form.Form): a Form instance + @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 - raw data form is used because Wokkel doesn't manage result items parsing yet - @param xmlui: the XMLUI where the AdvancedList will be added - @param form_xml: domish.Element of the data form + """Take a raw data form (not parsed by XEP-0004) and convert it to an advanced list. + + The raw data form is used because Wokkel doesn't manage result items parsing yet. + @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 = {} @@ -138,7 +148,7 @@ def dataFormResult2AdvancedList(xmlui, form_xml): 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_) @@ -162,13 +172,15 @@ def dataFormResult2AdvancedList(xmlui, form_xml): 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 - raw data form is used because Wokkel doesn't manage result items parsing yet - @param form_elt: domish.Element of the data form - @return: XMLUI interface - """ +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. + + The raw data form is used because Wokkel doesn't manage result items parsing yet. + @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) @@ -177,8 +189,9 @@ def dataFormResult2XMLUI(form_elt, session_id=None): 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) @@ -189,27 +202,42 @@ def _cleanValue(value): return unicode(value) return value + def XMLUIResult2DataFormResult(xmlui_data): - """ 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 + """ Extract form data from a XMLUI return. + + @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 u"%s%s" % (SAT_FORM_PREFIX, name) + """Return escaped name for forms. + + @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 - @xmlui_data: data returned by frontends for XMLUI form + """Construct result domish.Element from XMLUI result. + + @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]) @@ -217,8 +245,13 @@ def tupleList2dataForm(values): 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': @@ -274,8 +307,12 @@ def paramsXML2XMLUI(xml): def _getParamListOptions(param): - """Retrieve the options for list element. The