1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
########################################################################
# File name: __init__.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/>.
#
########################################################################
"""
:mod:`~aioxmpp.forms` --- Data Forms support (:xep:`4`)
#######################################################
This subpackage contains tools to deal with :xep:`4` 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 :class:`Form` class exists for use cases where automated processing of
Data Forms is supposed to happen. The
:ref:`api-aioxmpp.forms-declarative-style` allow convenient access to and
manipulation of form data from within code.
* Direct use of the :class:`Data` XSO is advisable if you want to present forms
or data to sentient beings: even though :class:`Form` is more convenient for
machine-to-machine use, using the :class:`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).
.. versionadded:: 0.7
Even though the :mod:`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
===========================
:mod:`aioxmpp.forms` adds the following attributes to stanzas:
.. attribute:: aioxmpp.Message.xep0004_data
A sequence of :class:`Data` instances. This is used for example by the
:mod:`~.muc` implementation (:xep:`45`).
.. versionadded:: 0.8
.. _api-aioxmpp.forms-declarative-style:
Declarative-style Forms
=======================
Base class
----------
.. autoclass:: Form
Fields
------
Text fields
~~~~~~~~~~~
.. autoclass:: TextSingle(var, type_=xso.String(), *[, default=None][, required=False][, desc=None][, label=None])
.. autoclass:: TextPrivate(var, type_=xso.String(), *[, default=None][, required=False][, desc=None][, label=None])
.. autoclass:: TextMulti(var, type_=xso.String(), *[, default=()][, required=False][, desc=None][, label=None])
JID fields
~~~~~~~~~~
.. autoclass:: JIDSingle(var, *[, default=None][, required=False][, desc=None][, label=None])
.. autoclass:: JIDMulti(var, *[, default=()][, required=False][, desc=None][, label=None])
Selection fields
~~~~~~~~~~~~~~~~
.. autoclass:: ListSingle(var, type_=xso.String(), *[, default=None][, options=[]][, required=False][, desc=None][, label=None])
.. autoclass:: ListMulti(var, type_=xso.String(), *[, default=frozenset()][, options=[]][, required=False][, desc=None][, label=None])
Other fields
~~~~~~~~~~~~
.. autoclass:: Boolean(var, *[, default=False][, required=False][, desc=None][, label=None])
Abstract base classes
~~~~~~~~~~~~~~~~~~~~~
.. currentmodule:: aioxmpp.forms.fields
.. autoclass:: AbstractField
.. autoclass:: AbstractChoiceField(var, type_=xso.String(), *[, options=[]][, required=False][, desc=None][, label=None])
.. currentmodule:: aioxmpp.forms
.. _api-aioxmpp.forms-bound-fields:
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 :attr:`~.AbstractField.desc`).
For the different field types, there are different classes of bound fields,
which are documented below.
.. currentmodule:: aioxmpp.forms.fields
.. autoclass:: BoundField
.. autoclass:: BoundSingleValueField
.. autoclass:: BoundMultiValueField
.. autoclass:: BoundOptionsField
.. autoclass:: BoundSelectField
.. autoclass:: BoundMultiSelectField
.. currentmodule:: aioxmpp.forms
XSOs
====
.. autoclass:: Data
.. autoclass:: DataType
.. autoclass:: Field
.. autoclass:: FieldType
Report and table support
------------------------
.. autoclass:: Reported
.. autoclass:: Item
""" # NOQA: E501
from . import xso # NOQA: F401
from .xso import ( # NOQA: F401
Data,
DataType,
Field,
FieldType,
Reported,
Item,
)
from .fields import ( # NOQA: F401
Boolean,
ListSingle,
ListMulti,
JIDSingle,
JIDMulti,
TextSingle,
TextMulti,
TextPrivate,
)
from .form import ( # NOQA: F401
Form,
)
|
