[7.x] Refactor support for 'unknown' with location map #544
Conversation
This introduces a new Parser-class variable, `DEFAULT_UNKNOWN_BY_LOCATION`, which maps location names to `unknown` values. It populates that and `DEFAULT_UNKNOWN` to pass `EXCLUDE` in the general case and `RAISE` for request bodies. The new behavior is layered and defined with lower precedence than `Parser.unknown` or the `unknown` parameter on parse calls. In order to implement this and allow users to opt *out* of the behavior (i.e. in order to use schema-defined values), the way these values are set is subtly changed. Instead of having a default value of `None`, parse calls and parser __init__ have a default of `unknown="_default"`. When that value is detected, the various layers of defaults (DEFAULT_UNKNOWN and DEFAULT_UNKNOWN_BY_LOCATION) are applied. However, if a user passes `None`, that will take effect with the meaning "do not pass a value for `unknown`". For parsers which define additional locations, they extend the base DEFAULT_UNKNOWN_BY_LOCATION as appropriate. The changelog has been updated significantly in order to handle this and a new section of the advanced usage docs covers the behavior.
|
The only idea I've had for making this simpler which really appeals to me at all is that we could get rid of I also thought about getting rid of I'll leave this open for today, since I don't have time left in the day to handle doing a 7.0.0b1 release and such, as I said I would. But I plan to merge it and do the branch management tomorrow. We can look at removing |
Doing this before releasing a beta would avoid mentioning |
Removing this value removes a layer of defaults and potential ambiguity from the interfaces. Docs and changelog update to remove all references to DEFAULT_UNKNOWN.
|
I removed |
|
Great. Thanks for taking care of all this. I suppose you mean release a beta. Sure, go ahead. There are still a few things in the 7.0 milestone before we ship stable. |
|
Yeah, I meant a beta. Sorry if my phrasing was confusing. I just didn't want to put anything new out -- even a beta -- without giving you a chance to weigh in. |
Based on the suggestion in #514, this is my attempt at putting together what I think is ideal behavior for webargs: we have sensible defaults for
unknownbased on locations, but it's easy to opt-out by just settingunknown=Noneor overriding the defaults.It should be possible to use the
query,headers, and similar locations out of the box without issue. By passingunknown=EXCLUDEfor these locations, that is achieved.This introduces a new Parser-class variable,
DEFAULT_UNKNOWN_BY_LOCATION, which maps location names tounknownvalues. It populates that andDEFAULT_UNKNOWNto passEXCLUDEin the general case andRAISEfor request bodies.The new behavior is layered and defined with lower precedence than
Parser.unknownor theunknownparameter on parse calls. In order to implement this and allow users to opt out of the behavior (i.e. in order to use schema-defined values), the way these values are set is subtly changed. Instead of having a default value ofNone, parse calls and parser__init__have a default ofunknown="_default". When that value is detected, the various layers of defaults (DEFAULT_UNKNOWN and DEFAULT_UNKNOWN_BY_LOCATION) are applied. However, if a user passesNone, that will take effect with the meaning "do not pass a value forunknown".The changelog has been updated significantly in order to handle this and a new section of the advanced usage docs covers the behavior.
If this seems good, I'd like to switch the branches around so that we have a 6.x maintenance branch and 7.0 is in progress in
dev, as @lafrech suggested. I think we could release this as7.0.0b1, if that sounds acceptable. And then other work (like dropping 3.5) can happen during the 7.0 beta period.