Install & Compatibility
Where this runs
tested against v0.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.125s · 21MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.8s · import 0.117s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Email
✓ from wtforms_components import Email
✗ from wtforms_components.validators import Email
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.
DateField
✓ from wtforms_components import DateField
✗ from wtforms_components.fields import DateField
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.
Unique
✓ from wtforms_components import Unique
✗ from wtforms_components.validators import Unique
Common fields/validators are directly exposed under the top-level 'wtforms_components' namespace.
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}")
Debug
Known issues
gotchaThe 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`.fixAlways use `import wtforms_components` or `from wtforms_components import ...` in your Python code, even though you install `pip install wtforms-components`.
affects: All versions
gotchaWhile 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`.fixConsult 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.
affects: 0.10.0 to 0.11.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'wtforms-components'
The user attempted to import the package using its PyPI name (`wtforms-components`) instead of its Python module name (`wtforms_components`).
fixChange 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')
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`.
fixImport 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)
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.
fixWhen using `Unique`, ensure you pass the SQLAlchemy/ORM model and the field to check uniqueness for. Example: `email = Email(validators=[Unique(User, User.email)])`.
Upgrade
Version history
0.11.0latest on PyPI · released Nov 15, 2024
Audit
Dependencies
WTFormsrequiredProvides the base form and field classes that this library extends.