Marshmallow: Misleading docs around 'attribute'

[manoadamro]

this section

By default, Schemas will marshal the object attributes that are identical to the schema’s field names.
However, you may want to have different field and attribute names. 
In this case, you can explicitly specify which attribute names to use.

suggests that this:

    low_monitoring = fields.List(
        fields.String(), attribute="low-monitoring", required=True
    )

should be able to validate this:

        "low-monitoring": [
          "some",
          "strings"
        ],

however it was raising the following error:

'low_monitoring': ['Missing data for required field.']}

after some searching, it turned out I actually needed this:

    low_monitoring = fields.List(
        fields.String(), load_from="low-monitoring", required=True
    )

The docs should probably explain this a little more clearly to avoid time being wasted.

[lafrech]

There are thee names involved, here.

• object attribute (object / deserialized space)
• field name
• data key (serialized space)

By default, the three are the same.

attribute is used to specify a different name in object space (deserialized space), an object attribute.

Indeed, to specified a different name is serialized space, one needs to use data_key (or `load_from / dump_to if using marshmallow 2).

[manoadamro]

my point is, this is extremely unclear in the docs. If you are reading through the quickstart page, it leads you to believe that attribute is what you need to use.
based on:

By default, Schemas will marshal the object attributes that are identical to the schema’s field names.
However, you may want to have different field and attribute names. 
In this case, you can explicitly specify which attribute names to use.

I'm not suggesting there is a bug, I'm suggesting the docs are bad.

[sloria]

Below that section, though, you see how to specify (de)serialization keys, i.e. load_from and dump_to.

By default Schemas will unmarshal an input dictionary to an output dictionary whose keys are identical to the field names. However, if you are consuming data that does not exactly match your schema, you can specify additional keys to load values by passing the load_from argument.

I'm not sure how to further clarify this. Any suggestions, @manoadamro ?