# `forms` — Data Forms support (XEP-0004)

This subpackage contains tools to deal with XEP-0004 Data Forms. Data Forms is a pervasive and highly flexible protocol used in XMPP. It allows for machine-readable (and processable) forms as well as tables of data. This flexibility comes unfortunately at the price of complexity. This subpackage attempts to take some of the load of processing Data Forms off the application developer.

Cheat Sheet:

- The `Form` class exists for use cases where automated processing of Data Forms is supposed to happen. The Declarative-style Forms allow convenient access to and manipulation of form data from within code.

- Direct use of the `Data` XSO is advisable if you want to present forms or data to sentient beings: even though `Form` is more convenient for machine-to-machine use, using the `Data` sent by the peer easily allows showing the user all fields supported by the peer.

- For machine-processed tables, there is no tooling (yet).

New in version 0.7: Even though the `aioxmpp.forms` module existed pre-0.7, it has not been documented and was thus not part of the public API.

Note

The authors are not entirely happy with the API at some points. Specifically, at some places where mutable data structures are used, the mutation of these data structures may have unexpected side effects. This may be rectified in a future release by replacing these data structures with their appropriate immutable equivalents.

These locations are marked accordingly.

## Attributes added to stanzas

`aioxmpp.forms` adds the following attributes to stanzas:

aioxmpp.Message.xep0004_data

  A sequence of `Data` instances. This is used for example by the `muc` implementation (XEP-0045).

  New in version 0.8.

## Declarative-style Forms

### Base class

class aioxmpp.forms.Form(*args, **kwargs)

  A form template for XEP-0004 Data Forms.

  Fields are declared using the different field descriptors available in this module:

  `TextSingle`(var[, type_, default]) | Represent a `"text-single"` input with the given var.
  `TextMulti`(var[, type_, default]) | Represent a `"text-multi"` input with the given var.
  `TextPrivate`(var[, type_, default]) | Represent a `"text-private"` input with the given var.
  `JIDSingle`(var, *[, default]) | Represent a `"jid-single"` input with the given var.
  `JIDMulti`(var, *[, default]) | Represent a `"jid-multi"` input with the given var.
  `ListSingle`(var, *[, default]) | Represent a `"list-single"` input with the given var.
  `ListMulti`(var, *[, default]) | Represent a `"list-multi"` input with the given var.
  `Boolean`(var, *[, default]) | Represent a `"boolean"` input with the given var.

  A form template can be instantiated by two different means:

  1. the `from_xso()` method can be called on a `xso.Data` instance to fill in the template with the data from the XSO.

  2. the constructor can be called.

  With the first method, labels, descriptions, options and values are taken from the XSO. The descriptors declared on the form merely act as a convenient way to access the fields in the XSO.

  If a field is missing from the XSO, its descriptor still works as if the form had been constructed using its constructor. It will not be emitted when re-serialising the form for a response using `render_reply()`.

  If the XSO has more fields than the form template, these fields are re-emitted when the form is serialised using `render_reply()`.

  LAYOUT

    A mixed list of descriptors and strings to determine form layout as generated by `render_request()`. The semantics are the following:

    - each `str` is converted to a `"fixed"` field without `var` attribute in the output.

    - each `AbstractField` descriptor is rendered to its corresponding `Field` XSO.

    The elements of `LAYOUT` are processed in-order. This attribute is optional and can be set on either the `Form` or a specific instance. If it is absent, it is treated as if it were set to `list(self.DESCRIPTORS)`.

  classmethod from_xso(xso)

    Construct and return an instance from the given xso.

    Note

    This is a static method (classmethod), even though sphinx does not document it as such.

    Parameters

      xso (`Data`) – A XEP-0004 data form

    Raises

      - ValueError – if the `FORM_TYPE` mismatches

      - ValueError – if field types mismatch

    Returns

      newly created instance of this class

    The fields from the given xso are matched against the fields on the form. Any matching field loads its data from the xso field. Fields which occur on the form template but not in the xso are skipped. Fields which occur in the xso but not on the form template are also skipped (but are re-emitted when the form is rendered as reply, see `render_reply()`).

    If the form template has a `FORM_TYPE` attribute and the incoming xso also has a `FORM_TYPE` field, a mismatch between the two values leads to a `ValueError`.

    The field types of matching fields are checked. If the field type on the incoming XSO may not be upcast to the field type declared on the form (see `allow_upcast()`), a `ValueError` is raised.

    If the `type_` does not indicate an actual form (but rather a cancellation request or tabular result), `ValueError` is raised.

  render_reply()

    Create a `Data` object equal to the object from which the from was created through `from_xso()`, except that the values of the fields are exchanged with the values set on the form.

    Fields which have no corresponding form descriptor are left untouched. Fields which are accessible through form descriptors, but are not in the original `Data` are not included in the output.

    This method only works on forms created through `from_xso()`.

    The resulting `Data` instance has the `type_` set to `SUBMIT`.

  render_request()

    Create a `Data` object containing all fields known to the `Form`. If the `Form` has a `LAYOUT` attribute, it is used during generation.

