Changeset 25:fd00a744a458 for wokkel/data_form.py

Timestamp:

Jul 7, 2008, 4:29:02 PM (14 years ago)

Author:

Ralph Meijer <ralphm@…>

Branch:

default

Convert:

svn:b33ecbfc-034c-dc11-8662-000475d9059e/trunk@55

Message:

Refactor Data Forms.

Author: ralphm.
Fixes #13.

This refactoring provides an abstract representation of Forms, Fields and
Options and each of those can be parsed from or unparsed to XML. This change
also simplifies testing in test_pubsub, by allowing the 'received' requests
to be represented as an XML snippit.

File:

• wokkel/data_form.py (modified) (1 diff)

wokkel/data_form.py

@@ -1 @@
-# Copyright (c) 2003-2007 Ralph Meijer
+# -*- test-case-name: wokkel.test.test_data_form -*-
+#
+# Copyright (c) 2003-2008 Ralph Meijer
 # See LICENSE for details.
 
+"""
+Data Forms.
+
+Support for Data Forms as described in
+U{XEP-0004<http://www.xmpp.org/extensions/xep-0004.html>}, along with support
+for Field Standardization for Data Forms as described in
+U{XEP-0068<http://www.xmpp.org/extensions/xep-0068.html>}.
+"""
+
+from twisted.words.protocols.jabber.jid import JID
 from twisted.words.xish import domish
 
 NS_X_DATA = 'jabber:x:data'
 
-class Field(domish.Element):
-    def __init__(self, type='text-single', var=None, label=None,
-                       value=None, values=[], options={}):
-        domish.Element.__init__(self, (NS_X_DATA, 'field'))
-        self['type'] = type
-        if var is not None:
-            self['var'] = var
-        if label is not None:
-            self['label'] = label
+
+
+class Error(Exception):
+    """
+    Data Forms error.
+    """
+
+
+
+class FieldNameRequiredError(Error):
+    """
+    A field name is required for this field type.
+    """
+
+
+
+class TooManyValuesError(Error):
+    """
+    This field is single-value.
+    """
+
+
+
+class Option(object):
+    """
+    Data Forms field option.
+
+    @ivar value: Value of this option.
+    @type value: C{unicode}
+    @ivar label: Optional label for this option.
+    @type label: C{unicode} or C{NoneType}.
+    """
+
+    def __init__(self, value, label=None):
+        self.value = value
+        self.label = label
+
+
+    def __repr__(self):
+        r = ["Option(", repr(self.value)]
+        if self.label:
+            r.append(", ")
+            r.append(repr(self.label))
+        r.append(")")
+        return u"".join(r)
+
+
+    def toElement(self):
+        """
+        Return the DOM representation of this option.
+
+        @rtype L{domish.Element}.
+        """
+        option = domish.Element((NS_X_DATA, 'option'))
+        option.addElement('value', content=self.value)
+        if self.label:
+            option['label'] = self.label
+        return option
+
+    @staticmethod
+    def fromElement(element):
+        valueElements = list(domish.generateElementsQNamed(element.children,
+                                                           'value', NS_X_DATA))
+        if not valueElements:
+            raise Error("Option has no value")
+
+        label = element.getAttribute('label')
+        return Option(unicode(valueElements[0]), label)
+
+
+class Field(object):
+    """
+    Data Forms field.
+
+    @ivar fieldType: Type of this field. One of C{'boolean'}, C{'fixed'},
+                     C{'hidden'}, C{'jid-multi'}, C{'jid-single'},
+                     C{'list-multi'}, {'list-single'}, C{'text-multi'},
+                     C{'text-private'}, C{'text-single'}.
+
+                     The default is C{'text-single'}.
+    @type fieldType: C{str}
+    @ivar var: Field name. Optional if L{fieldType} is C{'fixed'}.
+    @type var: C{str}
+    @ivar label: Human readable label for this field.
+    @type label: C{unicode}
+    @ivar values: The values for this field, for multi-valued field
+                  types, as a list of C{bool}, C{unicode} or L{JID}.
+    @type values: C{list}
+    @ivar options: List of possible values to choose from in a response
+                   to this form as a list of L{Option}s.
+    @type options: C{list}.
+    @ivar desc: Human readable description for this field.
+    @type desc: C{unicode}
+    @ivar required: Whether the field is required to be provided in a
+                    response to this form.
+    @type required: C{bool}.
+    """
+
+    def __init__(self, fieldType='text-single', var=None, value=None,
+                       values=None, options=None, label=None, desc=None,
+                       required=False):
+        """
+        Initialize this field.
+
+        See the identically named instance variables for descriptions.
+
+        If C{value} is not C{None}, it overrides C{values}, setting the
+        given value as the only value for this field.
+        """
+
+        self.fieldType = fieldType
+        self.var = var
         if value is not None:
