marshmallow扩展Schemas

• Pre-processing and Post-processing Methods

可以使用pre_load，post_load，pre_dump，post_dump装饰器，来对（反）序列化数据进行预处理和后处理操作

from marshmallow import Schema, fields, pre_load

class UserSchema(Schema):
    name = fields.String()
    slug = fields.String()

    @pre_load
    def slugify_name(self, in_data, **kwargs):
        print(1111)
        in_data["slug"] = in_data["slug"].lower().strip().replace(" ", "-")
        return in_data

    @post_load
    def make_user(self, in_data, **kwargs):
        print(2222)
        return in_data

schema = UserSchema()
result = schema.load({"name": "Steve", "slug": "Steve Loria"})
pprint(result)

11111
22222
{'name': 'Steve', 'slug': 'steve-loria'}

• Passing “many”

默认情况下，预处理和后处理方法同时只能接受一个对象/数据，如果要处理一个集合的数据，只需给装饰器方法传入pass_many=True即可

from marshmallow import Schema, fields, pre_load, post_load, post_dump

class BaseSchema(Schema):
    __envelope__ = {"single": None, "many": None}
    __model__ = User

    def get_envelope_key(self, many):
        key = self.__envelope__["many"] if many else self.__envelope__["single"]
        assert key is not None, "Envelope key undefined"
        return key

    @pre_load(pass_many=True)
    def unwrap_envelope(self, data, many, **kwargs):
        key = self.get_envelope_key(many)
        return data[key]

    @post_dump(pass_many=True)
    def wrap_with_envelope(self, data, many, **kwargs):
        key = self.get_envelope_key(many)
        return {key: data}

    @post_load
    def make_object(self, data, **kwargs):
        return self.__model__(**data)

class UserSchema(BaseSchema):
    __envelope__ = {"single": "user", "many": "users"}
    __model__ = User
    name = fields.Str()
    email = fields.Email()

user_schema = UserSchema()
user = User("Mike", "mike@stones.com")
pprint(user_schema.dump(user))

{'user': {'email': 'mike@stones.com', 'name': 'Mike'}}

users = [
    User("Keith", "keith@stones.com"),
    User("Charlie", "charlie@stones.com"),
]
users_data = user_schema.dump(users, many=True)
pprint(users_data)

{'users': [{'email': 'keith@stones.com', 'name': 'Keith'},
           {'email': 'charlie@stones.com', 'name': 'Charlie'}]}

pprint(user_schema.load(users_data, many=True))

[<User(name='Keith')>, <User(name='Charlie')>]

• Raising Errors in Pre-/Post-processor Methods

预处理和后处理方法可能会触发ValidationError，默认情况下，错误会被保存在以“_schema”为键的字典中

from marshmallow import Schema, fields, ValidationError, pre_load

class BandSchema(Schema):
    name = fields.Str()

    @pre_load
    def unwrap_envelope(self, data, **kwargs):
        if "data" not in data:
            raise ValidationError("Input data must have a 'data' key.")
        return data["data"]

sch = BandSchema()
try:
    sch.load({"name": "The Band"})
except ValidationError as err:
    print(err.messages)

{'_schema': ["Input data must have a 'data' key."]}

如果不想用“_schema”作为错误字典的键，只需往ValidationError传入第二个参数（自定义键）即可

from marshmallow import Schema, fields, ValidationError, pre_load

class BandSchema(Schema):
    name = fields.Str()

    @pre_load
    def unwrap_envelope(self, data, **kwargs):
        if "data" not in data:
            raise ValidationError("Input data must have a 'data' key.", "_preprocessing")
        return data["data"]

sch = BandSchema()
    try:
        sch.load({"name": "The Band"})
    except ValidationError as err:
        print(err.messages)

{'_preprocessing': ["Input data must have a 'data' key."]}

• Pre-/Post-processor Invocation Order

反序列化处理调用顺序如下：

1. @pre_load(pass_many=True) methods
2. @pre_load(pass_many=False) methods
3. load(in_data, many) (validation and deserialization)
4. @post_load(pass_many=True) methods
5. @post_load(pass_many=False) methods

序列化类似，只是带pass_many=True的处理方法会在带pass_many=False的处理方法之后被调用

1. @pre_dump(pass_many=False) methods
2. @pre_dump(pass_many=True) methods
3. dump(obj, many) (serialization)
4. @post_dump(pass_many=False) methods
5. @post_dump(pass_many=True) methods

Warning：

你可能会在同一个schema上注册多个处理方法，如果出现多个同类型的处理装饰器，则schema无法保证调用顺序。

如果你需要保证调用顺序，你应该将它们放到同一个方法里。

from marshmallow import Schema, fields, pre_load

# YES
class MySchema(Schema):
    field_a = fields.Field()

    @pre_load
    def preprocess(self, data, **kwargs):
        step1_data = self.step1(data)
        step2_data = self.step2(step1_data)
        return step2_data

    def step1(self, data):
        do_step1(data)

    # Depends on step1
    def step2(self, data):
        do_step2(data)


# NO
class MySchema(Schema):
    field_a = fields.Field()

    @pre_load
    def step1(self, data, **kwargs):
        do_step1(data)

    # Depends on step1
    @pre_load
    def step2(self, data, **kwargs):
        do_step2(data)

