class MyForm(Form):
    name    = StringField('Full Name', [validators.required(), validators.length(max=10)])
    address = TextAreaField('Mailing Address', [validators.optional(), validators.length(max=200)])

Stores and processes data, and generates HTML for a form field.

Field instances contain the data of that instance as well as the
functionality to render it within your Form. They also contain a number of
properties which can be used within your templates to render the field and
label.

**Construction**

.. automethod:: __init__

Built-in field processing messages can be customized per field with
``invalid_value_message=``.

**Validation**

To validate the field, call its `validate` method, providing a form and any
extra validators needed. To extend validation behaviour, override
`pre_validate` or `post_validate`.

.. automethod:: validate
.. automethod:: pre_validate
.. automethod:: post_validate
.. attribute:: errors

    If `validate` encounters any errors, they will be inserted into this
    list.

**Data access and processing**

To handle incoming data from python, override `process_data`. Similarly, to
handle incoming data from the outside, override `process_formdata`.

.. automethod:: process(formdata [, data])
.. automethod:: process_data
.. automethod:: process_formdata
.. attribute:: data

    Contains the resulting (sanitized) value of calling either of the
    process methods. Note that it is not HTML escaped when using in
    templates.

.. attribute:: raw_data

    If form data is processed, is the valuelist given from the formdata
    wrapper. Otherwise, `raw_data` will be `None`.

.. attribute:: object_data

    This is the data passed from an object or from kwargs to the field,
    stored unmodified. This can be used by templates, widgets, validators
    as needed (for comparison, for example)

**Rendering**

To render a field, simply call it, providing any values the widget expects
as keyword arguments. Usually the keyword arguments are used for extra HTML
attributes.

.. automethod:: __call__

    If one wants to pass the "class" argument which is a reserved keyword
    in some python-based templating languages, one can do::

        form.field(class_="text_blob")

    This will output (for a text field):

    .. code-block:: html

        <input type="text" name="field_name" value="blah" class="text_blob" id="field_name" />

    Note: Simply coercing the field to a string will render it as
    if it was called with no arguments.

.. automethod:: __html__

    Many template engines use the __html__ method when it exists on a
    printed object to get an 'html-safe' string that will not be
    auto-escaped. To allow for printing a bare field without calling it,
    all WTForms fields implement this method as well.

**Message Translations**

.. automethod:: gettext

.. automethod:: ngettext

**Properties**

.. attribute:: name

    The HTML form name of this field. This is the name as defined in your
    Form prefixed with the `prefix` passed to the Form constructor.

.. attribute:: short_name

    The un-prefixed name of this field.

.. attribute:: id

    The HTML ID of this field. If unspecified, this is generated for you to
    be the same as the field name.

.. attribute:: label

    This is a :class:`Label` instance which when evaluated as a string
    returns an HTML :mdn-tag:`label` construct.

.. attribute:: default

    This is whatever you passed as the `default` to the field's
    constructor, otherwise None.

.. attribute:: description

    A string containing the value of the description passed in the
    constructor to the field; this is not HTML escaped.

.. attribute:: errors
   :noindex:

   A sequence containing the validation errors for this field.

.. attribute:: process_errors

   Errors obtained during input processing. These will be prepended to the
   list of errors at validation time.

.. attribute:: widget

    The widget used to render the field.

.. attribute:: type

    The type of this field, as a string. This can be used in your templates
    to do logic based on the type of field:

    .. code-block:: html+django

        {% for field in form %}
            <tr>
            {% if field.type == "BooleanField" %}
                <td></td>
                <td>{{ field }} {{ field.label }}</td>
            {% else %}
                <td>{{ field.label }}</td>
                <td>{{ field }}</td>
            {% endif %}
            </tr>
        {% endfor %}

.. attribute:: flags

    An object containing flags set either by the field itself, or
    by validators on the field. For example, the built-in
    :class:`~wtforms.validators.InputRequired` validator sets the `required` flag.
    An unset flag will result in :const:`None`.

    .. code-block:: html+django

        {% for field in form %}
            <tr>
                <th>{{ field.label }} {% if field.flags.required %}*{% endif %}</th>
                <td>{{ field }}</td>
            </tr>
        {% endfor %}

.. attribute:: meta

    The same :doc:`meta object <meta>` instance as is available as
    :attr:`Form.meta <wtforms.form.Form.meta>`


.. attribute:: filters

    The same sequence of filters that was passed as the ``filters=`` to
    the field constructor. This is usually a sequence of callables.

