########################################################################
# File name: xso.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program. If not, see
# .
#
########################################################################
import collections
import enum
import aioxmpp
import aioxmpp.xso as xso
from aioxmpp.utils import namespaces
namespaces.xep0004_data = "jabber:x:data"
class Value(xso.XSO):
TAG = (namespaces.xep0004_data, "value")
value = xso.Text(default="")
class ValueElement(xso.AbstractElementType):
def unpack(self, item):
return item.value
def pack(self, value):
v = Value()
v.value = value
return v
def get_xso_types(self):
return [Value]
class Option(xso.XSO):
TAG = (namespaces.xep0004_data, "option")
label = xso.Attr(
tag="label",
default=None,
)
value = xso.ChildText(
(namespaces.xep0004_data, "value"),
default=None,
)
def validate(self):
if self.value is None:
raise ValueError("option is missing a value")
class OptionElement(xso.AbstractElementType):
def unpack(self, item):
return (item.value, item.label)
def pack(self, value):
value, label = value
o = Option()
o.value = value
o.label = label
return o
def get_xso_types(self):
return [Option]
class FieldType(enum.Enum):
"""
Enumeration containing the field types defined in :xep:`4`.
.. seealso::
:attr:`Field.values`
for important information regarding typing, restrictions, validation
and constraints of values in that attribute.
Each type has the following attributes and methods:
.. automethod:: allow_upcast
.. autoattribute:: has_options
.. autoattribute:: is_multivalued
Quotations in the following attribute descriptions are from said XEP.
.. attribute:: BOOLEAN
The ``"boolean"`` field:
The field enables an entity to gather or provide an either-or choice
between two options. The default value is "false".
The :attr:`Field.values` sequence should contain zero or one elements.
If it contains an element, it must be ``"0"``, ``"1"``, ``"false"``, or
``"true"``, in accordance with the XML Schema documents.
.. attribute:: FIXED
The ``"fixed"`` field:
The field is intended for data description (e.g., human-readable text
such as "section" headers) rather than data gathering or provision.
The child SHOULD NOT contain newlines (the ``\\n`` and
``\\r`` characters); instead an application SHOULD generate multiple
fixed fields, each with one child.
As such, the :attr:`Field.values` sequence should contain exactly one
element. :attr:`Field.desc`, :attr:`Field.label`, :attr:`Field.options`
and :attr:`Field.var` should be set to :data:`None` or empty containers.
.. attribute:: HIDDEN
The ``"hidden"`` field:
The field is not shown to the form-submitting entity, but instead is
returned with the form. The form-submitting entity SHOULD NOT modify
the value of a hidden field, but MAY do so if such behavior is
defined for the "using protocol".
This type is commonly used for the ``var="FORM_TYPE"`` field, as
specified in :xep:`68`.
.. attribute:: JID_MULTI
The ``"jid-multi"`` field:
The field enables an entity to gather or provide multiple Jabber IDs.
Each provided JID SHOULD be unique (as determined by comparison that
includes application of the Nodeprep, Nameprep, and Resourceprep
profiles of Stringprep as specified in XMPP Core), and duplicate JIDs
MUST be ignored.
As such, the :attr:`Field.values` sequence should contain zero or more
strings representing Jabber IDs. :attr:`Field.options` should be empty.
.. attribute:: JID_SINGLE
The ``"jid-single"`` field:
The field enables an entity to gather or provide a single Jabber ID.
As such, the :attr:`Field.values` sequence should contain zero or one
string representing a Jabber ID. :attr:`Field.options` should be empty.
.. attribute:: LIST_MULTI
The ``"list-multi"`` field:
The field enables an entity to gather or provide one or more options
from among many. A form-submitting entity chooses one or more items
from among the options presented by the form-processing entity and
MUST NOT insert new options. The form-submitting entity MUST NOT
modify the order of items as received from the form-processing
entity, since the order of items MAY be significant.
Thus, :attr:`Field.values` should contain a subset of the keys of the
:class:`Field.options` dictionary.
.. attribute:: LIST_SINGLE
The ``"list-single"`` field:
The field enables an entity to gather or provide one option from
among many. A form-submitting entity chooses one item from among the
options presented by the form-processing entity and MUST NOT insert
new options.
Thus, :attr:`Field.values` should contain a zero or one of the keys of
the :class:`Field.options` dictionary.
.. attribute:: TEXT_MULTI
The ``"text-multi"`` field:
The field enables an entity to gather or provide multiple lines of
text.
Each string in the :attr:`Field.values` attribute should be a single
line of text. Newlines are not allowed in data forms fields (due to the
ambiguity between ``\\r`` and ``\\n`` and combinations thereof), which
is why the text is split on the line endings.
.. attribute:: TEXT_PRIVATE
The ``"text-private"`` field:
The field enables an entity to gather or provide a single line or
word of text, which shall be obscured in an interface (e.g., with
multiple instances of the asterisk character).
The :attr:`Field.values` attribute should contain zero or one string
without any newlines.
.. attribute:: TEXT_SINGLE
The ``"text-single"`` field:
The field enables an entity to gather or provide a single line or
word of text, which may be shown in an interface. This field type is
the default and MUST be assumed if a form-submitting entity receives
a field type it does not understand.
The :attr:`Field.values` attribute should contain zero or one string
without any newlines.
"""
FIXED = "fixed"
HIDDEN = "hidden"
BOOLEAN = "boolean"
TEXT_SINGLE = "text-single"
TEXT_MULTI = "text-multi"
TEXT_PRIVATE = "text-private"
LIST_SINGLE = "list-single"
LIST_MULTI = "list-multi"
JID_SINGLE = "jid-single"
JID_MULTI = "jid-multi"
@property
def has_options(self):
"""
true for the ``list-`` field types, false otherwise.
"""
return self.value.startswith("list-")
@property
def is_multivalued(self):
"""
true for the ``-multi`` field types, false otherwise.
"""
return self.value.endswith("-multi")
def allow_upcast(self, to):
"""
Return true if the field type may be upcast to the other field type
`to`.
This relation specifies when it is safe to transfer data from this
field type to the given other field type `to`.
This is the case if any of the following holds true:
* `to` is equal to this type
* this type is :attr:`TEXT_SINGLE` and `to` is :attr:`TEXT_PRIVATE`
"""
if self == to:
return True
if self == FieldType.TEXT_SINGLE and to == FieldType.TEXT_PRIVATE:
return True
return False
class Field(xso.XSO):
"""
Represent a single field in a Data Form.
:param type_: Field type, must be one of the valid field types specified in
:xep:`4`.
:type type_: :class:`FieldType`
:param options: A mapping of values to labels defining the options in a
``list-*`` field.
:type options: :class:`dict` mapping :class:`str` to :class:`str`
:param values: A sequence of values currently given for the field. Having
more than one value is only valid in ``*-multi`` fields.
:type values: :class:`list` of :class:`str`
:param desc: Description which can be shown in a tool-tip or similar,
without newlines.
:type desc: :class:`str` or :data:`None`
:param label: Human-readable label to be shown next to the field input
:type label: :class:`str` or :data:`None`
:param required: Flag to indicate that the field is required
:type required: :class:`bool`
:param var: "ID" identifying the field uniquely inside the form. Only
required for fields carrying a meaning (thus, not for
``fixed``).
:type var: :class:`str` or :data:`None`
The semantics of a :class:`Field` are different depending on where it
occurs: in a :class:`Data`, it is a form field to be filled in, in a
:class:`Item` it is a cell of a row and in a :class:`Reported` it
represents a column header.
.. attribute:: required
A boolean flag indicating whether the field is required.
If true, the XML serialisation will contain the corresponding
```` tag.
.. attribute:: desc
Single line of description for the field. This attribute represents the
```` element from :xep:`4`.
.. attribute:: values
A sequence of strings representing the ```` elements of the
field, one string for each value.
.. note::
Since the requirements on the sequence of strings in :attr:`values`
change depending on the :attr:`type_` attribute, validation and type
conversion on assignment is very lax. The attribute accepts all
sequences of strings, even if the field is for example a
:attr:`FieldType.BOOLEAN` field, which allows for at most one string
of a well-defined format (see the documentation there for the
details).
This makes it easy to inadvertendly generate invalid forms, which is
why you should be using :class:`Form` subclasses when accessing forms
from within normal code and some other, generic mechanism taking care
of these details when showing forms in a UI framework to users. Note
that devising such a mechanism is out of scope for :mod:`aioxmpp`, as
every UI framework has different requirements.
.. attribute:: options
A dictionary mapping values to human-readable labels, representing the
```` elements of the field.
.. attribute:: var
The uniquely identifying string of the (valued, that is,
non-:attr:`FieldType.FIXED` field). Represents the ``var`` attribute of
the field.
.. attribute:: type_
The type of the field. The :attr:`type_` must be a :class:`FieldType`
enumeration value and determines restrictions and constraints on other
attributes. See the :class:`FieldType` enumeration and :xep:`4` for
details.
.. attribute:: label
The human-readable label for the field, representing the ``label``
attribute of the field. May be :data:`None` if the label is omitted.
"""
TAG = (namespaces.xep0004_data, "field")
required = xso.ChildFlag(
(namespaces.xep0004_data, "required"),
)
desc = xso.ChildText(
(namespaces.xep0004_data, "desc"),
default=None
)
values = xso.ChildValueList(
type_=ValueElement()
)
options = xso.ChildValueMap(
type_=OptionElement(),
mapping_type=collections.OrderedDict,
)
var = xso.Attr(
(None, "var"),
default=None
)
type_ = xso.Attr(
(None, "type"),
type_=xso.EnumCDataType(
FieldType,
),
default=None,
)
label = xso.Attr(
(None, "label"),
default=None
)
def __init__(self, *,
type_=FieldType.TEXT_SINGLE,
options={},
values=[],
desc=None,
label=None,
required=False,
var=None):
super().__init__()
self.type_ = type_
self.options.update(options)
self.values[:] = values
self.desc = desc
self.label = label
self.required = required
self.var = var
def validate(self):
super().validate()
if self.type_ != FieldType.FIXED and not self.var:
raise ValueError("missing attribute var")
if self.type_ is not None:
if not self.type_.has_options and self.options:
raise ValueError("unexpected option on non-list field")
if not self.type_.is_multivalued and len(self.values) > 1:
raise ValueError("too many values on non-multi field")
values_list = [opt for opt in self.options.values() if opt is not None]
values_set = set(values_list)
if len(values_list) != len(values_set):
raise ValueError("duplicate option label in {}".format(
values_list
))
class AbstractItem(xso.XSO):
fields = xso.ChildList([Field])
class Item(AbstractItem):
"""
A single row in a report :class:`Data` object.
.. attribute:: fields
A sequence of :class:`Field` objects representing the cells of the row.
"""
TAG = (namespaces.xep0004_data, "item")
class Reported(AbstractItem):
"""
The table heading of a report :class:`Data` object.
.. attribute:: fields
A sequence of :class:`Field` objects representing the columns of the
report or table.
"""
TAG = (namespaces.xep0004_data, "reported")
class Instructions(xso.XSO):
TAG = (namespaces.xep0004_data, "instructions")
value = xso.Text(default="")
class InstructionsElement(xso.AbstractElementType):
def unpack(self, item):
return item.value
def pack(self, value):
v = Instructions()
v.value = value
return v
def get_xso_types(self):
return [Instructions]
class DataType(enum.Enum):
"""
Enumeration containing the :class:`Data` types defined in :xep:`4`.
Quotations in the following attribute descriptions are from :xep:`4`.
.. attribute:: FORM
The ``"form"`` type:
The form-processing entity is asking the form-submitting entity to
complete a form.
.. attribute:: SUBMIT
The ``"submit"`` type:
The form-submitting entity is submitting data to the form-processing
entity. The submission MAY include fields that were not provided in
the empty form, but the form-processing entity MUST ignore any fields
that it does not understand.
.. attribute:: CANCEL
The ``"cancel"`` type:
The form-submitting entity has cancelled submission of data to the
form-processing entity.
.. attribute:: RESULT
The ``"result"`` type:
The form-processing entity is returning data (e.g., search results) to
the form-submitting entity, or the data is a generic data set.
"""
FORM = "form"
SUBMIT = "submit"
RESULT = "result"
CANCEL = "cancel"
class Data(AbstractItem):
"""
A :xep:`4` ``x`` element, that is, a Data Form.
:param type_: Initial value for the :attr:`type_` attribute.
.. attribute:: type_
The ``type`` attribute of the form, represented by one of the members of
the :class:`DataType` enumeration.
.. attribute:: title
The (optional) title of the form. Either a :class:`str` or :data:`None`.
.. attribute:: instructions
A sequence of strings which represent the instructions elements on the
form.
.. attribute:: fields
If the :class:`Data` is a form, this is a sequence of :class:`Field`
elements which represent the fields to be filled in.
This does not make sense on :attr:`.DataType.RESULT` typed objects.
.. attribute:: items
If the :class:`Data` is a table, this is a sequence of :class:`Item`
instances which represent the table rows.
This only makes sense on :attr:`.DataType.RESULT` typed objects.
.. attribute:: reported
If the :class:`Data` is a table, this is a :class:`Reported` object
representing the table header.
This only makes sense on :attr:`.DataType.RESULT` typed objects.
.. automethod:: get_form_type
"""
TAG = (namespaces.xep0004_data, "x")
type_ = xso.Attr(
"type",
type_=xso.EnumCDataType(DataType)
)
title = xso.ChildText(
(namespaces.xep0004_data, "title"),
default=None,
)
instructions = xso.ChildValueList(
type_=InstructionsElement()
)
items = xso.ChildList([Item])
reported = xso.Child([Reported], required=False)
def __init__(self, type_):
super().__init__()
self.type_ = type_
def _validate_result(self):
if self.fields:
raise ValueError("field in report result")
fieldvars = {field.var for field in self.reported.fields}
if not fieldvars:
raise ValueError("empty report header")
for item in self.items:
itemvars = {field.var for field in item.fields}
if itemvars != fieldvars:
raise ValueError("field mismatch between row and header")
def validate(self):
super().validate()
if (self.type_ != DataType.RESULT and
(self.reported is not None or self.items)):
raise ValueError("report in non-result")
if (self.type_ == DataType.RESULT and
(self.reported is not None or self.items)):
self._validate_result()
def get_form_type(self):
"""
Extract the ``FORM_TYPE`` from the fields.
:return: ``FORM_TYPE`` value or :data:`None`
:rtype: :class:`str` or :data:`None`
Return :data:`None` if no well-formed ``FORM_TYPE`` field is found in
the list of fields.
.. versionadded:: 0.8
"""
for field in self.fields:
if field.var == "FORM_TYPE" and field.type_ == FieldType.HIDDEN:
if len(field.values) != 1:
return None
return field.values[0]
aioxmpp.Message.xep0004_data = xso.ChildList([Data])