WTForms是如何工作的?

WTForms是一个Python语言的请求数据验证库,功能强大、且支持自定义验证器。

1.初体验

首先用一个简单的示例,来体验一下WTForms的效果。

from wtforms import Form, StringField, IntegerField
from wtforms.validators import DataRequired, NumberRange, length


class UserForm(Form):
    name = StringField(label='姓名', validators=[DataRequired(message='can not be empty'), length(min=2, max=6, message='姓名必须2-6个字符')])
    age = IntegerField(label='年龄', validators=[DataRequired(message='can not be empty'), NumberRange(min=0, max=10, message='年龄必须为0-10')])


if __name__ == '__main__':
    data = {'name': 'zhangsan', 'age': 11}
    form = UserForm(data=data)
    print(form.validate())
    print(form.errors)

执行结果如下, errors中包含了所有的错误提示。

False
{'name': ['姓名必须2-6个字符'], 'age': ['年龄必须为0-10']}

2.Form

作为一个有追求的开发者,我们不能满足于仅仅知道怎么用这个库,有必要思考下这究竟是怎样实现的。

首先从UserForm的基类Form着手

class Form(with_metaclass(FormMeta, BaseForm)):

Form又使用了一个函数with_metaclass的返回结果作为基类,函数with_metaclasswtforms.compat.py

def with_metaclass(meta, base=object):
    return meta("NewBase", (base,), {})

所以Form的基类其实就是

FormMeta("NewBase", (BaseForm,), {})

3.BaseForm

BaseForm是一个基础"Form"类,它提供了"Form"的核心行为的代理。

# 其中部分代码太长,用pass替代,如有需要直接查看源码
class BaseForm(object):
    def __init__(self, fields, prefix='', meta=DefaultMeta()):
        pass

    def __iter__(self):
        """Iterate form fields in creation order."""
        return iter(itervalues(self._fields))

    def __contains__(self, name):
        """ Returns `True` if the named field is a member of this form. """
        return (name in self._fields)

    def __getitem__(self, name):
        """ Dict-style access to this form's fields."""
        return self._fields[name]

    def __setitem__(self, name, value):
        """ Bind a field to this form. """
        self._fields[name] = value.bind(form=self, name=name, prefix=self._prefix)

    def __delitem__(self, name):
        """ Remove a field from this form. """
        del self._fields[name]

    def _get_translations(self):
        pass

    def populate_obj(self, obj):
        pass

    def process(self, formdata=None, obj=None, data=None, **kwargs):
        pass

    def validate(self, extra_validators=None):
        pass

    @property
    def data(self):
        return dict((name, f.data) for name, f in iteritems(self._fields))

    @property
    def errors(self):
        if self._errors is None:
            self._errors = dict((name, f.errors) for name, f in iteritems(self._fields) if f.errors)
        return self._errors

4.FormMeta

FormMeta(type)是一个元类,用来动态创建Form及其字段列表(关键),为了便于分析,可以在FormMeta的call函数中断点调试,能够清晰地看到Field的绑定过程。

# 部分代码较长,使用pass替代,如有需要直接查看源码
class FormMeta(type):
    def __init__(cls, name, bases, attrs):
        type.__init__(cls, name, bases, attrs)
        cls._unbound_fields = None
        cls._wtforms_meta = None

    def __call__(cls, *args, **kwargs):
        pass

    def __setattr__(cls, name, value):
        pass

    def __delattr__(cls, name):
        pass

这里使用到了Python中元类的技巧。

5.Python中的元类编程

通过FormMeta这个元类,动态创建了BaseForm的子类Form,并且控制了Form的子类实例化的时候能够按照FormMeta中的逻辑绑定Field。

这里顺便提一下Python中的元类编程,元类编程的关键是type这个类。

查看type的源码,发现type有3种构造函数,其中type(name, bases, dict) -> a new type用来动态创建一个新的类,创建类的时候可以指定新类继承的基类(bases),以及自身的属性和函数(dict)。

接下来我们用一个最简单的例子来说明元类编程。

class A:
    a = 1

    @staticmethod
    def test_a():
        return 'aaa'


class B:
    b = 2


class CMeta(type):
    pass


if __name__ == '__main__':
    C = CMeta("C", (A, B), {'x': 123})
    c = C()
    print(c)
    print(c.a)
    print(c.b)
    print(c.test_a())
    print(c.x)

输出结果如下

<__main__.C object at 0x1023668d0>
1
2
aaa
123

这里动态地创建了类C,并且继承了A、B,当然直接使用type而非type的子类CMeta也是可以的,只不过使用CMeta可以在创建类的时候做更多的控制。

6.Basic Field

上面提到了Form的子类,也就是一开始的例子中我们定义的UserForm,在示例化的时候会按照FormMeta中定义的逻辑绑定Field。

诸如StringField、IntegerField等都是Field的子类,Field中关键的函数_run_validation_chain执行校验链,对所有的validators逐一校验。

    def _run_validation_chain(self, form, validators):
        
        for validator in validators:
            try:
                validator(form, self)
            except StopValidation as e:
                if e.args and e.args[0]:
                    self.errors.append(e.args[0])
                return True
            except ValueError as e:
                self.errors.append(e.args[0])

        return False

7.Custom Field

关于Custom Fields这里不进行阐述,可自行查看官方文档。

8.Built-in validators

这里以DataRequired这个validator为例,其中call魔法函数中定义了具体的校验逻辑,使其成为一个可调用对象,并且2个参数分别为form和field。而Field中_run_validation_chain函数中有一句validator(form, self)正好就是在Field中遍历validator,并执行validator的call中的校验逻辑。

class DataRequired(object):

    field_flags = ('required', )

    def __init__(self, message=None):
        self.message = message

    def __call__(self, form, field):
        if not field.data or isinstance(field.data, string_types) and not field.data.strip():
            if self.message is None:
                message = field.gettext('This field is required.')
            else:
                message = self.message

            field.errors[:] = []
            raise StopValidation(message)

9.Custorm validator

通过源代码的分析可知,只要我们定义的类中有call魔法函数,传入两个参数form、field,并在其中给定具体的校验逻辑,如果校验失败时,raise ValueError或其子类,Field就能捕获异常,并将error追加到该字段的错误列表中。

官方文档中也给出了自定义validator的示例

class Length(object):
    def __init__(self, min=-1, max=-1, message=None):
        self.min = min
        self.max = max
        if not message:
            message = u'Field must be between %i and %i characters long.' % (min, max)
        self.message = message

    def __call__(self, form, field):
        l = field.data and len(field.data) or 0
        if l < self.min or self.max != -1 and l > self.max:
            raise ValidationError(self.message)

当然,除了call的方式,使用闭包函数自定义validator也是可以的,不过还是建议可调用对象的方式。

10.总结

一句话总结WTForms的层级结构:Form中绑定Filed,Field中通过构造函数定义需要的validators。