.. warning::
    :class:`DateTimeField` renders ``<input type="datetime">``, which is
    obsolete in HTML and not broadly supported by browsers. Use
    :class:`DateTimeLocalField` instead.

    :class:`DateTimeField` is deprecated and will be removed in WTForms 3.4.

Example usage::

    class UploadForm(Form):
        image        = FileField('Image File', [validators.regexp(r'^[^/\\]\.jpg$', matcher=re.fullmatch)])
        description  = TextAreaField('Image Description')

        def validate_image(form, field):
            if field.data:
                field.data = re.sub(r'[^a-z0-9_.-]', '_', field.data)

    def upload(request):
        form = UploadForm(request.POST)
        if form.image.data:
            image_data = request.FILES[form.image.name].read()
            open(os.path.join(UPLOAD_PATH, form.image.data), 'w').write(image_data)

    {{ form.username(size=30, maxlength=50) }}

.. code-block:: jinja

    {% for subfield in form.radio %}
        <tr>
            <td>{{ subfield }}</td>
            <td>{{ subfield.label }}</td>
        </tr>
    {% endfor %}

Simply outputting the field without iterating its subfields will result in
a :mdn-tag:`ul` list of radio choices.

Select fields take a ``choices`` parameter which is either:

* a list of :class:`Choice`.
  It can also be a list of only values, in which case the value is used
  as the label. The :class:`Choice` ``render_kw`` mapping is rendered as
  HTML :mdn-tag:`option` parameters. The value can be of any
  type, but because form data is sent to the browser as strings, you
  will need to provide a ``coerce`` function that converts a string
  back to the expected type.
* a function taking no argument, and returning a list of :class:`Choice`.


**Select fields with static choice values**::

    class PastebinEntry(Form):
        language = SelectField('Programming Language', choices=[
            Choice('cpp', 'C++'),
            Choice('py', 'Python'),
            Choice('text', 'Plain Text'),
        ])

Note that the `choices` keyword is evaluated each time the form is
instantiated, so callables passed as `choices` are re-evaluated per instance.
For dynamic options, either pass a callable to `choices` or assign
`field.choices` after instantiation. Any submitted choices which are not in
the given choices list will cause validation on the field to fail. If this
option cannot be applied to your problem you may wish to skip choice
validation (see below).

**Select fields with ``<optgroup>``**::

    Use :class:`SelectChoice` to assign an option to an ``<optgroup>``.

    class PastebinEntry(Form):
        language = SelectField('Programming Language', choices=[
            SelectChoice('cpp', 'C++', optgroup='Compiled'),
            SelectChoice('rs', 'Rust', optgroup='Compiled'),
            SelectChoice('py', 'Python', optgroup='Interpreted'),
            SelectChoice('text', 'Plain Text'),
        ])

**Select fields with dynamic choice values**::

    def available_groups():
        return [Choice(g.id, g.name) for g in Group.query.order_by('name')]

    class UserDetails(Form):
        group_id = SelectField('Group', coerce=int, choices=available_groups)

    def edit_user(request, id):
        user = User.query.get(id)
        form = UserDetails(request.POST, obj=user)

Note we passed a callable to `choices` rather than a static list; it is
invoked each time the form is instantiated, producing fresh options per
request. If the choices depend on data only available in the view, you can
instead assign `form.group_id.choices` after instantiation. The `coerce`
keyword arg to :class:`~wtforms.fields.SelectField` says that we use
:func:`int()` to coerce form data. The default coerce is :func:`str()`.

**Coerce function example**::

    def coerce_none(value):
        if value == 'None':
            return None
        return value

    class NonePossible(Form):
        my_select_field = SelectField('Select an option', choices=[
            Choice('1', 'Option 1'),
            Choice('2', 'Option 2'),
            Choice('None', 'No option'),
        ], coerce=coerce_none)

Note when the option None is selected a 'None' str will be passed. By using a coerce
function the 'None' str will be converted to None.

**Select fields backed by an Enum**::

    from enum import Enum

    class Color(Enum):
        RED = 1
        GREEN = 2
        BLUE = 3

    class PaintForm(Form):
        color = SelectField(choices=Choice.from_enum(Color), coerce=Color)

:meth:`Choice.from_enum` builds the option list from the Enum items;
the HTML ``value`` of each option is the item's ``name``. Passing the
Enum class itself as ``coerce`` installs the matching coercion, so
``form.color.data`` is a ``Color`` item after submit. Pre-selecting
works the usual way, with an Enum item: ``PaintForm(color=Color.RED)``.