-            self.set_value(value)
+            self.value = value
         else:
-            self.set_values(values)
-        if type in ['list-single', 'list-multi']:
-            for value, label in options.iteritems():
-                self.addChild(Option(value, label))
-
-    def set_value(self, value):
-        if self['type'] == 'boolean':
-            value = str(int(bool(value)))
+            self.values = values or []
+
+        try:
+            self.options = [Option(value, label)
+                            for value, label in options.iteritems()]
+        except AttributeError:
+            self.options = options or []
+
+        self.label = label
+        self.desc = desc
+        self.required = required
+
+
+    def __repr__(self):
+        r = ["Field(fieldType=", repr(self.fieldType)]
+        if self.var:
+            r.append(", var=")
+            r.append(repr(self.var))
+        if self.label:
+            r.append(", label=")
+            r.append(repr(self.label))
+        if self.desc:
+            r.append(", desc=")
+            r.append(repr(self.desc))
+        if self.required:
+            r.append(", required=")
+            r.append(repr(self.required))
+        if self.values:
+            r.append(", values=")
+            r.append(repr(self.values))
+        if self.options:
+            r.append(", options=")
+            r.append(repr(self.options))
+        r.append(")")
+        return u"".join(r)
+
+
+    def __value_set(self, value):
+        """
+        Setter of value property.
+
+        Sets C{value} as the only element of L{values}.
+
+        @type value: C{bool}, C{unicode} or L{JID}
+        """
+        self.values = [value]
+
+
+    def __value_get(self):
+        """
+        Getter of value property.
+
+        Returns the first element of L{values}, if present, or C{None}.
+        """
+
+        if self.values:
+            return self.values[0]
         else:
-            value = str(value)
-
-        value_element = self.value or self.addElement('value')
-        value_element.children = []
-        value_element.addContent(value)
-
-    def set_values(self, values):
-        for value in values:
-            value = str(value)
-            self.addElement('value', content=value)
-
-class Option(domish.Element):
-    def __init__(self, value, label=None):
-        domish.Element.__init__(self, (NS_X_DATA, 'option'))
-        if label is not None:
-            self['label'] = label
-        self.addElement('value', content=value)
-
-class Form(domish.Element):
-    def __init__(self, type, form_type):
-        domish.Element.__init__(self, (NS_X_DATA, 'x'),
-                                attribs={'type': type})
-        self.add_field(type='hidden', var='FORM_TYPE', values=[form_type])
-
-    def add_field(self, type='text-single', var=None, label=None,
-                        value=None, values=[], options={}):
-        self.addChild(Field(type, var, label, value, values, options))
+            return None
+
+
+    value = property(__value_get, __value_set, doc="""
+            The value for this field, for single-valued field types.
+
+            This is a special property accessing L{values}.  Writing to this
+            property empties L{values} and then sets the given value as the
+            only element of L{values}.  Reading from this propery returns the
+            first element of L{values}.
+            """)
+
+
+    def toElement(self):
+        """
+        Return the DOM representation of this Field.
+
+        @rtype L{domish.Element}.
+        """
+        if self.var is None and self.fieldType != 'fixed':
+            raise FieldNameRequiredError()
+
+        field = domish.Element((NS_X_DATA, 'field'))
+        field['type'] = self.fieldType
+
+        if self.var is not None:
+            field['var'] = self.var
+
+        if self.values:
+            if (self.fieldType not in ('hidden', 'jid-multi', 'list-multi',
+                                 'text-multi') and
+                len(self.values) > 1):
+                raise TooManyValuesError()
+
+            for value in self.values:
+                if self.fieldType == 'boolean':
+                    # We send out the textual representation of boolean values
+                    value = unicode(bool(value)).lower()
+                elif self.fieldType in ('jid-single', 'jid-multi'):
+                    value = value.full()
+
+                field.addElement('value', content=value)
+
+        if self.fieldType in ('list-single', 'list-multi'):
+            for option in self.options:
+                field.addChild(option.toElement())
+
+        if self.label is not None:
+            field['label'] = self.label
+
+        if self.desc is not None:
+            field.addElement('desc', content=self.desc)
+
+        if self.required:
+            field.addElement('required')
+
+        return field
+
+
+    @staticmethod
+    def _parse_desc(field, element):
+        desc = unicode(element)
+        if desc:
+            field.desc = desc
+
+
+    @staticmethod
+    def _parse_option(field, element):
+        field.options.append(Option.fromElement(element))
+
+
+    @staticmethod
+    def _parse_required(field, element):
+        field.required = True
+
+
+    @staticmethod
+    def _parse_value(field, element):
+        value = unicode(element)
+        if field.fieldType == 'boolean':
+            value = value.lower() in ('1', 'true')
+        elif field.fieldType in ('jid-multi', 'jid-single'):
+            value = JID(value)
+        field.values.append(value)
+
+
+    @staticmethod
+    def fromElement(element):
+        field = Field(None)
+
+        for eAttr, fAttr in {'type': 'fieldType',
+                             'var': 'var',
+                             'label': 'label'}.iteritems():
+            value = element.getAttribute(eAttr)
+            if value:
+                setattr(field, fAttr, value)
+
+
+        for child in element.elements():
+            if child.uri != NS_X_DATA:
+                continue
+
+            func = getattr(Field, '_parse_' + child.name, None)
+            if func:
+                func(field, child)
+
+        return field
+
+
+    @staticmethod
+    def fromDict(dictionary):
+        if 'type' in dictionary:
+            dictionary['fieldType'] = dictionary['type']
+            del dictionary['type']
+        if 'options' in dictionary:
+            options = []
+            for value, label in dictionary['options'].iteritems():
+                options.append(Option(value, label))
+            dictionary['options'] = options
+        return Field(**dictionary)
+
+
+
+class Form(object):
+    """
+    Data Form.
+
+    There are two similarly named properties of forms. The L{formType} is the
+    the so-called type of the form, and is set as the C{'type'} attribute
+    on the form's root element.
+
+    The Field Standardization specification in XEP-0068, defines a way to
+    provide a context for the field names used in this form, by setting a
+    special hidden field named C{'FORM_TYPE'}, to put the names of all
+    other fields in the namespace of the value of that field. This namespace
+    is recorded in the L{formNamespace} instance variable.
+
+    @ivar formType: Type of form. One of C{'form'}, C{'submit'}, {'cancel'},
+                    or {'result'}.
+    @type formType: C{str}.
+    @ivar formNamespace: The optional namespace of the field names for this
+                         form. This goes in the special field named
+                         C{'FORM_TYPE'}, if set.
+    @type formNamespace: C{str}.
+    """
+
+    def __init__(self, formType, title=None, instructions=None,
+                       formNamespace=None, fields=None):
+        self.formType = formType
+        self.title = title
+        self.instructions = instructions or []
+        self.formNamespace = formNamespace
+        self.fields = fields or []
+
+
+    def __repr__(self):
+        r = ["Form(formType=", repr(self.formType)]
+
+        if self.title:
+            r.append(", title=")
+            r.append(repr(self.title))
+        if self.instructions:
+            r.append(", instructions=")
+            r.append(repr(self.instructions))
+        if self.formNamespace:
+            r.append(", formNamespace=")
+            r.append(repr(self.formNamespace))
+        if self.fields:
+            r.append(", fields=")
+            r.append(repr(self.fields))
+        r.append(")")
+        return u"".join(r)
+
+
+    def toElement(self):
+        form = domish.Element((NS_X_DATA, 'x'))
+        form['type'] = self.formType
+
+        if self.title:
+            form.addElement('title', content=self.title)
+
+        for instruction in self.instructions:
+            form.addElement('instruction', content=instruction)
+
+        if self.formNamespace is not None:
+            field = Field('hidden', 'FORM_TYPE', self.formNamespace)
+            form.addChild(field.toElement())
+
+        for field in self.fields:
+            form.addChild(field.toElement())
+
+        return form
+
+
+    @staticmethod
+    def _parse_title(form, element):
+        title = unicode(element)
+        if title:
+            form.title = title
+
+
+    @staticmethod
+    def _parse_instructions(form, element):
+        instructions = unicode(element)
+        if instructions:
+            form.instructions.append(instructions)
+
+
+    @staticmethod
+    def _parse_field(form, element):
+        field = Field.fromElement(element)
+        if (field.var == "FORM_TYPE" and
+            field.fieldType == 'hidden' and
+            field.value):
+            form.formNamespace = field.value
+        else:
+            form.fields.append(field)
+
+    @staticmethod
+    def fromElement(element):
+        if (element.uri, element.name) != ((NS_X_DATA, 'x')):
+            raise Error("Element provided is not a Data Form")
+
+        form = Form(element.getAttribute("type"))
+
+        for child in element.elements():
+            if child.uri != NS_X_DATA:
+                continue
+
+            func = getattr(Form, '_parse_' + child.name, None)
+            if func:
+                func(form, child)
+
+        return form
+
+    def getValues(self):
+        values = {}
+
+        for field in self.fields:
+            if len(field.values) > 1:
+                value = field.values
+            else:
+                value = field.value
+
+            if field.var:
+                values[field.var] = value
+
+        return values