Base parser class that provides high-level implementation for parsing a request.
Descendant classes must provide lower-level implementations for reading
data from different locations, e.g. load_json, load_querystring,
etc.
location (str) – Default location to use for data
unknown (str) – A default value to pass for unknown when calling the
schema’s load method. Defaults to EXCLUDE for non-body
locations and RAISE for request bodies. Pass None to use the
schema’s setting instead.
error_handler (callable) – Custom error handler function.
alias of marshmallow.schema.Schema
field types which should always be treated as if they set is_multiple=True
Decorator that registers a custom error handling function. The
function should receive the raised error, request object,
marshmallow.Schema instance used to parse the request, error status code,
and headers to use for the error response. Overrides
the parser’s handle_error method.
Example:
from webargs import flaskparser
parser = flaskparser.FlaskParser()
class CustomError(Exception):
pass
@parser.error_handler
def handle_error(error, req, schema, *, error_status_code, error_headers):
raise CustomError(error.messages)
func (callable) – The error callback to register.
Optional override. Provides a hook for frameworks that use thread-local request objects.
Optional override. Returns the request object to be parsed, given a view function’s args and kwargs.
Used by the use_args and use_kwargs to get a request object from a
view’s arguments.
view (callable) – The view function or method being decorated by
use_args or use_kwargs
args (tuple) – Positional arguments passed to view.
kwargs (dict) – Keyword arguments passed to view.
Called if an error occurs while parsing args. By default, just logs and
raises error.
Load the cookies from the request or return missing if no value
can be found.
Load files from the request or return missing if no values can be
found.
Load the form data of a request object or return missing if no
value can be found.
Load the headers or return missing if no value can be found.
Load JSON from a request object or return missing if no value can
be found.
Load data from a request, accepting either JSON or form-encoded data.
The data will first be loaded as JSON, and, if that fails, it will be loaded as a form post.
Load the query string of a request object or return missing if no
value can be found.
Decorator that registers a function for loading a request location. The wrapped function receives a schema and a request.
The schema will usually not be relevant, but it’s important in some
cases – most notably in order to correctly load multidict values into
list fields. Without the schema, there would be no way to know whether
to simply get() or getall() from a multidict for a given value.
Example:
from webargs import core
parser = core.Parser()
@parser.location_loader("name")
def load_data(request, schema):
return request.data
name (str) – The name of the location to register.
Main request parsing method.
argmap – Either a marshmallow.Schema, a dict
of argname -> marshmallow.fields.Field pairs, or a callable
which accepts a request and returns a marshmallow.Schema.
req – The request object to parse.
location (str) – Where on the request to load values.
Can be any of the values in __location_map__. By
default, that means one of ('json', 'query', 'querystring',
'form', 'headers', 'cookies', 'files', 'json_or_form').
unknown (str) – A value to pass for unknown when calling the
schema’s load method. Defaults to EXCLUDE for non-body
locations and RAISE for request bodies. Pass None to use the
schema’s setting instead.
validate (callable) – Validation function or list of validation functions
that receives the dictionary of parsed arguments. Validator either returns a
boolean or raises a ValidationError.
error_status_code (int) – Status code passed to error handler functions when
a ValidationError is raised.
error_headers (dict) –
a ValidationError is raised.
A dictionary of parsed arguments
A method of the parser which can transform data after location loading is done. By default it does nothing, but users can subclass parsers and override this method.
Decorator that injects parsed arguments into a view function or method.
Example usage with Flask:
@app.route('/echo', methods=['get', 'post'])
@parser.use_args({'name': fields.Str()}, location="querystring")
def greet(args):
return 'Hello ' + args['name']
argmap – Either a marshmallow.Schema, a dict
of argname -> marshmallow.fields.Field pairs, or a callable
which accepts a request and returns a marshmallow.Schema.
location (str) – Where on the request to load values.
unknown (str) – A value to pass for unknown when calling the
schema’s load method.
as_kwargs (bool) – Whether to insert arguments as keyword arguments.
validate (callable) – Validation function that receives the dictionary
of parsed arguments. If the function returns False, the parser
will raise a ValidationError.
error_status_code (int) – Status code passed to error handler functions when
a ValidationError is raised.
error_headers (dict) – Headers passed to error handler functions when a
a ValidationError is raised.
Decorator that injects parsed arguments into a view function or method as keyword arguments.
This is a shortcut to use_args() with as_kwargs=True.
Example usage with Flask:
@app.route('/echo', methods=['get', 'post'])
@parser.use_kwargs({'name': fields.Str()})
def greet(name):
return 'Hello ' + name
Receives the same args and kwargs as use_args().
Raised when validation fails on a field or schema.
Validators and custom fields should raise this exception.
message – An error message, list of error messages, or dict of error messages. If a dict, the keys are subitems and the values are error messages.
field_name – Field name to store the error on.
If None, the error is stored as schema-level error.
data – Raw input data.
valid_data – Valid (de)serialized data.
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
Field classes.
Includes all fields from marshmallow.fields in addition to a custom
Nested field and DelimitedList.
All fields can optionally take a special location keyword argument, which
tells webargs where to parse the request argument from.
args = {
"active": fields.Bool(location="query"),
"content_type": fields.Str(data_key="Content-Type", location="headers"),
}
A field which is similar to a List, but takes its input as a delimited string (e.g. “foo,bar,baz”).
Like List, it can be given a nested field type which it will use to de/serialize each element of the list.
cls_or_instance (Field) – A field class or instance.
delimiter (str) – Delimiter between values.
Same as marshmallow.fields.Nested, except can be passed a dictionary as
the first argument, which will be converted to a marshmallow.Schema.
Note
The schema class here will always be marshmallow.Schema, regardless
of whether a custom schema class is set on the parser. Pass an explicit schema
class if necessary.
A proxy object which wraps multidict types along with a matching schema
Whenever a value is looked up, it is checked against the schema to see if
there is a matching field where is_multiple is True. If there is, then
the data should be loaded as a list or tuple.
In all other cases, __getitem__ proxies directly to the input multidict.
Asynchronous request parser.
Asynchronous variant of webargs.core.Parser, where parsing methods may be
either coroutines or regular methods.
alias of marshmallow.schema.Schema
Decorator that registers a custom error handling function. The
function should receive the raised error, request object,
marshmallow.Schema instance used to parse the request, error status code,
and headers to use for the error response. Overrides
the parser’s handle_error method.
Example:
from webargs import flaskparser
parser = flaskparser.FlaskParser()
class CustomError(Exception):
pass
@parser.error_handler
def handle_error(error, req, schema, *, error_status_code, error_headers):
raise CustomError(error.messages)
func (callable) – The error callback to register.
Optional override. Provides a hook for frameworks that use thread-local request objects.
Optional override. Returns the request object to be parsed, given a view function’s args and kwargs.
Used by the use_args and use_kwargs to get a request object from a
view’s arguments.
view (callable) – The view function or method being decorated by
use_args or use_kwargs
args (tuple) – Positional arguments passed to view.
kwargs (dict) – Keyword arguments passed to view.
Called if an error occurs while parsing args. By default, just logs and
raises error.
Load the cookies from the request or return missing if no value
can be found.
Load files from the request or return missing if no values can be
found.
Load the form data of a request object or return missing if no
value can be found.
Load the headers or return missing if no value can be found.
Load JSON from a request object or return missing if no value can
be found.
Load data from a request, accepting either JSON or form-encoded data.
The data will first be loaded as JSON, and, if that fails, it will be loaded as a form post.
Load the query string of a request object or return missing if no
value can be found.
Decorator that registers a function for loading a request location. The wrapped function receives a schema and a request.
The schema will usually not be relevant, but it’s important in some
cases – most notably in order to correctly load multidict values into
list fields. Without the schema, there would be no way to know whether
to simply get() or getall() from a multidict for a given value.
Example:
from webargs import core
parser = core.Parser()
@parser.location_loader("name")
def load_data(request, schema):
return request.data
name (str) – The name of the location to register.
Coroutine variant of webargs.core.Parser.
Receives the same arguments as webargs.core.Parser.parse.
A method of the parser which can transform data after location loading is done. By default it does nothing, but users can subclass parsers and override this method.
Decorator that injects parsed arguments into a view function or method.
Receives the same arguments as webargs.core.Parser.use_args.
Decorator that injects parsed arguments into a view function or method as keyword arguments.
This is a shortcut to use_args() with as_kwargs=True.
Example usage with Flask:
@app.route('/echo', methods=['get', 'post'])
@parser.use_kwargs({'name': fields.Str()})
def greet(name):
return 'Hello ' + name
Receives the same args and kwargs as use_args().
Flask request argument parsing module.
Example:
from flask import Flask
from webargs import fields
from webargs.flaskparser import use_args
app = Flask(__name__)
user_detail_args = {
'per_page': fields.Int()
}
@app.route("/user/<int:uid>")
@use_args(user_detail_args)
def user_detail(args, uid):
return ("The user page for user {uid}, showing {per_page} posts.").format(
uid=uid, per_page=args["per_page"]
)
Flask request argument parser.
Django request argument parsing.
Example usage:
from django.views.generic import View
from django.http import HttpResponse
from marshmallow import fields
from webargs.djangoparser import use_args
hello_args = {
'name': fields.Str(missing='World')
}
class MyView(View):
@use_args(hello_args)
def get(self, args, request):
return HttpResponse('Hello ' + args['name'])
Django request argument parser.
Warning
DjangoParser does not override
handle_error, so your Django
views are responsible for catching any ValidationErrors raised by
the parser and returning the appropriate HTTPResponse.
Bottle request argument parsing module.
Example:
from bottle import route, run
from marshmallow import fields
from webargs.bottleparser import use_args
hello_args = {
'name': fields.Str(missing='World')
}
@route('/', method='GET', apply=use_args(hello_args))
def index(args):
return 'Hello ' + args['name']
if __name__ == '__main__':
run(debug=True)
Bottle.py request argument parser.
Tornado request argument parsing module.
Example:
import tornado.web
from marshmallow import fields
from webargs.tornadoparser import use_args
class HelloHandler(tornado.web.RequestHandler):
@use_args({'name': fields.Str(missing='World')})
def get(self, args):
response = {'message': 'Hello {}'.format(args['name'])}
self.write(response)
tornado.web.HTTPError that stores validation errors.
Tornado request argument parser.
Optional override. Returns the request object to be parsed, given a view function’s args and kwargs.
Used by the use_args and use_kwargs to get a request object from a
view’s arguments.
And a special override for cookies because they come back as objects with a
value attribute we need to extract.
Also, does not use the _unicode decoding step
Override class for Tornado multidicts, handles argument decoding requirements.
Pyramid request argument parsing.
Example usage:
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response
from marshmallow import fields
from webargs.pyramidparser import use_args
hello_args = {
'name': fields.Str(missing='World')
}
@use_args(hello_args)
def hello_world(request, args):
return Response('Hello ' + args['name'])
if __name__ == '__main__':
config = Configurator()
config.add_route('hello', '/')
config.add_view(hello_world, route_name='hello')
app = config.make_wsgi_app()
server = make_server('0.0.0.0', 6543, app)
server.serve_forever()
Pyramid request argument parser.
Handles errors during parsing. Aborts the current HTTP request and responds with a 400 error.
Decorator that injects parsed arguments into a view callable.
Supports the Class-based View pattern where request is saved as an instance
attribute on a view class.
argmap (dict) – Either a marshmallow.Schema, a dict
of argname -> marshmallow.fields.Field pairs, or a callable
which accepts a request and returns a marshmallow.Schema.
req – The request object to parse. Pulled off of the view by default.
location (str) – Where on the request to load values.
unknown (str) – A value to pass for unknown when calling the
schema’s load method.
as_kwargs (bool) – Whether to insert arguments as keyword arguments.
validate (callable) – Validation function that receives the dictionary
of parsed arguments. If the function returns False, the parser
will raise a ValidationError.
error_status_code (int) – Status code passed to error handler functions when
a ValidationError is raised.
error_headers (dict) – Headers passed to error handler functions when a
a ValidationError is raised.
Decorator that injects parsed arguments into a view callable.
Supports the Class-based View pattern where request is saved as an instance
attribute on a view class.
argmap (dict) – Either a marshmallow.Schema, a dict
of argname -> marshmallow.fields.Field pairs, or a callable
which accepts a request and returns a marshmallow.Schema.
req – The request object to parse. Pulled off of the view by default.
location (str) – Where on the request to load values.
unknown (str) – A value to pass for unknown when calling the
schema’s load method.
as_kwargs (bool) – Whether to insert arguments as keyword arguments.
validate (callable) – Validation function that receives the dictionary
of parsed arguments. If the function returns False, the parser
will raise a ValidationError.
error_status_code (int) – Status code passed to error handler functions when
a ValidationError is raised.
error_headers (dict) – Headers passed to error handler functions when a
a ValidationError is raised.
Falcon request argument parsing module.
Falcon request argument parser.
Defaults to using the media location. See load_media() for
details on the media location.
Get request from a resource method’s arguments. Assumes that request is the second argument.
Handles errors during parsing.
Load files from the request or return missing if no values can be
found.
Return form values from the request as a MultiDictProxy
Note
The request stream will be read and left at EOF.
Return data unpacked and parsed by one of Falcon’s media handlers. By default, Falcon only handles JSON payloads.
To configure additional media handlers, see the Falcon documentation on media types.
Note
The request stream will be read and left at EOF.
aiohttp request argument parsing module.
Example:
import asyncio
from aiohttp import web
from webargs import fields
from webargs.aiohttpparser import use_args
hello_args = {
'name': fields.Str(required=True)
}
@asyncio.coroutine
@use_args(hello_args)
def index(request, args):
return web.Response(
body='Hello {}'.format(args['name']).encode('utf-8')
)
app = web.Application()
app.router.add_route('GET', '/', index)
aiohttp request argument parser.
Get request object from a handler function or method. Used internally by
use_args and use_kwargs.
Handle ValidationErrors and return a JSON response of error messages to the client.
Return cookies from the request as a MultiDictProxy.
Load files from the request or return missing if no values can be
found.
Return form values from the request as a MultiDictProxy.
Return headers from the request as a MultiDictProxy.
Return a parsed json payload from the request.
Load data from a request, accepting either JSON or form-encoded data.
The data will first be loaded as JSON, and, if that fails, it will be loaded as a form post.
Load the request’s match_info.
Return query params from the request as a MultiDictProxy.