Add type annotations

[benbariteau]

It would be nice to be able to use typecheckers like mypy with wtforms.

[miketheman]

Is this change desired? Would love to see a comment from a maintainer if they'd entertain accepting a PR adding type hints before putting time in on trying to make it happen.

[davidism]

I am entirely neutral on adding them, but I probably wouldn't accept a PR from someone else. From my experience adding typing to Flask, etc., I have particular standards I want to meet for the initial annotations, there's a lot of complexity in the implementation of WTForms bound fields, and it's very hard to review a PR that changes the majority of lines. It's also unclear how useful the annoations would be, the field signature would get types, but the form attributes themselves might not be able to expose type information on the .data attribute due to their implementation.

[Daverball]

There's now a third-party stubs package: https://pypi.org/project/types-WTForms/

There are some caveats, since the API has some rough edges which makes it hard to properly represent in the current type system, feel free to look through some of my comments in the original PR: python/typeshed#10557

The main issue is that Field.__new__ usually returns UnboundField, but mypy currently only allows returning a subclass and if you violate that rule it will ignore the return type and assume it's Field anyways. There is an open PR in mypy to change that behavior, but it's still not entirely clear how type checkers will behave with both __new__ and __init__ present (especially in regards to subclassing, where it may forego utilizing the __new__ on the base class if the subclass defines its own __init__), so right now for convenience's sake the API just accepts Field for some arguments that should only accept UnboundField (specifically FieldList is affected)

[jace]

I don't have types-WTForms installed, but Pylance appears to be using it anyway and is redlining my code. In particular:

1. LazyString from Flask-Babel is not compatible with str. The workaround is to re-cast the type on import:

   from typing import Callable
   from flask_babel import lazy_gettext
   __: Callable[..., str] = lazy_gettext

2. I have a custom field that types validators as list[Callable[[Form, Field], None]] with Form and Field imported from WTForms. This is now erroring on the URL() validator:

   Argument of type "list[URL]" cannot be assigned to parameter "validators" of type "ValidatorList" in function "__init__"
     Type "URL" cannot be assigned to type "ValidatorCallable"
       Parameter 2: type "Field" cannot be assigned to type "StringField"
         "Field" is incompatible with "StringField"
   

   That last line is suggesting the type stub's StringField has a different base from WTForms's Field.

Since the type stubs are not in the main lib, my custom fields and validators cannot use them. It's unclear why Pylance is auto-using these stubs when Mypy (which runs in CI) is not. There's probably other weirdness. Should I be reporting here or on python/typeshed#10557 or as new issues somewhere, @Daverball?

[Daverball]

@jace I'm not really familiar with how pylance does things, IIRC they also have some of their own stubs that are separate from typeshed, although there is an ongoing effort to merge them with typeshed, but I expect there to be some way to tell pylance to not use a types-* package, even when it is available.

As far as reporting problems with types-WTForms goes, you can open a new issue on typeshed and open a PR if you can think of a way to fix the problem.

That being said for your second problem it's not surprising that your annotation for validators is erroring, the problem is, list is invariant. On top of that some validators require a specific kind of Field, so it requires some workarounds to get moderate type safety without a ton of false positives. You can have a look at how I typed the arguments on __init__ to achieve a good balance between type safety and ergonomics in:
https://github.com/python/typeshed/blob/d3bf2805b46b61ea9c08d07efbfac5a4f0b9ae73/stubs/WTForms/wtforms/fields/core.pyi#L51-L71

You can either redefine the TypeAlias I'm using yourself or import them inside a if TYPE_CHECKING block.

The reason why it was working before, is that both Form and Field were essentially just an alias for Any, so it accepted any list containing callables which accept two arguments.

For the first issue it is indeed the problem that LazyString is not itself a subclass of str. There's another similar package called translationstring where TranslationString is itself a subclass of str and can be used anywhere that accepts a str, I've found it to be a much nicer implementation. I realize that for WTForms you can provide your own custom translation machinery, so it could in theory accept arbitrary objects for label and a lot of other string arguments, but I don't think it's very helpful to just accept object in those cases.

If you want a slightly more robust workaround, you could use NewType to define LazyString as a subclass of str, that way you will still get an error if you try to reassign a regular string to a variable, which is supposed to be holding a LazyString.