webargs

Bump version and update changelog

Bump version, update changelog, and update LICENSE

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bug fixes:

• Fix DelimitedList and DelimitedTuple to pass additional keyword arguments through their _serialize methods to the child fields and fix type checking on these classes. (569) Thanks to decaz for reporting.

Changes:

• Backwards-incompatible: Drop support for webapp2 (565).

• Add type annotations to Parser class, DelimitedList, and DelimitedTuple. (566)

Features:

• DjangoParser now supports the headers location. (540)

• FalconParser now supports a new media location, which uses Falcon's media decoding. (253)

media behaves very similarly to the json location but also supports any registered media handler. See the Falcon documentation on media types for more details.

Changes:

• FalconParser defaults to the media location instead of json. (253)

• Test against Python 3.9 (552).

• Backwards-incompatible: Drop support for Python 3.5 (553).

Refactoring:

• Backwards-incompatible: Remove support for marshmallow2 (539)

• Backwards-incompatible: Remove dict2schema

  Users desiring the dict2schema functionality may now rely upon marshmallow.Schema.from_dict. Rewrite any code using dict2schema like so:

import marshmallow as ma

# webargs 6.x and older
from webargs import dict2schema

myschema = dict2schema({"q1", ma.fields.Int()})

# webargs 7.x
myschema = ma.Schema.from_dict({"q1", ma.fields.Int()})

Features:

• 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.

This allows usages like

import marshmallow as ma


@parser.use_kwargs(
    {"q1": ma.fields.Int(), "q2": ma.fields.Int()}, location="query", unknown=ma.EXCLUDE
)
def foo(q1, q2): ...

• Defaults for unknown may be customized on parser classes via Parser.DEFAULT_UNKNOWN_BY_LOCATION, which maps location names to values to use.

Usages are varied, but include

import marshmallow as ma
from webargs.flaskparser import FlaskParser


# as well as...
class MyParser(FlaskParser):
    DEFAULT_UNKNOWN_BY_LOCATION = {"query": ma.INCLUDE}


parser = MyParser()

Setting the unknown value for a Parser instance has higher precedence. So

parser = MyParser(unknown=ma.RAISE)

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 value for DEFAULT_UNKNOWN_BY_LOCATION.

Changes:

• Registered error_handler callbacks are required to raise an exception. If a handler is invoked and no exception is raised, webargs will raise a ValueError (527)

Bug fixes:

• Failure to validate flask headers would produce error data which contained tuples as keys, and was therefore not JSON-serializable. (500) These errors will now extract the headername as the key correctly. Thanks to shughes-uk for reporting.

Features:

• Add fields.DelimitedTuple when using marshmallow 3. This behaves as a combination of fields.DelimitedList and marshmallow.fields.Tuple. It takes an iterable of fields, plus a delimiter (defaults to ,), and parses delimiter-separated strings into tuples. (509)

• Add __str__ and __repr__ to MultiDictProxy to make it easier to work with (488)

Support:

• Various docs updates (482, 486, 489, 498, 508). Thanks lefterisjp, timgates42, and ugultopu for the PRs.

Features:

• FalconParser: Pass request content length to req.stream.read to provide compatibility with falcon.testing (477). Thanks suola for the PR.

• Backwards-incompatible: Factorize the use_args / use_kwargs branch in all parsers. When as_kwargs is False, arguments are now consistently appended to the arguments list by the use_args decorator. Before this change, the PyramidParser would prepend the argument list on each call to use_args. Pyramid view functions must reverse the order of their arguments. (478)

Refactoring:

• Backwards-incompatible: Use keyword-only arguments (472).

Features:

• Backwards-incompatible: webargs will rewrite the error messages in ValidationErrors to be namespaced under the location which raised the error. The messages field on errors will therefore be one layer deeper with a single top-level key.

Refactoring:

• Remove the cache attached to webargs parsers. Due to changes between webargs v5 and v6, the cache is no longer considered useful.

Other changes:

• Import Mapping from collections.abc in pyramidparser.py (471). Thanks tirkarthi for the PR.

Refactoring:

• Backwards-incompatible: DelimitedList now requires that its input be a string and always serializes as a string. It can still serialize and deserialize using another field, e.g. DelimitedList(Int()) is still valid and requires that the values in the list parse as ints.

Bug fixes:

• CVE-2020-7965: Don't attempt to parse JSON if request's content type is mismatched (bugfix from 5.5.3).

Features:

• Backwards-incompatible: Support Falcon 2.0. Drop support for Falcon 1.x (459). Thanks dodumosu and Nateyo for the PR.

Other changes:

• Backwards-incompatible: Drop support for Python 2 (440). Thanks hugovk for the PR.

Features:

• Backwards-incompatible: Schemas will now load all data from a location, not only data specified by fields. As a result, schemas with validators which examine the full input data may change in behavior. The unknown parameter on schemas may be used to alter this. For example, unknown=marshmallow.EXCLUDE will produce a behavior similar to webargs v5.

Bug fixes:

• Backwards-incompatible: All parsers now require the Content-Type to be set correctly when processing JSON request bodies. This impacts DjangoParser, FalconParser, FlaskParser, and PyramidParser

