Remove Parser.DEFAULT_UNKNOWN to reduce complexity

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.

Author: sirosen

CHANGELOG.rst

@@ -27,8 +27,8 @@ Refactoring:
 
 Features:
 
-* Add ``unknown`` as a parameter to ``Parser.parse``, ``Parser.use_args``, and
-  ``Parser.use_kwargs``, or to parser instantiation. When set, it will be passed
+* Add ``unknown`` as a parameter to ``Parser.parse``, ``Parser.use_args``,
+  ``Parser.use_kwargs``, and parser instantiation. When set, it will be passed
   to ``Schema.load``. When not set, the value passed will depend on the parser's
   settings. If set to ``None``, the schema's default behavior will be used (i.e.
   no value is passed to ``Schema.load``) and parser settings will be ignored.
@@ -48,8 +48,7 @@ This allows usages like
 
 * Defaults for ``unknown`` may be customized on parser classes via
   ``Parser.DEFAULT_UNKNOWN_BY_LOCATION``, which maps location names to values
-  to use, and ``Parser.DEFAULT_UNKNOWN``, which is used when a location is not
-  found in ``DEFAULT_UNKNOWN_BY_LOCATION``.
+  to use.
 
 Usages are varied, but include
 
@@ -58,8 +57,6 @@ Usages are varied, but include
     import marshmallow as ma
     from webargs.flaskparser import FlaskParser
 
-    parser = FlaskParser(unknown=ma.INCLUDE)
-
     # as well as...
     class MyParser(FlaskParser):
         DEFAULT_UNKNOWN_BY_LOCATION = {"query": ma.INCLUDE}
@@ -78,7 +75,7 @@ will always pass ``RAISE``, even when the location is ``query``.
 * By default, webargs will pass ``unknown=EXCLUDE`` for all locations except
   for request bodies (``json``, ``form``, and ``json_or_form``) and path
   parameters. Request bodies and path parameters will pass ``unknown=RAISE``.
-  This behavior is defined by the default values for ``DEFAULT_UNKNOWN`` and
+  This behavior is defined by the default value for
   ``DEFAULT_UNKNOWN_BY_LOCATION``.
 
 Changes:

docs/advanced.rst

@@ -151,30 +151,24 @@ Default `unknown`
 +++++++++++++++++
 
 By default, webargs will pass `unknown=marshmallow.EXCLUDE` except when the
-location is `json`, `form`, or `json_or_form`. In those cases, it uses
-`unknown=marshmallow.RAISE` instead.
+location is `json`, `form`, `json_or_form`, `path`, or `path`. In those cases,
+it uses `unknown=marshmallow.RAISE` instead.
 
-You can change these defaults by overriding `DEFAULT_UNKNOWN_BY_LOCATION` and
-`DEFAULT_UNKNOWN`. The first is a mapping of locations to values to pass, and
-the second is the fallback value used if the location is not included in the
-map.
-
-You can also define a default at parser instantiation, which will take
-precedence over these defaults.
+You can change these defaults by overriding `DEFAULT_UNKNOWN_BY_LOCATION`.
+This is a mapping of locations to values to pass.
 
 For example,
 
 .. code-block:: python
 
     from flask import Flask
-    from marshmallow import EXCLUDE, INCLUDE, fields
+    from marshmallow import EXCLUDE, fields
     from webargs.flaskparser import FlaskParser
 
     app = Flask(__name__)
 
 
     class Parser(FlaskParser):
-        DEFAULT_UNKNOWN = INCLUDE
         DEFAULT_UNKNOWN_BY_LOCATION = {"query": EXCLUDE}
 
 
@@ -190,14 +184,30 @@ For example,
 
 
     # location is "json", which is not in DEFAULT_UNKNOWN_BY_LOCATION,
-    # so the parser's default value, `INCLUDE`, will be used
+    # so no value will be passed for `unknown`
+    @app.route("/", methods=["POST"])
+    @parser.use_args({"foo": fields.Int(), "bar": fields.Int()}, location="json")
+    def post(self, args):
+        return f"foo x bar = {args['foo'] * args['bar']}"
+
+
+You can also define a default at parser instantiation, which will take
+precedence over these defaults, as in
+
+.. code-block:: python
+
+    from marshmallow import INCLUDE
+
+    parser = Parser(unknown=INCLUDE)
+
+    # because `unknown` is set on the parser, `DEFAULT_UNKNOWN_BY_LOCATION` has
+    # effect and `INCLUDE` will always be used
     @app.route("/", methods=["POST"])
     @parser.use_args({"foo": fields.Int(), "bar": fields.Int()}, location="json")
     def post(self, args):
         unexpected_args = [k for k in args.keys() if k not in ("foo", "bar")]
         return f"foo x bar = {args['foo'] * args['bar']}; unexpected args={unexpected_args}"
 