By default the option label is ``str(item)`` if the Enum defines its
own ``__str__`` (also the case for :class:`enum.StrEnum`), otherwise
``item.name``. To customise, pass a ``label`` callable taking an Enum
item and returning the label string::

    Choice.from_enum(Color, label=lambda item: item.name.title())
    # → [Choice('RED', 'Red'), Choice('GREEN', 'Green'), Choice('BLUE', 'Blue')]

**Skipping choice validation**::

    class DynamicSelectForm(Form):
        dynamic_select = SelectField("Choose an option", validate_choice=False)

Note the `validate_choice` parameter - by setting this to :const:`False` we
are telling the SelectField to skip the choice validation step and instead
to accept any inputted choice without checking to see if it was one of the
given choices. This should only really be used in situations where you
cannot use dynamic choice values as shown above - for example where the
choices of a :class:`~wtforms.fields.SelectField` are determined
dynamically by another field on the page, such as choosing a country and
state/region.

**Advanced functionality**

SelectField and its descendants are iterable, and iterating it will produce
a list of fields each representing an option. The rendering of this can be
further controlled by specifying `option_widget=`.

Use ``invalid_value_message=`` to customize errors raised when submitted
data cannot be coerced, and ``invalid_choice_message=`` to customize errors
raised when the value is not present in ``choices``.

HiddenField is useful for providing data from a model or the application to
be used on the form handler side for making choices or finding records.
Very frequently, CRUD forms will use the hidden field for an object's id.

Hidden fields are like any other field in that they can take validators and
values and be accessed on the form object.   You should consider validating
your hidden fields just as you'd validate an input field, to prevent from
malicious people playing with your data.

.. code-block: jinja

    {{ form.textarea(rows=7, cols=90) }}

FormFields are useful for editing child objects or enclosing multiple
related forms on a page which are submitted and validated together.  While
subclassing forms captures most desired behaviours, sometimes for
reusability or purpose of combining with `FieldList`, FormField makes
sense.

For example, take the example of a contact form which uses a similar set of
three fields to represent telephone numbers::

    class TelephoneForm(Form):
        country_code = IntegerField('Country Code', [validators.required()])
        area_code    = IntegerField('Area Code/Exchange', [validators.required()])
        number       = StringField('Number')

    class ContactForm(Form):
        first_name   = StringField()
        last_name    = StringField()
        mobile_phone = FormField(TelephoneForm)
        office_phone = FormField(TelephoneForm)

In the example, we reused the TelephoneForm to encapsulate the common
telephone entry instead of writing a custom field to handle the 3
sub-fields. The `data` property of the mobile_phone field will return the
:attr:`~wtforms.form.Form.data` dict of the enclosed form. Similarly, the
`errors` property encapsulate the forms' errors.

**Note**: Due to a limitation in how HTML sends values, FieldList cannot enclose
:class:`BooleanField`, :class:`ButtonField`, or :class:`SubmitField`
instances.

.. automethod:: append_entry([data])
.. automethod:: insert_entry(index[, data])
.. automethod:: pop_entry

``append_entry`` and ``insert_entry`` accept Python object data for the new
entry, not submitted formdata. For simple enclosed fields this is usually a
scalar value. For ``FieldList(FormField(...))``, this may be a dict or an
object that the enclosed form can process, similar to passing ``data`` or
``obj`` when constructing that form.

Entries are kept with consecutive indices: ``insert_entry``,
``pop_entry`` and rebuilds from formdata renumber entries so that each
entry's ``index``, ``name`` and ``id`` reflect its position in
:attr:`entries`.

.. attribute:: entries

    Each entry in a FieldList is actually an instance of the field you
    passed in. Iterating, checking the length of, and indexing the
    FieldList works as expected, and proxies to the enclosed entries list.

    **Do not** resize the entries list directly, this will result in
    undefined behavior. See `append_entry`, `insert_entry`, and `pop_entry`
    for ways you can manipulate the list.

.. automethod:: __iter__
.. automethod:: __len__
.. automethod:: __getitem__


:class:`FieldList` is not limited to enclosing simple fields; and can
indeed represent a list of enclosed forms by combining FieldList with
FormField::

    class IMForm(Form):
        protocol = SelectField(choices=[Choice('aim', 'AIM'), Choice('msn', 'MSN')])
        username = StringField()

    class ContactForm(Form):
        first_name  = StringField()
        last_name   = StringField()
        im_accounts = FieldList(FormField(IMForm))

A :mdn-tag:`datalist` of suggestions. Unlike
:class:`~wtforms.fields.SelectField`, the
input stays a free-form text input: the browser displays the
suggestions but the user may type any value. Combine with
:class:`~wtforms.validators.AnyOf` if you need a closed set.

``choices`` is either a list of :class:`~wtforms.fields.Choice`
(or plain strings, in which case the string is used as both value
and label), or a callable invoked at render time. The callable
may take no argument (``fn()``) for a static list, or ``(field)``
to adapt the suggestions to the current field value at each
render — convenient for server-side filtering::

    DataList(lambda field: search(field.data))

**Inline DataList owned by a field**

Pass a :class:`DataList` instance directly as ``datalist=`` to get
a field-owned datalist with a unique id derived from the field's
id::

    class F(Form):
        country = StringField(datalist=DataList(["FR", "US"]))

    {{ form.country() }}
    {{ form.country.datalist() }}

``{{ form.country() }}`` emits the ``<input list="...">`` and
``{{ form.country.datalist() }}`` emits the matching
:mdn-tag:`datalist` element. Both calls are explicit, like
:attr:`Field.errors` or :attr:`Field.label` — you decide where each
piece appears in the DOM.

Inside a :class:`~wtforms.fields.FieldList`, each entry binds its
own clone of the inline :class:`DataList`, so a callable
``choices`` sees each entry's own value::

    class F(Form):
        items = FieldList(
            StringField(
                datalist=DataList(lambda field: suggest(field.data))
            ),
            min_entries=3,
        )

    {% for entry in form.items %}
        {{ entry() }}
        {{ entry.datalist() }}
    {% endfor %}

**String references**

A field may also reference an existing datalist id directly by
string::

    class F(Form):
        field = StringField(datalist="external")

The ``list="external"`` attribute is emitted as-is — the user is
expected to render the :mdn-tag:`datalist` element themselves (in
a shared layout, a static template, or another form on the same
page). ``field.datalist()`` returns empty markup in this case, so
calling it unconditionally in templates is safe.

**Compatible fields**

Any field accepts a ``datalist=`` parameter, but only text-based
HTML inputs (``text``, ``search``, ``email``, ``tel``, ``url``,
``number``, ``range``, ``color``, date/time inputs) honor the
``list=`` attribute. Passing ``datalist=`` to a
:class:`~wtforms.fields.SelectField` or
:class:`~wtforms.fields.TextAreaField` is silently ignored by the
browser.

class TagListField(Field):
    widget = TextInput()

    def _value(self):
        if self.data:
            return ', '.join(self.data)
        else:
            return ''

    def process_formdata(self, valuelist):
        if valuelist:
            self.data = [x.strip() for x in valuelist[0].split(',')]
        else:
            self.data = []

Custom fields can also override the default field constructor if needed to
provide additional customization::

    class BetterTagListField(TagListField):
        def __init__(self, label=None, validators=None, remove_duplicates=True, **kwargs):
            super(BetterTagListField, self).__init__(label, validators, **kwargs)
            self.remove_duplicates = remove_duplicates

        def process_formdata(self, valuelist):
            super(BetterTagListField, self).process_formdata(valuelist)
            if self.remove_duplicates:
                self.data = list(self._remove_duplicates(self.data))

        @classmethod
        def _remove_duplicates(cls, seq):
            """Remove duplicates in a case insensitive, but case preserving manner"""
            d = {}
            for item in seq:
                if item.lower() not in d:
                    d[item.lower()] = True
                    yield item

When you override a Field's constructor, to maintain consistent behavior, you
should design your constructor so that:

 * You take `label='', validators=None` as the first two positional arguments
 * Add any additional arguments your field takes as keyword arguments after the
   label and validators
 * Take `**kwargs` to catch any additional keyword arguments.
 * Call the Field constructor first, passing the first two positional
   arguments, and all the remaining keyword args.


Considerations for overriding process()

Usage:

.. code-block:: pycon

    >>> flags = Flags()
    >>> flags.required = True
    >>> 'required' in flags
    True
    >>> flags.nonexistent
    >>> 'nonexistent' in flags
    False

On all fields, the `label` property is an instance of this class.
Labels can be printed to yield a :mdn-tag:`label`
HTML tag enclosure. Similar to fields, you can also call the label with
additional html params.

.. attribute:: field_id

    The ID of the field which this label will reference.

.. attribute:: text

    The original label text passed to the field's constructor.