########################################################################
# File name: fields.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
# <http://www.gnu.org/licenses/>.
#
########################################################################
import abc
import collections
import copy
import aioxmpp.xso as xso
from . import xso as forms_xso
descriptor_ns = "{jabber:x:data}field"
FIELD_DOCSTRING_TEMPLATE = """
``{field_type.value}`` field ``{var}``
{label}
"""
[docs]class BoundField(metaclass=abc.ABCMeta):
"""
Abstract base class for objects returned by the field descriptors.
:param field: field descriptor to bind
:type field: :class:`AbstractField`
:param instance: form instance to bind to
:type instance: :class:`object`
:class:`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
:attr:`desc`, :attr:`label` and :attr:`required` (and possibly
:attr:`.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
:class:`.Data` XSO when creating a form with :meth:`.Form.from_xso`: it
allows the fields to behave exactly like the sender specified.
Deep-copying a :class:`BoundField` deepcopies all attributes, except the
:attr:`field` and :attr:`instance` attributes. See also :meth:`clone_for`
for copying a bound field for a new `instance`.
Subclass overview:
.. autosummary::
BoundSingleValueField
BoundMultiValueField
BoundSelectField
BoundMultiSelectField
Binding relationship:
.. autoattribute:: field
.. attribute:: instance
The `instance` as passed to the constructor.
Field metadata attributes:
.. autoattribute:: desc
.. autoattribute:: label
.. autoattribute:: required
Helper methods:
.. automethod:: clone_for
The following methods must be implemented by base classes.
.. automethod:: load
.. automethod:: render
"""
def __init__(self, field, instance):
super().__init__()
self._field = field
self.instance = instance
@property
def field(self):
"""
The field which is bound to the :attr:`instance`.
"""
return self._field
def __repr__(self):
return "<bound {!r} for {!r} at 0x{:x}>".format(
self._field,
self.instance,
id(self),
)
def __deepcopy__(self, memo):
result = copy.copy(self)
for k, v in self.__dict__.items():
if k == "_field" or k == "instance":
continue
setattr(result, k, copy.deepcopy(v, memo))
return result
@property
def desc(self):
"""
.. seealso::
:attr:`.Field.desc`
for a full description of the ``desc`` semantics.
"""
try:
return self._desc
except AttributeError:
return self._field.desc
@desc.setter
def desc(self, value):
self._desc = value
@property
def label(self):
"""
.. seealso::
:attr:`.Field.label`
for a full description of the ``label`` semantics.
"""
try:
return self._label
except AttributeError:
return self._field.label
@label.setter
def label(self, value):
self._label = value
@property
def required(self):
"""
.. seealso::
:attr:`.Field.required`
for a full description of the ``required`` semantics.
"""
try:
return self._required
except AttributeError:
return self._field.required
@required.setter
def required(self, value):
self._required = value
[docs] def clone_for(self, other_instance, memo=None):
"""
Clone this bound field for another instance, possibly during a
:func:`~copy.deepcopy` operation.
:param other_instance: Another form instance to which the newly created
bound field shall be bound.
:type other_instance: :class:`object`
:param memo: Optional deepcopy-memo (see :mod:`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 :attr:`instance`
afterwards.
"""
if memo is None:
result = copy.deepcopy(self)
else:
result = copy.deepcopy(self, memo)
result.instance = other_instance
return result
[docs] @abc.abstractmethod
def load(self, field_xso):
"""
Load the field information from a data field.
:param field_xso: XSO describing the field.
:type field_xso: :class:`~.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 :attr:`desc`, :attr:`label`
and :attr:`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
:func:`super`.
"""
if field_xso.desc:
self._desc = field_xso.desc
if field_xso.label:
self._label = field_xso.label
self._required = field_xso.required
[docs] @abc.abstractmethod
def render(self, *, use_local_metadata=True):
"""
Return a :class:`~.Field` containing the values and metadata set in the
field.
:param use_local_metadata: if true, the description, label and required
metadata can be sourced from the field
descriptor associated with this bound field.
:type use_local_metadata: :class:`bool`
:return: A new :class:`~.Field` instance.
The returned object uses the values accessible through this object;
that means, any values set for e.g. :attr:`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 :class:`~.Field` instance
and initialises its :attr:`~.Field.var`, :attr:`~.Field.type_`,
:attr:`~.Field.desc`, :attr:`~.Field.required` and
:attr:`~.Field.label` attributes and returns the result. Subclasses are
supposed to override this method, call the base implementation through
:func:`super` to obtain the :class:`~.Field` instance and then fill in
the values and/or options.
"""
result = forms_xso.Field(
var=self.field.var,
type_=self.field.FIELD_TYPE,
)
if use_local_metadata:
result.desc = self.desc
result.label = self.label
result.required = self.required
else:
try:
result.desc = self._desc
except AttributeError:
pass
try:
result.label = self._label
except AttributeError:
pass
try:
result.required = self._required
except AttributeError:
pass
return result
[docs]class BoundSingleValueField(BoundField):
"""
A bound field which has only a single value at any time. Only the first
value is parsed when loading data from a :class:`~.Field` XSO. When writing
data to a :class:`~.Field` XSO, :data:`None` is treated as the absence of
any value; every other value is serialised through the
:attr:`~.AbstractField.type_` of the field.
.. seealso::
:class:`BoundField`
for a description of the arguments.
This bound field is used by :class:`TextSingle`, :class:`TextPrivate` and
:class:`JIDSingle`.
.. autoattribute:: value
"""
@property
def value(self):
"""
The current value of the field. If no value is set when this attribute
is accessed for reading, the :meth:`default` of the field is invoked
and the result is set and returned as value.
Only values which pass through :meth:`~.AbstractCDataType.coerce` of
the :attr:`~.AbstractField.type_` of the field can be set. To
revert the :attr:`value` to its default, use the ``del`` operator.
"""
try:
return self._value
except AttributeError:
# call through to field
self._value = self._field.default()
return self._value
@value.setter
def value(self, value):
self._value = self._field.type_.coerce(value)
@value.deleter
def value(self):
try:
del self._value
except AttributeError:
pass
def load(self, field_xso):
try:
value = field_xso.values[0]
except IndexError:
value = self._field.default()
else:
value = self._field.type_.parse(value)
self._value = value
super().load(field_xso)
def render(self, **kwargs):
result = super().render(**kwargs)
try:
value = self._value
except AttributeError:
value = self._field.default()
if value is None:
return result
result.values[:] = [
self.field.type_.format(value)
]
return result
[docs]class BoundMultiValueField(BoundField):
"""
A bound field which can have multiple values.
.. seealso::
:class:`BoundField`
for a description of the arguments.
This bound field is used by :class:`TextMulti` and :class:`JIDMulti`.
.. autoattribute:: value
"""
@property
def value(self):
"""
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 :meth:`~.AbstractCDataType.coerce` method of the
:attr:`~.AbstractField.type_` of the field. To revert the
:attr:`value` to its default, use the ``del`` operator.
"""
try:
return self._value
except AttributeError:
self.value = self._field.default()
return self._value
@value.setter
def value(self, values):
coerce = self._field.type_.coerce
self._value = tuple(
coerce(v)
for v in values
)
@value.deleter
def value(self):
try:
del self._value
except AttributeError:
pass
def load(self, field_xso):
self._value = tuple(
self._field.type_.parse(v)
for v in field_xso.values
)
super().load(field_xso)
def render(self, **kwargs):
result = super().render(**kwargs)
result.values[:] = (
self.field.type_.format(v)
for v in self._value
)
return result
[docs]class BoundOptionsField(BoundField):
"""
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.
.. seealso::
:class:`BoundField`
for a description of the arguments.
When the field is loaded from a :class:`~.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:
.. autosummary::
BoundSelectField
BoundMultiSelectField
.. autoattribute:: options
"""
@property
def options(self):
"""
This is a :class:`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
:meth:`~.AbstractCDataType.coerce` method of the
:attr:`~.AbstractField.type_` of the field. To make the :attr:`options`
attribute identical to the :attr:`~.AbstractField.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 :class:`~.AbstractChoiceField.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.
"""
try:
return self._options
except AttributeError:
return self.field.options
@options.setter
def options(self, value):
iterator = (value.items()
if isinstance(value, collections.abc.Mapping)
else value)
self._options = collections.OrderedDict(
(self.field.type_.coerce(k), v)
for k, v in iterator
)
@options.deleter
def options(self):
try:
del self._options
except AttributeError:
pass
def load(self, field_xso):
self._options = collections.OrderedDict(
field_xso.options
)
super().load(field_xso)
def render(self, **kwargs):
format_ = self._field.type_.format
field_xso = super().render(**kwargs)
field_xso.options.update(
(format_(k), v)
for k, v in self.options.items()
)
return field_xso
[docs]class BoundSelectField(BoundOptionsField):
"""
Bound field carrying one value out of a set of options.
.. seealso::
:class:`BoundField`
for a description of the arguments.
:attr:`BoundOptionsField.options`
for semantics and behaviour of the ``options`` attribute
.. autoattribute:: value
"""
@property
def value(self):
"""
The current value of the field. If no value is set when this attribute
is accessed for reading, the :meth:`default` of the field is invoked
and the result is set and returned as value.
Only values contained in the :attr:`~.BoundOptionsField.options` can be
set, other values are rejected with a :class:`ValueError`. To revert
the value to the default value specified in the descriptor, use the
``del`` operator.
"""
try:
return self._value
except AttributeError:
self._value = self.field.default()
return self._value
@value.setter
def value(self, value):
options = self.options
if value not in options:
raise ValueError("{!r} not in field options: {!r}".format(
value,
tuple(options.keys()),
))
self._value = value
@value.deleter
def value(self):
try:
del self._value
except AttributeError:
pass
def load(self, field_xso):
try:
value = field_xso.values[0]
except IndexError:
try:
del self._value
except AttributeError:
pass
else:
self._value = self.field.type_.parse(value)
super().load(field_xso)
def render(self, **kwargs):
format_ = self._field.type_.format
field_xso = super().render(**kwargs)
value = self.value
if value is not None:
field_xso.values[:] = [format_(value)]
return field_xso
[docs]class BoundMultiSelectField(BoundOptionsField):
"""
Bound field carrying a subset of values out of a set of options.
.. seealso::
:class:`BoundField`
for a description of the arguments.
:attr:`BoundOptionsField.options`
for semantics and behaviour of the ``options`` attribute
.. autoattribute:: value
"""
@property
def value(self):
"""
A :class:`frozenset` whose elements are a subset of the keys of the
:attr:`~.BoundOptionsField.options` mapping.
This value can be written with any iterable; the iterable is then
evaluated into a :class:`frozenset`. If it contains any value not
contained in the set of keys of options, the attribute is not written
and :class:`ValueError` is raised.
To revert the value to the default specified by the field descriptor,
use the ``del`` operator.
"""
try:
return self._value
except AttributeError:
self.value = self.field.default()
return self._value
@value.setter
def value(self, values):
new_values = frozenset(values)
options = set(self.options.keys())
invalid = new_values - options
if invalid:
raise ValueError(
"{!r} not in field options: {!r}".format(
next(iter(invalid)),
tuple(self.options.keys())
)
)
self._value = new_values
@value.deleter
def value(self):
try:
del self._value
except AttributeError:
pass
def load(self, field_xso):
self._value = frozenset(
self.field.type_.parse(value)
for value in field_xso.values
)
super().load(field_xso)
def render(self, **kwargs):
format_ = self.field.type_.format
result = super().render(**kwargs)
result.values[:] = [
format_(value)
for value in self.value
]
return result
class AbstractDescriptor(metaclass=abc.ABCMeta):
attribute_name = None
root_class = None
@abc.abstractmethod
def descriptor_keys(self):
"""
Return an iterator with the descriptor keys for this descriptor. The
keys will be added to the :attr:`DescriptorClass.DESCRIPTOR_KEYS`
mapping, pointing to the descriptor.
Duplicate keys will lead to a :class:`TypeError` being raised during
declaration of the class.
"""
[docs]class AbstractField(AbstractDescriptor):
"""
Abstract base class to implement field descriptor classes.
:param var: The field ``var`` attribute this descriptor is supposed to
represent.
:type var: :class:`str`
:param type_: The type of the data, defaults to :class:`~.xso.String`.
:type type_: :class:`~.xso.AbstractCDataType`
:param required: Flag to indicate that the field is required.
:type required: :class:`bool`
:param desc: Description text for the field, e.g. for tool-tips.
:type desc: :class:`str`, without newlines
:param label: Short, human-readable label for the field
:type label: :class:`str`
The arguments are used to initialise the respective attributes. Details on
the semantics can be found in the respective documentation pieces below.
.. autoattribute:: desc
.. attribute:: label
Represents the label flag as specified per :xep:`4`.
The value of this attribute is used when forms are generated locally.
When forms are received from remote peers and :class:`~.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.
.. seealso::
:attr:`~.Field.label`
for details on the semantics of this attribute
.. attribute:: required
Represents the required flag as specified per :xep:`4`.
The value of this attribute is used when forms are generated locally.
When forms are received from remote peers and :class:`~.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.
.. seealso::
:attr:`~.Field.required`
for details on the semantics of this attribute
.. autoattribute:: var
.. automethod:: create_bound
.. automethod:: default
.. automethod:: make_bound
"""
def __init__(self, var, type_, *, required=False, desc=None, label=None):
super().__init__()
self._var = var
self.required = required
self.desc = desc
self.label = label
self._type = type_
self.__doc__ = FIELD_DOCSTRING_TEMPLATE.format(
field_type=self.FIELD_TYPE,
var=self.var,
desc=self.desc,
label=self.label,
)
def descriptor_keys(self):
yield descriptor_ns, self._var
@property
def type_(self):
"""
:class:`.AbstractCDataType` instance used to parse, validate and
format the value(s) of this field.
The type of a field cannot be changed after its initialisation.
"""
return self._type
@property
def desc(self):
"""
Represents the description as specified per :xep:`4`.
The value of this attribute is used when forms are generated locally.
When forms are received from remote peers and :class:`~.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.
.. seealso::
:attr:`~.Field.desc`
for details on the semantics of this attribute
"""
return self._desc
@desc.setter
def desc(self, value):
if value is not None and any(ch == "\r" or ch == "\n" for ch in value):
raise ValueError("desc must not contain newlines")
self._desc = value
@desc.deleter
def desc(self):
self._desc = None
@property
def var(self):
"""
Represents the field ID as specified per :xep:`4`.
The value of this attribute is used to match fields when instantiating
:class:`~.Form` classes from :class:`~.Data` XSOs.
.. seealso::
:attr:`~.Field.var`
for details on the semantics of this attribute
"""
return self._var
[docs] @abc.abstractmethod
def default(self):
"""
Create and return a default value for this field.
This must be implemented by subclasses.
"""
[docs] @abc.abstractmethod
def create_bound(self, for_instance):
"""
Create a :ref:`bound field class <api-aioxmpp.forms-bound-fields>`
instance for this field for the given form object and return it.
:param for_instance: The form instance to which the bound field should
be bound.
This method must be re-implemented by subclasses.
.. seealso::
:meth:`make_bound`
creates (using this method) or returns an existing bound field
for a given form instance.
"""
[docs] def make_bound(self, for_instance):
"""
Create a new :ref:`bound field class <api-aioxmpp.forms-bound-fields>`
or return an existing one for the given form object.
:param 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 :meth:`create_bound`, stored at the
instance and returned. Otherwise, the existing instance is returned.
.. seealso::
:meth:`create_bound`
creates a new bound field for the given form instance (without
storing it anywhere).
"""
try:
return for_instance._descriptor_data[self]
except KeyError:
bound = self.create_bound(for_instance)
for_instance._descriptor_data[self] = bound
return bound
def __get__(self, instance, type_):
if instance is None:
return self
return self.make_bound(instance)
[docs]class TextSingle(AbstractField):
"""
Represent a ``"text-single"`` input with the given `var`.
:param default: A default value to initialise the field.
.. seealso::
:class:`~.fields.BoundSingleValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.TEXT_SINGLE
def __init__(self, var, type_=xso.String(), *,
default=None,
**kwargs):
super().__init__(var, type_, **kwargs)
self._default = default
def default(self):
return self._default
def create_bound(self, for_instance):
return BoundSingleValueField(
self,
for_instance,
)
[docs]class JIDSingle(AbstractField):
"""
Represent a ``"jid-single"`` input with the given `var`.
:param default: A default value to initialise the field.
.. seealso::
:class:`~.fields.BoundSingleValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.JID_SINGLE
def __init__(self, var, *, default=None, **kwargs):
super().__init__(var, type_=xso.JID(), **kwargs)
self._default = default
def default(self):
return self._default
def create_bound(self, for_instance):
return BoundSingleValueField(
self,
for_instance,
)
[docs]class Boolean(AbstractField):
"""
Represent a ``"boolean"`` input with the given `var`.
:param default: A default value to initialise the field.
.. seealso::
:class:`~.fields.BoundSingleValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.BOOLEAN
def __init__(self, var, *, default=False, **kwargs):
super().__init__(var, xso.Bool(), **kwargs)
self._default = default
def default(self):
return self._default
def create_bound(self, for_instance):
return BoundSingleValueField(
self,
for_instance,
)
[docs]class TextPrivate(TextSingle):
"""
Represent a ``"text-private"`` input with the given `var`.
:param default: A default value to initialise the field.
.. seealso::
:class:`~.fields.BoundSingleValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.TEXT_PRIVATE
[docs]class TextMulti(AbstractField):
"""
Represent a ``"text-multi"`` input with the given `var`.
:param default: A default value to initialise the field.
:type default: :class:`tuple`
.. seealso::
:class:`~.fields.BoundMultiValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.TEXT_MULTI
def __init__(self, var, type_=xso.String(), *,
default=(), **kwargs):
super().__init__(var, type_, **kwargs)
self._default = default
def create_bound(self, for_instance):
return BoundMultiValueField(self, for_instance)
def default(self):
return self._default
[docs]class JIDMulti(AbstractField):
"""
Represent a ``"jid-multi"`` input with the given `var`.
:param default: A default value to initialise the field.
:type default: :class:`tuple`
.. seealso::
:class:`~.fields.BoundMultiValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.JID_MULTI
def __init__(self, var, *, default=(), **kwargs):
super().__init__(var, xso.JID(), **kwargs)
self._default = default
def create_bound(self, for_instance):
return BoundMultiValueField(self, for_instance)
def default(self):
return self._default
[docs]class AbstractChoiceField(AbstractField):
"""
Abstract base class to implement field descriptor classes using options.
:param type_: Type used for the option keys.
:type type_: :class:`~.xso.AbstractCDataType`
:param options: A sequence of key-value pairs or a mapping object
representing the options available.
:type options: sequence of pairs or mapping
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 :meth:`~.xso.AbstractCDataType.coerce` (this is enforced
when the field is instantiated).
Fields using this base class:
.. autosummary::
aioxmpp.forms.ListSingle
aioxmpp.forms.ListMulti
.. seealso::
:class:`~.fields.BoundOptionsField`
is an abstract base class to implement :ref:`bound field classes
<api-aioxmpp.forms-bound-fields>` for fields inheriting from this
class.
:class:`~.fields.AbstractField`
for documentation on the `var`, `required`, `desc` and `label`
arguments.
"""
def __init__(self, var, *,
type_=xso.String(),
options=[],
**kwargs):
super().__init__(var, type_, **kwargs)
iterator = (options.items()
if isinstance(options, collections.abc.Mapping)
else options)
self.options = collections.OrderedDict(
(type_.coerce(k), v)
for k, v in iterator
)
self._type = type_
@property
def type_(self):
return self._type
[docs]class ListSingle(AbstractChoiceField):
"""
Represent a ``"list-single"`` input with the given `var`.
:param default: A default value to initialise the field. This must be a
member of the `options`.
.. seealso::
:class:`~.fields.BoundMultiValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractChoiceField`
for documentation on the `options` argument.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.LIST_SINGLE
def __init__(self, var, *, default=None, **kwargs):
super().__init__(var, **kwargs)
if default is not None and default not in self.options:
raise ValueError("invalid default: not in options")
self._default = default
def create_bound(self, for_instance):
return BoundSelectField(self, for_instance)
def default(self):
return self._default
[docs]class ListMulti(AbstractChoiceField):
"""
Represent a ``"list-multi"`` input with the given `var`.
:param default: An iterable of `options` keys
:type default: iterable
`default` is evaluated into a :class:`frozenset` and all elements must be
keys of the `options` mapping argument.
.. seealso::
:class:`~.fields.BoundMultiValueField`
is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
by fields of this type.
:class:`~.fields.AbstractChoiceField`
for documentation on the `options` argument.
:class:`~.fields.AbstractField`
for documentation on the `var`, `type_`, `required`, `desc` and
`label` arguments.
"""
FIELD_TYPE = forms_xso.FieldType.LIST_MULTI
def __init__(self, var, *, default=frozenset(), **kwargs):
super().__init__(var, **kwargs)
self._default = frozenset(default)
if any(value not in self.options for value in self._default):
raise ValueError(
"invalid default: not in options"
)
def create_bound(self, for_instance):
return BoundMultiSelectField(self, for_instance)
def default(self):
return self._default