webargs 8.7.1 documentation

Skip to content
Back to top
View this page

# webargs

Release v8.7.1. (Changelog)

webargs is a Python library for parsing and validating HTTP request objects, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, Falcon, and aiohttp.

## Upgrading from an older version?

See the Upgrading to Newer Releases page for notes on getting your code up-to-date with the latest version.

## Usage and Simple Examples

    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__":
        app.run()

    # curl http://localhost:5000/\?name\='World'
    # Hello World

By default Webargs will automatically parse JSON request bodies. But it also has support for:

Query Parameters

    $ curl http://localhost:5000/\?name\='Freddie'
    Hello Freddie

    # pass location="query" to use_args

Form Data

    $ curl -d 'name=Brian' http://localhost:5000/
    Hello Brian

    # pass location="form" to use_args

JSON Data

    $ curl -X POST -H "Content-Type: application/json" -d '{"name":"Roger"}' http://localhost:5000/
    Hello Roger

    # pass location="json" (or omit location) to use_args

and, optionally:

- Headers

- Cookies

- Files

- Paths

## Why Use It

- Simple, declarative syntax. Define your arguments as a mapping rather than imperatively pulling values off of request objects.

- Code reusability. If you have multiple views that have the same request parameters, you only need to define your parameters once. You can also reuse validation and pre-processing routines.

- Self-documentation. Webargs makes it easy to understand the expected arguments and their types for your view functions.

- Automatic documentation. The metadata that webargs provides can serve as an aid for automatically generating API documentation.

- Cross-framework compatibility. Webargs provides a consistent request-parsing interface that will work across many Python web frameworks.

- marshmallow integration. Webargs uses marshmallow under the hood. When you need more flexibility than dictionaries, you can use marshmallow `Schemas` to define your request arguments.

## Get It Now

    pip install -U webargs

Ready to get started? Go on to the Quickstart tutorial or check out some examples.

## User Guide

- Install
  - From the PyPI
  - Get the Bleeding Edge Version
- Quickstart
  - Basic Usage
  - Decorator API
  - Request “Locations”
  - Validation
  - Error Handling
  - Parsing Lists in Query Strings
  - Nesting Fields
  - Next Steps
- Advanced Usage
  - Custom Location Handlers
  - marshmallow Integration
  - Setting `unknown`
  - When to avoid `use_kwargs`
  - Schema Factories
  - Custom Fields
  - Custom Parsers
  - Parser pre_load
  - Returning HTTP 400 Responses
  - Bulk-type Arguments
  - Multi-Field Detection
  - Mixing Locations
  - Argument Passing and `arg_name`
  - Next Steps
- Framework Support
  - Flask
  - Django
  - Tornado
  - Pyramid
  - Falcon
  - aiohttp
  - Bottle
- Ecosystem

## API Reference

- API
  - webargs.core
  - webargs.fields
  - webargs.multidictproxy
  - webargs.asyncparser
  - webargs.flaskparser
  - webargs.djangoparser
  - webargs.bottleparser
  - webargs.tornadoparser
  - webargs.pyramidparser
  - webargs.falconparser
  - webargs.aiohttpparser

## Project Info

- License
- Changelog
- Upgrading to Newer Releases
- Authors
- Contributing Guidelines