WTForms Components

0.11.0 · active · verified Fri Apr 17

WTForms-Components is a library that extends WTForms with additional fields, validators, and widgets, aiming to simplify common form-related tasks. It is currently at version 0.11.0 and is maintained with occasional releases driven by community contributions and WTForms compatibility.

Common errors

```
ModuleNotFoundError: No module named 'wtforms-components'
```
cause The user attempted to import the package using its PyPI name (`wtforms-components`) instead of its Python module name (`wtforms_components`).

fix Change your import statement from `import wtforms-components` to `import wtforms_components` (or `from wtforms_components import ...`).
```
ImportError: cannot import name 'Unique' from 'wtforms_components.validators' (or similar for 'Email', 'DateField')
```
cause Many commonly used fields and validators from `wtforms-components` are directly exposed under the top-level `wtforms_components` namespace, not nested within submodules like `wtforms_components.validators` or `wtforms_components.fields`.

fix Import the symbol directly from the top-level package, e.g., `from wtforms_components import Unique`.
```
TypeError: __init__() missing 1 required positional argument: 'model' (or 'query' for Unique validator)
```
cause The `Unique` validator (and similar database-interacting validators) requires specific arguments like a database model and field to check uniqueness against, which were not provided or were provided incorrectly.

fix When using `Unique`, ensure you pass the SQLAlchemy/ORM model and the field to check uniqueness for. Example: `email = Email(validators=[Unique(User, User.email)])`.

Warnings

gotcha The PyPI package name is `wtforms-components` (with a hyphen), but the Python package name for importing is `wtforms_components` (with an underscore). Importing `wtforms-components` will result in a `ModuleNotFoundError`.
Fix: Always use `import wtforms_components` or `from wtforms_components import ...` in your Python code, even though you install `pip install wtforms-components`.
gotcha While the library declares `WTForms>=2.0`, specific functionalities might be primarily tested against older WTForms 2.x versions. Users on WTForms 3.x or 4.x should thoroughly test custom fields, widgets, and complex validators for full compatibility, especially if encountering unexpected `TypeError` or `AttributeError`.
Fix: Consult WTForms-Components GitHub issues for known compatibility problems with newer WTForms versions. If issues arise, consider pinning an older WTForms version (e.g., `WTForms<3.0`) or contributing compatibility fixes.

Install

pip install wtforms-components Install stable version

Imports

Email
wrong:
```
from wtforms_components.validators import Email
```
correct:
```
from wtforms_components import Email
```
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.
DateField
wrong:
```
from wtforms_components.fields import DateField
```
correct:
```
from wtforms_components import DateField
```
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.
Unique
wrong:
```
from wtforms_components.validators import Unique
```
correct:
```
from wtforms_components import Unique
```
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.

Quickstart

This quickstart demonstrates defining a simple form using WTForms-Components' custom Email and DateField types with basic validation. It shows how to instantiate the form with data and validate it.

from wtforms import Form
from wtforms_components import Email, DateField
from wtforms.validators import DataRequired

class UserProfileForm(Form):
    email = Email(validators=[DataRequired()])
    birth_date = DateField(validators=[DataRequired()])

# Example usage (run with a dictionary or request.form)
form_data = {
    'email': 'user@example.com',
    'birth_date': '1990-05-15'
}

form = UserProfileForm(data=form_data)

if form.validate():
    print("Form is valid!")
    print(f"Email: {form.email.data}")
    print(f"Birth Date: {form.birth_date.data}")
else:
    print("Form errors:")
    for field, errors in form.errors.items():
        for error in errors:
            print(f"  {field}: {error}")

view raw JSON →