webargs

8.7.1 · active · verified Fri Apr 10

webargs is a Python library for declarative parsing and validation of HTTP request objects. It provides built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, Falcon, and aiohttp. Leveraging Marshmallow under the hood, it offers a consistent API for defining request arguments and handling validation errors across different frameworks. The library is actively maintained, with the current stable version being 8.7.1.

Warnings

breaking webargs 7.x dropped support for Marshmallow 2. Ensure your project is using Marshmallow 3.x or later.
Fix: Upgrade Marshmallow to version 3.x or higher: `pip install -U marshmallow>=3.0.0`.
breaking The `dict2schema` helper function was removed in webargs 7.x.
Fix: Replace `webargs.dict2schema` with `marshmallow.Schema.from_dict`.
breaking The default behavior of the `unknown` parameter changed in webargs 8.x for `json`, `form`, and `json_or_form` locations. It now defaults to `None` instead of `RAISE` if not explicitly set. This means unknown fields might be silently ignored rather than raising an error.
Fix: Explicitly set `unknown=marshmallow.RAISE` in your schema or `use_args`/`use_kwargs` decorator if you require strict validation against unknown fields in these locations. Example: `@use_args(MySchema(unknown=RAISE))`.
breaking webargs 7.x dropped support for Python 3.5 and webapp2.
Fix: Upgrade your Python environment to 3.9 or higher. If using webapp2, migrate to a supported framework.
gotcha When integrating with Flask-RESTful, webargs' default error handling may return HTTP 500 errors for validation failures instead of JSON-formatted errors.
Fix: Register a custom error handler using the parser's `@parser.error_handler` decorator to properly format validation errors as JSON. See `webargs` documentation on 'Error Handling' for details.

Install

pip install -U webargs Install stable version

Imports

fields
```
from webargs import fields
```
While webargs re-exports marshmallow.fields, it's best practice to import directly from webargs for consistency within the library's context.
use_args
```
from webargs.flaskparser import use_args
```
Import path varies by framework (e.g., `webargs.djangoparser`, `webargs.aiohttpparser`).
Arg
```
from webargs import fields
```
The `Arg` class was used in older versions (<=2.x). As of webargs 3.x, `marshmallow.fields.Field` classes (re-exported by `webargs.fields`) are used.
dict2schema
```
from marshmallow import Schema
```
The `dict2schema` helper was removed in webargs 7.x. Use `marshmallow.Schema.from_dict` instead.

Quickstart

This Flask example demonstrates how to use the `use_args` decorator to parse and validate a 'name' query parameter. It uses `fields.Str` from `webargs` (which re-exports `marshmallow.fields`) to define the expected argument.

from flask import Flask
from webargs import fields
from webargs.flaskparser import use_args

app = Flask(__name__)

@app.route("/")
@use_args({"name": fields.Str(required=True)}, location="query")
def index(args):
    return "Hello " + args["name"]

if __name__ == "__main__":
    # To run: python your_app.py
    # Then try: curl "http://127.0.0.1:5000/?name=World"
    app.run(debug=True)

view raw JSON →