Rethink the missing/default field attributes

Those attributes come from marshmallow, which is all about serialize/deserialize a document:

• missing is used when the field is not present in the dict to deserialize
• default is used when the field is not present in the document to serialize

However in umongo the focus shifts toward the document itself, so those terms seems a bit clunky

• the missing object is already used inside umongo’s DataProxy to represent field not present in MongoDB. Hence the missing attribute should mean what value to return if the value is missing
• the default attribute sounds like the value to set by default to the field when creating a new document

In a nutshell the meaning of missing and default are reversed between mashmallow and umongo…

What I’m thinking to do:

• Remove the missing attribute (in fact just hide it from abstract.BaseField constructor and documentation)
• Only use the default attribute for both missing and default (in marshmallow’s logic)
• Add methods to get from the umongo document an equivalent pure mashmallow Schema (see #34 )

The idea is to hide mashmallow logic to expose a more consistent API from the umongo user’s point of view. Then provide a way to get back a pure Marshmallow Schema when needed to do all the custom.

example:

@instance.register
class Person(Document):
    name = fields.StrField(default='John Doe')

p = Person()
# Default is set
assert p.name == 'John Doe'
# Default value will be written in database
assert p._data.get('name') == 'John Doe'
# If we want more cunning behavior (e.g. only save in database non-default value)
# we should use a `MethodField` to define custom method for serialization/deseriazation

del p.name
assert p._data.get('name') == missing
# If not present on database, we switch back to default value as well
assert p.name == 'John Doe'

# Now it's customization time !
PersonSchema = p.get_marshmallow_schema()
class MyCustomSchema(PersonSchema):
    ...

# It could be also useful to provide method to get a specific field
class MyCustomSchema2(marshmallow.Schema)
    name = p.get_marshmallow_field('name')

@lafrech What do you think ?

[lafrech]

I’ve been following the discussions about Marshmallow 3 and from what I gathered, the choices made are likely to make our lives easier.

Among the breaking changes, strict would be True by default or even removed and we’d need to catch ValidationError, and load would return the deserialized data rather than the (data, errors) tuple. This will break stuff, but ultimately, the code should be easier to read.

[touilleMan]

I think we should keep thing explicit to avoid misleading use of missing/default. For example we only use default un umongo, raise a runtime error if missing is used (to explain how umongo and marshmallow have their behavior changing on this point) and use a marshmallow_missing/marshmallow_default fields to pass a custom attribute value when using as_marshmallow_field. Of course if marshamallow_* is not provided, we fall back on default value (serializing it on the fly before marshmallow use it)

I’ve created a PR which implement this behavior #107, can you have a look and play a bit with it (the subject is pretty complicated, better have two pair of eyes on it !)