-
 Using Schema-Specfied `unknown`
 +++++++++++++++++++++++++++++++
 
@@ -230,9 +240,8 @@ If you wish to use the value of `unknown` specified by a schema, simply pass
         return f"area = {args['length'] * args['width']}"
 
 
-You can also set ``unknown=None`` when instantiating a parser, or set
-``DEFAULT_UNKNOWN = None`` to make this behavior the default for a parser
-class.
+You can also set ``unknown=None`` when instantiating a parser to make this
+behavior the default for a parser.
 
 
 When to avoid `use_kwargs`

src/webargs/asyncparser.py

@@ -45,9 +45,7 @@ async def parse(
             else (
                 self.unknown
                 if self.unknown != core._UNKNOWN_DEFAULT_PARAM
-                else self.DEFAULT_UNKNOWN_BY_LOCATION.get(
-                    location, self.DEFAULT_UNKNOWN
-                )
+                else self.DEFAULT_UNKNOWN_BY_LOCATION.get(location)
             )
         )
         load_kwargs = {"unknown": unknown}

src/webargs/core.py

@@ -111,12 +111,16 @@ class Parser:
     #: Default location to check for data
     DEFAULT_LOCATION = "json"
     #: Default value to use for 'unknown' on schema load
-    DEFAULT_UNKNOWN = ma.EXCLUDE
-    #: per-location default for 'unknown'
+    #  on a per-location basis
     DEFAULT_UNKNOWN_BY_LOCATION = {
         "json": ma.RAISE,
         "form": ma.RAISE,
         "json_or_form": ma.RAISE,
+        "querystring": ma.EXCLUDE,
+        "query": ma.EXCLUDE,
+        "headers": ma.EXCLUDE,
+        "cookies": ma.EXCLUDE,
+        "files": ma.EXCLUDE,
     }
     #: The marshmallow Schema class to use when creating new schemas
     DEFAULT_SCHEMA_CLASS = ma.Schema
@@ -267,16 +271,14 @@ def parse(
         """
         req = req if req is not None else self.get_default_request()
         location = location or self.location
-        # precedence order: explicit, instance setting, default per location, default
+        # precedence order: explicit, instance setting, default per location
         unknown = (
             unknown
             if unknown != _UNKNOWN_DEFAULT_PARAM
             else (
                 self.unknown
                 if self.unknown != _UNKNOWN_DEFAULT_PARAM
-                else self.DEFAULT_UNKNOWN_BY_LOCATION.get(
-                    location, self.DEFAULT_UNKNOWN
-                )
+                else self.DEFAULT_UNKNOWN_BY_LOCATION.get(location)
             )
         )
         load_kwargs = {"unknown": unknown} if unknown else {}

tests/test_core.py

@@ -114,7 +114,6 @@ def test_parse(parser, web_request):
         "parse_call",
         "parser_default",
         "parser_class_default",
-        "parser_class_location_default",
     ],
 )
 def test_parse_with_unknown_behavior_specified(parser, web_request, set_location):
@@ -142,14 +141,6 @@ def parse_with_desired_behavior(value):
         elif set_location == "parser_class_default":
 
             class CustomParser(MockRequestParser):
-                DEFAULT_UNKNOWN = value
-                DEFAULT_UNKNOWN_BY_LOCATION = {}
-
-            return CustomParser().parse(CustomSchema(), web_request)
-        elif set_location == "parser_class_location_default":
-
-            class CustomParser(MockRequestParser):
-                DEFAULT_UNKNOWN = None
                 DEFAULT_UNKNOWN_BY_LOCATION = {"json": value}
 
             return CustomParser().parse(CustomSchema(), web_request)
@@ -204,7 +195,6 @@ class CustomSchema(Schema):
     if clear_method == "custom_class":
 
         class CustomParser(MockRequestParser):
-            DEFAULT_UNKNOWN = None
             DEFAULT_UNKNOWN_BY_LOCATION = {}
 
         parser = CustomParser()
@@ -213,7 +203,6 @@ class CustomParser(MockRequestParser):
     elif clear_method == "both":
         # setting things in multiple ways should not result in errors
         class CustomParser(MockRequestParser):
-            DEFAULT_UNKNOWN = None
             DEFAULT_UNKNOWN_BY_LOCATION = {}
 
         parser = CustomParser(unknown=None)