<commit_before>Fields
======

.. module:: wtforms.fields

Fields are responsible for rendering and data conversion. They delegate to
validators for data validation.

Field definitions
-----------------

Fields are defined as members on a form in a declarative fashion::

    class MyForm(Form):
        name    = TextField(u'<NAME>', [validators.required(), validators.length(max=10)])
        address = TextAreaField(u'Mailing Address', [validators.optional(), validators.length(max=200)])

When a field is defined on a form, the construction parameters are saved until
the form is instantiated. At form instantiation time, a copy of the field is 
made with all the parameters specified in the definition. Each instance of the
field keeps its own field data and errors list.

The label and validators can be passed to the constructor as sequential
arguments, while all other arguments should be passed as keyword arguments.
Some fields (such as :class:`SelectField`) can also take additional
field-specific keyword arguments. Consult the built-in fields reference for
information on those.

The Field base class
--------------------

.. class:: Field

    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__

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

    **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):
<commit_msg>Add docs for object_data<commit_after>Fields
======

.. module:: wtforms.fields

Fields are responsible for rendering and data conversion. They delegate to
validators for data validation.

Field definitions
-----------------

Fields are defined as members on a form in a declarative fashion::

    class MyForm(Form):
        name    = TextField(u'<NAME>', [validators.required(), validators.length(max=10)])
        address = TextAreaField(u'Mailing Address', [validators.optional(), validators.length(max=200)])

When a field is defined on a form, the construction parameters are saved until
the form is instantiated. At form instantiation time, a copy of the field is 
made with all the parameters specified in the definition. Each instance of the
field keeps its own field data and errors list.

The label and validators can be passed to the constructor as sequential
arguments, while all other arguments should be passed as keyword arguments.
Some fields (such as :class:`SelectField`) can also take additional
field-specific keyword arguments. Consult the built-in fields reference for
information on those.

The Field base class
--------------------

.. class:: Field

    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__

    **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):

{'fraction_non_alphanumeric': 0.07604264659767952, 'fraction_numerical': 0.0015678896205707118, 'mean_word_length': 3.094351732991014, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6047158', 'n_tokens_mistral': 1561, 'n_tokens_neox': 1503, 'n_words': 781}