### Fields

#### Text fields

class aioxmpp.forms.TextSingle(var, type_=xso.String(), *[, default=None][, required=False][, desc=None][, label=None])

  Represent a `"text-single"` input with the given var.

  Parameters

    default – A default value to initialise the field.

  See also

  `BoundSingleValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

class aioxmpp.forms.TextPrivate(var, type_=xso.String(), *[, default=None][, required=False][, desc=None][, label=None])

  Represent a `"text-private"` input with the given var.

  Parameters

    default – A default value to initialise the field.

  See also

  `BoundSingleValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

class aioxmpp.forms.TextMulti(var, type_=xso.String(), *[, default=()][, required=False][, desc=None][, label=None])

  Represent a `"text-multi"` input with the given var.

  Parameters

    default (`tuple`) – A default value to initialise the field.

  See also

  `BoundMultiValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

#### JID fields

class aioxmpp.forms.JIDSingle(var, *[, default=None][, required=False][, desc=None][, label=None])

  Represent a `"jid-single"` input with the given var.

  Parameters

    default – A default value to initialise the field.

  See also

  `BoundSingleValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, required, desc and label arguments.

class aioxmpp.forms.JIDMulti(var, *[, default=()][, required=False][, desc=None][, label=None])

  Represent a `"jid-multi"` input with the given var.

  Parameters

    default (`tuple`) – A default value to initialise the field.

  See also

  `BoundMultiValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

#### Selection fields

class aioxmpp.forms.ListSingle(var, type_=xso.String(), *[, default=None][, options=[]][, required=False][, desc=None][, label=None])

  Represent a `"list-single"` input with the given var.

  Parameters

    default – A default value to initialise the field. This must be a member of the options.

  See also

  `BoundMultiValueField`

    is the bound field class used by fields of this type.

  `AbstractChoiceField`

    for documentation on the options argument.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

class aioxmpp.forms.ListMulti(var, type_=xso.String(), *[, default=frozenset()][, options=[]][, required=False][, desc=None][, label=None])

  Represent a `"list-multi"` input with the given var.

  Parameters

    default (iterable) – An iterable of options keys

  default is evaluated into a `frozenset` and all elements must be keys of the options mapping argument.

  See also

  `BoundMultiValueField`

    is the bound field class used by fields of this type.

  `AbstractChoiceField`

    for documentation on the options argument.

  `AbstractField`

    for documentation on the var, type_, required, desc and label arguments.

#### Other fields

class aioxmpp.forms.Boolean(var, *[, default=False][, required=False][, desc=None][, label=None])

  Represent a `"boolean"` input with the given var.

  Parameters

    default – A default value to initialise the field.

  See also

  `BoundSingleValueField`

    is the bound field class used by fields of this type.

  `AbstractField`

    for documentation on the var, required, desc and label arguments.

#### Abstract base classes

class aioxmpp.forms.fields.AbstractField(var, type_, *, required=False, desc=None, label=None)

  Abstract base class to implement field descriptor classes.

  Parameters

    - var (`str`) – The field `var` attribute this descriptor is supposed to represent.

    - type (`AbstractCDataType`) – The type of the data, defaults to `String`.

    - required (`bool`) – Flag to indicate that the field is required.

    - desc (`str`, without newlines) – Description text for the field, e.g. for tool-tips.

    - label (`str`) – Short, human-readable label for the field

  The arguments are used to initialise the respective attributes. Details on the semantics can be found in the respective documentation pieces below.

  desc

    Represents the description as specified per XEP-0004.

    The value of this attribute is used when forms are generated locally. When forms are received from remote peers and `Form` instances are constructed from that data, this attribute is not used when rendering a reply or when the value is accessed through the bound field.

    See also

    `desc`

      for details on the semantics of this attribute

  label

    Represents the label flag as specified per XEP-0004.

    The value of this attribute is used when forms are generated locally. When forms are received from remote peers and `Form` instances are constructed from that data, this attribute is not used when rendering a reply or when the value is accessed through the bound field.

    > See also

    > `label`

    >   for details on the semantics of this attribute

  required

    Represents the required flag as specified per XEP-0004.

    The value of this attribute is used when forms are generated locally. When forms are received from remote peers and `Form` instances are constructed from that data, this attribute is not used when rendering a reply or when the value is accessed through the bound field.

    > See also

    > `required`

    >   for details on the semantics of this attribute

  var

    Represents the field ID as specified per XEP-0004.

    The value of this attribute is used to match fields when instantiating `Form` classes from `Data` XSOs.

    See also

    `var`

      for details on the semantics of this attribute

  abstract create_bound(for_instance)

    Create a bound field class instance for this field for the given form object and return it.

    Parameters

      for_instance – The form instance to which the bound field should be bound.

    This method must be re-implemented by subclasses.

    See also

    `make_bound()`

      creates (using this method) or returns an existing bound field for a given form instance.

  abstract default()

    Create and return a default value for this field.

    This must be implemented by subclasses.

  make_bound(for_instance)

    Create a new bound field class or return an existing one for the given form object.

    Parameters

      for_instance – The form instance to which the bound field should be bound.

    If no bound field can be found on the given for_instance for this field, a new one is created using `create_bound()`, stored at the instance and returned. Otherwise, the existing instance is returned.

    See also

    `create_bound()`

      creates a new bound field for the given form instance (without storing it anywhere).

class aioxmpp.forms.fields.AbstractChoiceField(var, type_=xso.String(), *[, options=[]][, required=False][, desc=None][, label=None])

  Abstract base class to implement field descriptor classes using options.

  Parameters

    - type (`AbstractCDataType`) – Type used for the option keys.

    - options (sequence of pairs or mapping) – A sequence of key-value pairs or a mapping object representing the options available.

  The keys of the options mapping (or the first elements in the pairs in the sequence of pairs) must be compatible with type_, in the sense that must pass through `coerce()` (this is enforced when the field is instantiated).

  Fields using this base class:

  `aioxmpp.forms.ListSingle`(var, *[, default]) | Represent a `"list-single"` input with the given var.
  `aioxmpp.forms.ListMulti`(var, *[, default]) | Represent a `"list-multi"` input with the given var.

  See also

  `BoundOptionsField`

    is an abstract base class to implement bound field classes for fields inheriting from this class.

  `AbstractField`

    for documentation on the var, required, desc and label arguments.

## Bound fields

Bound fields are objects which are returned when the descriptor attribute is accessed on a form instance. It holds the value of the field, as well as overrides for the default (specified on the descriptors themselves) values for certain attributes (such as `desc`).

For the different field types, there are different classes of bound fields, which are documented below.

class aioxmpp.forms.fields.BoundField(field, instance)

  Abstract base class for objects returned by the field descriptors.

  Parameters

    - field (`AbstractField`) – field descriptor to bind

    - instance (`object`) – form instance to bind to

  `BoundField` instances represent the connection between the field descriptors present at a form class and the instance of that class.

  They store of course the value of the field for the specific instance, but also possible instance-specific overrides for the metadata attributes `desc`, `label` and `required` (and possibly `BoundOptionsField.options`). By default, these attributes return the same value as set on the corresponding field, but the attributes can be set to different values, which only affects the single form instance.

  The use case is to fill these fields with the information obtained from a `Data` XSO when creating a form with `Form.from_xso()`: it allows the fields to behave exactly like the sender specified.

  Deep-copying a `BoundField` deepcopies all attributes, except the `field` and `instance` attributes. See also `clone_for()` for copying a bound field for a new instance.

  Subclass overview:

  `BoundSingleValueField`(field, instance) | A bound field which has only a single value at any time.
  `BoundMultiValueField`(field, instance) | A bound field which can have multiple values.
  `BoundSelectField`(field, instance) | Bound field carrying one value out of a set of options.
  `BoundMultiSelectField`(field, instance) | Bound field carrying a subset of values out of a set of options.

  Binding relationship:

  field

    The field which is bound to the `instance`.

  instance

    The instance as passed to the constructor.

  Field metadata attributes:

  desc

    See also

    `Field.desc`

      for a full description of the `desc` semantics.

  label

    See also

    `Field.label`

      for a full description of the `label` semantics.

  required

    See also

    `Field.required`

      for a full description of the `required` semantics.

  Helper methods:

  clone_for(other_instance, memo=None)

    Clone this bound field for another instance, possibly during a `deepcopy()` operation.

    Parameters

      - other_instance (`object`) – Another form instance to which the newly created bound field shall be bound.

      - memo – Optional deepcopy-memo (see `copy` for details)

    If this is called during a deepcopy operation, passing the memo helps preserving and preventing loops. This method is essentially a deepcopy-operation, with a modification of the `instance` afterwards.

  The following methods must be implemented by base classes.

  abstract load(field_xso)

    Load the field information from a data field.

    Parameters

      field_xso (`Field`) – XSO describing the field.

    This loads the current value, description, label and possibly options from the field_xso, shadowing the information from the declaration of the field on the class.

    This method is must be overridden and is thus marked abstract. However, when called from a subclass, it loads the `desc`, `label` and `required` from the given field_xso. Subclasses are supposed to implement a mechanism to load options and/or values from the field_xso and then call this implementation through `super()`.

  abstract render(*, use_local_metadata=True)

    Return a `Field` containing the values and metadata set in the field.

    Parameters

      use_local_metadata (`bool`) – if true, the description, label and required metadata can be sourced from the field descriptor associated with this bound field.

    Returns

      A new `Field` instance.

    The returned object uses the values accessible through this object; that means, any values set for e.g. `desc` take precedence over the values declared at the class level. If use_local_metadata is false, values declared at the class level are not used if no local values are declared. This is useful when generating a reply to a form received by a peer, as it avoids sending a modified form.

    This method is must be overridden and is thus marked abstract. However, when called from a subclass, it creates the `Field` instance and initialises its `var`, `type_`, `desc`, `required` and `label` attributes and returns the result. Subclasses are supposed to override this method, call the base implementation through `super()` to obtain the `Field` instance and then fill in the values and/or options.

class aioxmpp.forms.fields.BoundSingleValueField(field, instance)

  A bound field which has only a single value at any time. Only the first value is parsed when loading data from a `Field` XSO. When writing data to a `Field` XSO, `None` is treated as the absence of any value; every other value is serialised through the `type_` of the field.

  See also

  `BoundField`

    for a description of the arguments.

  This bound field is used by `TextSingle`, `TextPrivate` and `JIDSingle`.

  value

    The current value of the field. If no value is set when this attribute is accessed for reading, the `default()` of the field is invoked and the result is set and returned as value.

    Only values which pass through `coerce()` of the `type_` of the field can be set. To revert the `value` to its default, use the `del` operator.

class aioxmpp.forms.fields.BoundMultiValueField(field, instance)

  A bound field which can have multiple values.

  See also

  `BoundField`

    for a description of the arguments.

  This bound field is used by `TextMulti` and `JIDMulti`.

  value

    A tuple of values. This attribute can be set with any iterable; the iterable is then evaluated into a tuple and stored at the bound field.

    Whenever values are written to this attribute, they are passed through the `coerce()` method of the `type_` of the field. To revert the `value` to its default, use the `del` operator.

class aioxmpp.forms.fields.BoundOptionsField(field, instance)

  This is an intermediate base class used to implement bound fields for fields which have options from which one or more values must be chosen.

  See also

  `BoundField`

    for a description of the arguments.

  When the field is loaded from a `Field` XSO, the options are also loaded from there and thus shadow the options defined at the field. This may come to a surprise of code expecting a specific set of options.

  Subclass overview:

  `BoundSelectField`(field, instance) | Bound field carrying one value out of a set of options.
  `BoundMultiSelectField`(field, instance) | Bound field carrying a subset of values out of a set of options.

  options

    This is a `collections.OrderedDict` which maps option keys to their labels. The keys are used as the values of the field; the labels are human-readable text for display.

    This attribute can be written with any object which is compatible with the dict-constructor. The order is preserved if a sequence of key-value pairs is used.

    When writing the attribute, the keys are checked against the `coerce()` method of the `type_` of the field. To make the `options` attribute identical to the `options` attribute, use the `del` operator.

    Warning

    This attribute is mutable, however, mutating it directly may have unexpected side effects:

    - If the attribute has not been set before, you will actually be mutating the `options` attributes value.

      This may be changed in the future by copying more eagerly.

    - The type checking cannot take place when keys are added by direct mutation of the dictionary. This means that errors will be delayed until the actual serialisation of the data form, which may be a confusing thing to debug.

    Relying on the above behaviour or any other behaviour induced by directly mutating the value returned by this attribute is not recommended. Changes to this behaviour are not considered breaking changes and will be done without the usual deprecation.

class aioxmpp.forms.fields.BoundSelectField(field, instance)

  Bound field carrying one value out of a set of options.

  See also

  `BoundField`

    for a description of the arguments.

  `BoundOptionsField.options`

    for semantics and behaviour of the `options` attribute

  value

    The current value of the field. If no value is set when this attribute is accessed for reading, the `default()` of the field is invoked and the result is set and returned as value.

    Only values contained in the `options` can be set, other values are rejected with a `ValueError`. To revert the value to the default value specified in the descriptor, use the `del` operator.

class aioxmpp.forms.fields.BoundMultiSelectField(field, instance)

  Bound field carrying a subset of values out of a set of options.

  See also

  `BoundField`

    for a description of the arguments.

  `BoundOptionsField.options`

    for semantics and behaviour of the `options` attribute

  value

    A `frozenset` whose elements are a subset of the keys of the `options` mapping.

    This value can be written with any iterable; the iterable is then evaluated into a `frozenset`. If it contains any value not contained in the set of keys of options, the attribute is not written and `ValueError` is raised.

    To revert the value to the default specified by the field descriptor, use the `del` operator.

## XSOs

class aioxmpp.forms.Data(*args, **kwargs)

  A XEP-0004 `x` element, that is, a Data Form.

  Parameters

    type – Initial value for the `type_` attribute.

  type_

    The `type` attribute of the form, represented by one of the members of the `DataType` enumeration.

  title

    The (optional) title of the form. Either a `str` or `None`.

  instructions

    A sequence of strings which represent the instructions elements on the form.

  fields

    If the `Data` is a form, this is a sequence of `Field` elements which represent the fields to be filled in.

    This does not make sense on `DataType.RESULT` typed objects.

  items

    If the `Data` is a table, this is a sequence of `Item` instances which represent the table rows.

    This only makes sense on `DataType.RESULT` typed objects.

  reported

    If the `Data` is a table, this is a `Reported` object representing the table header.

    This only makes sense on `DataType.RESULT` typed objects.

  get_form_type()

    Extract the `FORM_TYPE` from the fields.

    Returns

      `FORM_TYPE` value or `None`

    Return type

      `str` or `None`

    Return `None` if no well-formed `FORM_TYPE` field is found in the list of fields.

    New in version 0.8.

class aioxmpp.forms.DataType(value)

  Enumeration containing the `Data` types defined in XEP-0004.

  Quotations in the following attribute descriptions are from XEP-0004.

  FORM

    The `"form"` type:

    > The form-processing entity is asking the form-submitting entity to complete a form.

  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.

  CANCEL

    The `"cancel"` type:

    > The form-submitting entity has cancelled submission of data to the form-processing entity.

  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.

class aioxmpp.forms.Field(*args, **kwargs)

  Represent a single field in a Data Form.

  Parameters

    - type (`FieldType`) – Field type, must be one of the valid field types specified in XEP-0004.

    - options (`dict` mapping `str` to `str`) – A mapping of values to labels defining the options in a `list-*` field.

    - values (`list` of `str`) – A sequence of values currently given for the field. Having more than one value is only valid in `*-multi` fields.

    - desc (`str` or `None`) – Description which can be shown in a tool-tip or similar, without newlines.

    - label (`str` or `None`) – Human-readable label to be shown next to the field input

    - required (`bool`) – Flag to indicate that the field is required

    - var (`str` or `None`) – “ID” identifying the field uniquely inside the form. Only required for fields carrying a meaning (thus, not for `fixed`).

  The semantics of a `Field` are different depending on where it occurs: in a `Data`, it is a form field to be filled in, in a `Item` it is a cell of a row and in a `Reported` it represents a column header.

  required

    A boolean flag indicating whether the field is required.

    If true, the XML serialisation will contain the corresponding `<required/>` tag.

  desc

    Single line of description for the field. This attribute represents the `<desc/>` element from XEP-0004.

  values

    A sequence of strings representing the `<value/>` elements of the field, one string for each value.

    Note

    Since the requirements on the sequence of strings in `values` change depending on the `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 `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 `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 `aioxmpp`, as every UI framework has different requirements.

  options

    A dictionary mapping values to human-readable labels, representing the `<option/>` elements of the field.

  var

    The uniquely identifying string of the (valued, that is, non-`FieldType.FIXED` field). Represents the `var` attribute of the field.

  type_

    The type of the field. The `type_` must be a `FieldType` enumeration value and determines restrictions and constraints on other attributes. See the `FieldType` enumeration and XEP-0004 for details.

  label

    The human-readable label for the field, representing the `label` attribute of the field. May be `None` if the label is omitted.

