formular.forms - Forms

This module contains the built-in forms as well as the form base class.

class HTMLForm(session=None, action=u'', remote_addr=None, **kwargs)

Represents the logic for an HTML form.

Parameters:

• session – An object with a dict-like interface in which session related data can be stored.
• action – The path under which the form can be reached.
• remote_addr –

  The REMOTE_ADDR from the wsgi environment. This is required for the reCAPTCHA support.

  New in version 0.2.

as_widget()

Returns the HTMLForm as a formular.widgets.FormWidget.

csrf_protection_enabled

If True this form will be protected against cross-site request forgery, as long as it is protectable.

csrf_token

The csrf token for this form. If necessary this property should set the token on the session.

is_csrf_protectable

True if session is not None and action is specified.

is_csrf_protected

True if the field is protected against csrf.

recaptcha_private_key

The private reCAPTCHA api key.

New in version 0.2.

recaptcha_public_key

The public reCAPTCHA api key.

New in version 0.2.

validate(form_data, without_csrf_protection=False)

Validates the given form_data.

Parameter:without_csrf_protection – Pass True if you want to turn of the csrf protection for a validation e.g. if you want to validate form data you got via an JSON/XML API of your application.

Changed in version 0.2: form_data values are now converted to unicode if necessary.

class ConfigurationForm(*args, **kwargs)

drop_main_fields

If main_section is set to True every field which is not a mapping is dropped.

main_section

If your configuration format requires sections(like ini), you can specify a main section, instead of using a formular.fields.Mapping instance for every section. This does only affect assignment of fields on the class, not on the instance.

class Form(initial_data=missing, locale='en')

The base class for forms. Fields can be assigned declarativly, on a created class or on an instance:

class LoginForm(Form):
    username = TextField(label=u"Username", required=True)
    password = PasswordField(label=u"Password", required=True)
    repeat_password = password.copy(label=u"Repeat password",
                                    equals="password")
    permanent = BooleanField(label=u"Keep me logged in")

Fields can be accessed as an attribute or dict-like using LoginForm()["username"].

Sometimes you may want to validate a field in a way which only makes sense in the context of the form type you are defining. In order to do that you define a method with the name validate_FIELD_NAME. Such a method gets the value of the field FIELD_NAME as an argument.

If you want to validate the form itself you can define a validate_context method which get’s called upon validation.

Parameters:

• initial_data – If you want to use different default values for the fields you can pass a dictionary, using this parameter.
• locale –

  For localization provide a locale string, currently supported are:

  • en
  • de

New in version 0.2: validate_* methods.

classmethod as_mapping()

Returns the form as a formular.fields.Mapping.

data

The validated or default data.

errors

A formular.exceptions.MultipleValidationErrors instance with the errors which occured during validation or a formular.exceptions.ValidationError if an error occurred at form level.

fields

The fields of this form.

Note

Adding fields directly to this dictionary won’t bind them. Use Form().new_field = Field() instead.

initial_data

The initial form data.

is_valid

True if the data is valid.

reset()

Resets the form to the initial data.

validate(form_data)

Validates the form against the given form_data.