• Schema-level Validation

可以使用marshmallow.validates_schema装饰器来注册schema级别的验证方法

from marshmallow import Schema, fields, validates_schema, ValidationError

class NumberSchema(Schema):
    field_a = fields.Integer()
    field_b = fields.Integer()

    @validates_schema
    def validate_numbers(self, data, **kwargs):
        if data["field_b"] >= data["field_a"]:
            raise ValidationError("field_a must be greater than field_b")

schema = NumberSchema()
try:
    schema.load({"field_a": 1, "field_b": 2})
except ValidationError as err:
    print(err.messages)

{'_schema': ['field_a must be greater than field_b']}

• Storing Errors on Specific Fields

当多个schema级别的验证器返回错误信息时，这些错误信息将在验证结束后被合并到一起返回

from marshmallow import Schema, fields, validates_schema, ValidationError

class NumberSchema(Schema):
    field_a = fields.Integer()
    field_b = fields.Integer()
    field_c = fields.Integer()
    field_d = fields.Integer()

    @validates_schema
    def validate_lower_bound(self, data, **kwargs):
        errors = {}
        if data["field_b"] <= data["field_a"]:
            errors["field_b"] = ["field_b must be greater than field_a"]
        if data["field_c"] <= data["field_a"]:
            errors["field_c"] = ["field_c must be greater than field_a"]
        if errors:
            raise ValidationError(errors)

    @validates_schema
    def validate_upper_bound(self, data, **kwargs):
        errors = {}
        if data["field_b"] >= data["field_d"]:
            errors["field_b"] = ["field_b must be lower than field_d"]
        if data["field_c"] >= data["field_d"]:
            errors["field_c"] = ["field_c must be lower than field_d"]
        if errors:
            raise ValidationError(errors)

schema = NumberSchema()
try:
    schema.load({
        "field_a": 3,
        "field_b": 2,
        "field_c": 1,
        "field_d": 0
    })
except ValidationError as err:
    pprint(err.messages)

{'field_b': ['field_b must be greater than field_a',
             'field_b must be lower than field_d'],
 'field_c': ['field_c must be greater than field_a',
             'field_c must be lower than field_d']}

• Using Original Input Data

如果想使用原始的未处理的输入数据，只需要在post_load装饰器上传入pass_original=True即可

from marshmallow import Schema, fields, post_load, ValidationError

class MySchema(Schema):
    foo = fields.Integer()
    bar = fields.Integer()

    class Meta:
        unknown = EXCLUDE

    @post_load(pass_original=True)
    def add_baz_to_bar(self, data, original_data, **kwargs):
        baz = original_data.get("baz")
        if baz:
            data["bar"] = data["bar"] + baz
        return data

schema = MySchema()
pprint(schema.load({"foo": 1, "bar": 2, "baz": 3}))

{'bar': 5, 'foo': 1}

• Custom Error Handling

自定义错误处理，可以通过重写handle_error方法来自定义一个错误处理方法，这个方法接受ValidationError和原始的反序列化的输入数据

import logging
from marshmallow import Schema, fields

class AppError(Exception):
    pass

class UserSchema(Schema):
    email = fields.Email()

    def handle_error(self, error, data, **kwargs):
        logging.error(error.messages)
        raise AppError("An error occurred with input: {0}".format(data))

schema = UserSchema()
schema.load({"email": "invalid-email"})

AppError: An error occurred with input: {'email': 'invalid-email'}

• Custom “class Meta” Options

class Meta 设置是一种配置和修改schema行为的方式，查看API

可以通过子类SchemaOpts来自定义class Meta配置

• Example：Enveloping，Revisited

同样为上面的的例子添加一个序列化输出的封装。这次，使用封装的键来自定义class Meta的配置。

# Example outputs
{
    'user': {
        'name': 'Keith',
        'email': 'keith@stones.com'
    }
}
# List output
{
    'users': [{'name': 'Keith'}, {'name': 'Mick'}]
}

首先，添加命名空间配置到一个自定义的设置类

from marshmallow import Schema, SchemaOpts

class NamespaceOpts(SchemaOpts):
    """Same as the default class Meta options, but adds "name" and
    "plural_name" options for enveloping.
    """

    def __init__(self, meta, **kwargs):
        SchemaOpts.__init__(self, meta, **kwargs)
        self.name = getattr(meta, "name", None)
        self.plural_name = getattr(meta, "plural_name", self.name)

 然后用这个设置类创建一个自定义的schema

class NamespacedSchema(Schema):
    OPTIONS_CLASS = NamespaceOpts

    @pre_load(pass_many=True)
    def unwrap_envelope(self, data, many, **kwargs):
        key = self.opts.plural_name if many else self.opts.name
        return data[key]

    @post_dump(pass_many=True)
    def wrap_with_envelope(self, data, many, **kwargs):
        key = self.opts.plural_name if many else self.opts.name
        return {key: data}

现在应用schemas就可以继承这个自定义的schema类了

class UserSchema(NamespacedSchema):
    name = fields.String()
    email = fields.Email()

    class Meta:
        name = "user"
        plural_name = "users"


ser = UserSchema()
user = User("Keith", email="keith@stones.com")
result = ser.dump(user)
result  # {"user": {"name": "Keith", "email": "keith@stones.com"}}