Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Documenting callable default #196
When a default/missing value is a callable, it is called when generating the documentation.
if default is not marshmallow.missing: if callable(default): ret['default'] = default() else: ret['default'] = default
This can be wrong if the value of the callable depends on the moment it is called. Typically, if it is
Not sure how to do that. Maybe a
There is no way to document a dynamic default: OAI/OpenAPI-Specification#554.
What we should do is allow the user to opt-out of default documenting. Then he can either specify the default behaviour in the description or add a
So we need an attribute meaning "don't document default".
From the discussion in OAI/OpenAPI-Specification#554, datetime is the only common use case. Not documenting callable defaults is not really an option, as we'll miss
On second thought, since a callable could be anything, it could be smarter to not document them. There is no reason the value returned by the callable at documentation time makes sense in this context.
An exception to this would be basic types that are provided as callables to avoid the "same list instance in every field instance" issue. Those are common enough to justify an exception to the rule.
if default is not marshmallow.missing: if callable(default): if default in (dict, list, set,...): # How to get an exhaustive list? ret['default'] = default() else: # Don't assume anything and let the user add a note in the description pass else: ret['default'] = default
We could add a
EMPTY_COLLECTION_CALLABLES = (dict, list, set,...) # How to get an exhaustive list? if default_doc: if callable(default_doc): ret['default'] = default_doc() else: ret['default'] = default_doc elif default is not marshmallow.missing: if callable(default) and default in EMPTY_COLLECTION_CALLABLES: ret['default'] = default() else: ret['default'] = default
I'd like to tackle this.
Using the callable's return value to fill the doc default is wrong, so removing this would be a bugfix. Besides, it is not tested, so no test broken. Edit: My bad, it is tested in
I wanted to make an exception for
However, it would be nice to have another meta attribue to allow passing a default manually. This one could also be used when