class aioxmpp.forms.FieldType(value)

  Enumeration containing the field types defined in XEP-0004.

  See also

  `Field.values`

    for important information regarding typing, restrictions, validation and constraints of values in that attribute.

  Each type has the following attributes and methods:

  allow_upcast(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 `TEXT_SINGLE` and to is `TEXT_PRIVATE`

  has_options

    true for the `list-` field types, false otherwise.

  is_multivalued

    true for the `-multi` field types, false otherwise.

  Quotations in the following attribute descriptions are from said XEP.

  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 `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.

  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 <value/> child SHOULD NOT contain newlines (the `\n` and `\r` characters); instead an application SHOULD generate multiple fixed fields, each with one <value/> child.

    As such, the `Field.values` sequence should contain exactly one element. `Field.desc`, `Field.label`, `Field.options` and `Field.var` should be set to `None` or empty containers.

  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-0068.

  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 `Field.values` sequence should contain zero or more strings representing Jabber IDs. `Field.options` should be empty.

  JID_SINGLE

    The `"jid-single"` field:

    > The field enables an entity to gather or provide a single Jabber ID.

    As such, the `Field.values` sequence should contain zero or one string representing a Jabber ID. `Field.options` should be empty.

  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, `Field.values` should contain a subset of the keys of the `Field.options` dictionary.

  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, `Field.values` should contain a zero or one of the keys of the `Field.options` dictionary.

  TEXT_MULTI

    The `"text-multi"` field:

    > The field enables an entity to gather or provide multiple lines of text.

    Each string in the `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.

  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 `Field.values` attribute should contain zero or one string without any newlines.

  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 `Field.values` attribute should contain zero or one string without any newlines.

### Report and table support

class aioxmpp.forms.Reported(*args, **kwargs)

  The table heading of a report `Data` object.

  fields

    A sequence of `Field` objects representing the columns of the report or table.

class aioxmpp.forms.Item(*args, **kwargs)

  A single row in a report `Data` object.

  fields

    A sequence of `Field` objects representing the cells of the row.