Refactoring:

• Backwards-incompatible: Schema fields may not specify a location any longer, and Parser.use_args and Parser.use_kwargs now accept location (singular) instead of locations (plural). Instead of using a single field or schema with multiple locations, users are recommended to make multiple calls to use_args or use_kwargs with a distinct schema per location. For example, code should be rewritten like this:

# webargs 5.x and older
@parser.use_args(
    {
        "q1": ma.fields.Int(location="query"),
        "q2": ma.fields.Int(location="query"),
        "h1": ma.fields.Int(location="headers"),
    },
    locations=("query", "headers"),
)
def foo(q1, q2, h1): ...


# webargs 6.x
@parser.use_args({"q1": ma.fields.Int(), "q2": ma.fields.Int()}, location="query")
@parser.use_args({"h1": ma.fields.Int()}, location="headers")
def foo(q1, q2, h1): ...

• The location_handler decorator has been removed and replaced with location_loader. location_loader serves the same purpose (letting you write custom hooks for loading data) but its expected method signature is different. See the docs on location_loader for proper usage.

Thanks sirosen for the PR!

Bug fixes:

• CVE-2020-7965: Don't attempt to parse JSON if request's content type is mismatched.

Bug fixes:

• Handle UnicodeDecodeError when parsing JSON payloads (427). Thanks lindycoder for the catch and patch.

Bug fixes:

• Remove usage of deprecated Field.fail when using marshmallow 3.

Support:

• Various docs updates (414, 421).

Refactoring:

• Don't mutate globals() in webargs.fields (411).

• Use marshmallow 3's Schema.from_dict if available (415).

Changes:

• Use explicit type check for fields.DelimitedList when deciding to parse value with getlist() (#406 (comment) ).

Support:

• Add "Parsing Lists in Query Strings" section to docs (406).

Bug fixes:

• marshmallow 3.0.0rc7 compatibility (395).

Bug fixes:

• marshmallow 3.0.0rc6 compatibility (384).

Features:

• Add "path" location to AIOHTTPParser, FlaskParser, and PyramidParser (379). Thanks zhenhua32 for the PR.

• Add webargs.__version_info__.

Features:

• Make the schema class used when generating a schema from a dict overridable (375). Thanks ThiefMaster.

Bug fixes:

• CVE-2019-9710: Fix race condition between parallel requests when the cache is used (371). Thanks ThiefMaster for reporting and fixing.

Bug fixes:

• Remove lingering usages of ValidationError.status_code (365). Thanks decaz for reporting.

• Avoid AttributeError on Python<3.5.4 (366).

• Fix incorrect type annotations for error_headers.

• Fix outdated docs (367). Thanks alexandersoto for reporting.

• Include LICENSE in sdist (364).

Bug fixes:

• Fix installing simplejson on Python 2 by distributing a Python 2-only wheel (363).

Features:

• Error handlers for AsyncParser classes may be coroutine functions.

• Add type annotations to AsyncParser and AIOHTTPParser.

Bug fixes:

• Fix compatibility with Flask<1.0 (355). Thanks hoatle for reporting.

• Address warning on Python 3.7 about importing from collections.abc.

Features:

• Backwards-incompatible: A 400 HTTPError is raised when an invalid JSON payload is passed. (329). Thanks zedrdave for reporting.

Other changes:

• Backwards-incompatible: webargs.argmap2schema is removed. Use webargs.dict2schema instead.

• Backwards-incompatible: webargs.ValidationError is removed. Use marshmallow.ValidationError instead.

# <5.0.0
from webargs import ValidationError


def auth_validator(value):
    # ...
    raise ValidationError("Authentication failed", status_code=401)


@use_args({"auth": fields.Field(validate=auth_validator)})
def auth_view(args):
    return jsonify(args)


# >=5.0.0
from marshmallow import ValidationError


def auth_validator(value):
    # ...
    raise ValidationError("Authentication failed")


@use_args({"auth": fields.Field(validate=auth_validator)}, error_status_code=401)
def auth_view(args):
    return jsonify(args)

• Backwards-incompatible: Missing arguments will no longer be filled in when using @use_kwargs (342,307,252). Use **kwargs to account for non-required fields.

# <5.0.0
@use_kwargs(
    {"first_name": fields.Str(required=True), "last_name": fields.Str(required=False)}
)
def myview(first_name, last_name):
    # last_name is webargs.missing if it's missing from the request
    return {"first_name": first_name}


# >=5.0.0
@use_kwargs(
    {"first_name": fields.Str(required=True), "last_name": fields.Str(required=False)}
)
def myview(first_name, **kwargs):
    # last_name will not be in kwargs if it's missing from the request
    return {"first_name": first_name}

• simplejson is now a required dependency on Python 2 (334). This ensures consistency of behavior across Python 2 and 3.

Bug fixes:

• Remove usages of argmap2schema from fields.Nested, AsyncParser, and PyramidParser.

• Deprecation: argmap2schema is deprecated in favor of dict2schema (352).

• Add force_all param to PyramidParser.use_args.

• Add warning about missing arguments to AsyncParser.

• Deprecation: Add warning about missing arguments getting added to parsed arguments dictionary (342). This behavior will be removed in version 5.0.0.

Features:

• Add force_all argument to use_args and use_kwargs (252, 307). Thanks piroux for reporting.

• Deprecation: The status_code and headers arguments to ValidationError are deprecated. Pass error_status_code and error_headers to Parser.parse, Parser.use_args, and Parser.use_kwargs instead. (327, 336).

• Custom error handlers receive error_status_code and error_headers arguments. (327).

# <4.2.0
@parser.error_handler
def handle_error(error, req, schema):
    raise CustomError(error.messages)


class MyParser(FlaskParser):
    def handle_error(self, error, req, schema):
        # ...
        raise CustomError(error.messages)


# >=4.2.0
@parser.error_handler
def handle_error(error, req, schema, status_code, headers):
    raise CustomError(error.messages)


# OR


@parser.error_handler
def handle_error(error, **kwargs):
    raise CustomError(error.messages)


class MyParser(FlaskParser):
    def handle_error(self, error, req, schema, status_code, headers):
        # ...
        raise CustomError(error.messages)

    # OR

    def handle_error(self, error, req, **kwargs):
        # ...
        raise CustomError(error.messages)

Legacy error handlers will be supported until version 5.0.0.

Bug fixes:

• Fix bug in AIOHTTParser that prevented calling use_args on the same view function multiple times (273). Thanks to dnp1 for reporting and jangelo for the fix.

• Fix compatibility with marshmallow 3.0.0rc1 (330).

Bug fixes:

• Fix serialization behavior of DelimitedList (319). Thanks lee3164 for the PR.

Other changes:

• Test against Python 3.7.

Bug fixes:

• Fix bug in AIOHTTPParser that caused a JSONDecode error when parsing empty payloads (229). Thanks explosic4 for reporting and thanks user kochab for the PR.

Features:

• Add webargs.testing module, which exposes CommonTestCase to third-party parser libraries (see comments in 287).

Features:

• Backwards-incompatible: Custom error handlers receive the marshmallow.Schema instance as the third argument. Update any functions decorated with Parser.error_handler to take a schema argument, like so:

# 3.x
@parser.error_handler
def handle_error(error, req):
    raise CustomError(error.messages)


# 4.x
@parser.error_handler
def handle_error(error, req, schema):
    raise CustomError(error.messages)

See marshmallow-code/marshmallow#840 (comment) for more information about this change.

Bug fixes:

• Backwards-incompatible: Rename webargs.async to webargs.asyncparser to fix compatibility with Python 3.7 (240). Thanks Reskov for the catch and patch.

Other changes:

• Backwards-incompatible: Drop support for Python 3.4 (243). Python 2.7 and >=3.5 are supported.

• Backwards-incompatible: Drop support for marshmallow<2.15.0. marshmallow>=2.15.0 and >=3.0.0b12 are officially supported.

• Use black with pre-commit for code formatting (244).

Bug fixes:

• Fix compatibility with marshmallow 3.0.0b12 (242). Thanks lafrech.

Bug fixes:

• Respect Parser.DEFAULT_VALIDATION_STATUS when a status_code is not explicitly passed to ValidationError (180). Thanks foresmac for finding this.

Support:

• Add "Returning HTTP 400 Responses" section to docs (180).

Changes:

• Backwards-incompatible: Custom error handlers receive the request object as the second argument. Update any functions decorated with Parser.error_handler to take a req argument, like so:

# 2.x
@parser.error_handler
def handle_error(error):
    raise CustomError(error.messages)


# 3.x
@parser.error_handler
def handle_error(error, req):
    raise CustomError(error.messages)

• Backwards-incompatible: Remove unused instance and kwargs arguments of argmap2schema.

• Backwards-incompatible: Remove Parser.load method (Parser now calls Schema.load directly).

These changes shouldn't affect most users. However, they might break custom parsers calling these methods. (222)

• Drop support for aiohttp<3.0.0.

Features:

• Respect data_key field argument (in marshmallow 3). Thanks lafrech.

Changes:

• Drop support for aiohttp<2.0.0.

• Remove use of deprecated Request.has_body attribute in aiohttpparser (186). Thanks ariddell for reporting.

Features:

• Add support for marshmallow>=3.0.0b7 (188). Thanks lafrech.

Deprecations:

• Support for aiohttp<2.0.0 is deprecated and will be removed in webargs 2.0.0.

Changes:

• HTTPExceptions raised with webargs.flaskparser.abort will always have the data attribute, even if no additional keywords arguments are passed (184). Thanks lafrech.

Support:

• Fix examples in examples/ directory.

Bug fixes:

• Fix behavior of AIOHTTPParser.use_args when as_kwargs=True is passed with a Schema (179). Thanks Itayazolay.

Features:

• AIOHTTPParser supports class-based views, i.e. aiohttp.web.View (177). Thanks daniel98321.

Features:

• AIOHTTPParser.use_args and AIOHTTPParser.use_kwargs work with async def coroutines (170). Thanks zaro.

Support:

• Fix Flask error handling docs in "Framework support" section (168). Thanks nebularazer.