Add field-level pre/post-load API

[sloria]

As suggested by @lafrech in #2786 (review), we can enable pre/post-load on fields to address use cases like whitespace trimming (#1391) via an API similar to the schema-level pre/post_load/dump API.

Something like:

from marshmallow import Schema, fields

class ArtistSchema(Schema):
    name = fields.Str(post_load=(str.strip, str.upper))
    email = fields.Str(post_load=(str.strip, str.upper))

• pro: allows field-specific transformations without having to implement a custom field
• pro: non-breaking change
• con: overlaps with existing functionality provided by custom fields and the schema-level @pre/post_load

Alternatives considered

Allow validators to transform values

• same as pydantic and [sqlalchemy](https://docs.sqlalchemy.org/en/20/orm/mapped_attributes.html#simple-validators and Add field-level pre/post-load API #2787 (comment))
• pro: minimal API surface added
• pro: minimal internal code changes
• con: it's not intuitive that validators can mutate values
• con: doesn't solve for pre-validation transformations or dumping/serialization
• con: breaking change

Decorator API

update: this was considered as part of the original proposal but rejected/tabled (#2787 (comment) and #2787 (comment))

from marshmallow import Schema, fields, field_post_load

class ArtistSchema(Schema):
    name = fields.Str()
    email = fields.Str()

    @field_post_load("name", "email")
    def strip_whitespace(self, field_name: str, value: str) -> str:
        return value.strip()

[llucax]

Why is this considered a breaking change?

[sloria]

sorry for the confusion. The breaking change refers to the 'validators transform values' alternative, not the proposed approach

[sloria]

on second thought, i don't think field-level pre/post-dump makes as much sense as pre/post-load. field-level transformations are much less common on serialization than in deserialization, and custom fields already address the rare cases when they're necessary.

[sloria]

I also have medium confidence that @field_pre/post_load is unnecessary. the schema-level @pre/post_load already provides functionality for doing transformations on one or more fields.

[sloria]

proof of concept of the pre_load and post_load parameters in #2799

[lafrech]

I also have medium confidence that @field_pre/post_load is unnecessary. the schema-level @pre/post_load already provides functionality for doing transformations on one or more fields.

field level pre/post load transformers are more convenient than schema-level ones for some tasks, as shown by your tests in #2799. It allows one-liners such as

age = fields.Float(post_load=[multiply_by_2, decrement])

I see 3 cases:

• The transformation must be performed on a specific field in multiple schemas -> could use field-level but a custom field is nice too
• The transformation must be performed on several fields in the schema -> use schema-level
• The transformation must be performed on a specific field in a single schema -> well, schema-level works too, after all, it is just a bit longer, but if it's only once...

#1391 could be addressed by creating a base schema that trims whitespaces in pre-load.

[sloria]

@lafrech i agree that field-level pre_load and post_load parameters are useful. i was referring specifically to the @field_pre/post_load decorator API from my OP; i think that's less useful.

[lafrech]

Oh, I thought you were talking about the whole feature.

Yes, I agree. The benefit of the decorator would be to present the same multiple-fields interface as validates (#1965). But if one needs to apply a processor to a few fields, they may do it field by field, and if they need it applied to all fields, it may be worth considering using a schema level processor.

Note that if processors can only be passed as parameters, the order is obvious, while if we allow decorators, questions may arise about how to enforce an order (just like with schema-level processors #600).

[sloria]

exactly. i've updated the OP to remove the decorator API from consideration