API docs for fields.Field.allow_none
and fields.Field.load_default
are slightly confusing / wrong
#2040
Labels
fields.Field.allow_none
and fields.Field.load_default
are slightly confusing / wrong
#2040
I find the API docs for
allow_none
andload_default
in thefields.Field
class slightly confusing / incomplete.The docs state for
allow_none
that it defaults toTrue
if it's unset andload_default
isNone
marshmallow/src/marshmallow/fields.py
Lines 99 to 101 in 1ddf058
This kind of contradicts the docs (and as I later found type hints) of
load_default
. It mentions no default value but states it may be a value or callable - nothing about it beingNone
. I then (wrongly) assumed it defaults toNone
and that if neither of the parameters are providedallow_none
will default toTrue
.marshmallow/src/marshmallow/fields.py
Lines 83 to 84 in 1ddf058
Turns out that assumption was wrong. I got an error message "Field may not be null." and had to read the code to understand that
load_default
defaults toutil.Missing()
. On explicitly settingallow_none = True
when creatingField()
everything worked as expected.My suggestion is to explicitly mention in the docs for
allow_none
that it will default toFalse
(or None?) when neither parameter is set and mention the default value ofload_default
in its docs. Alternatively / additionally you might want to either change the type hint onload_default
to includeNone
, or changemarshmallow/src/marshmallow/fields.py
Line 210 in 1ddf058
to include the
load_default == missing_
case. But that probably changes the behaviour of the class in a breaking way, so I'm not sure if you want to opt for that.The text was updated successfully, but these errors were encountered: