API#

webargs.core#

class webargs.core.Parser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

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.

Parameters:
  • 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 marshmallow.EXCLUDE for non-body locations and marshmallow.RAISE for request bodies. Pass None to use the schema’s setting instead.

  • error_handler (callable) – Custom error handler function.

DEFAULT_LOCATION: str = 'json'#

Default location to check for data

DEFAULT_SCHEMA_CLASS#

The marshmallow Schema class to use when creating new schemas

alias of Schema

DEFAULT_VALIDATION_MESSAGE: str = 'Invalid value.'#

Default error message for validation errors

DEFAULT_VALIDATION_STATUS: int = 422#

Default status code to return for validation errors

KNOWN_MULTI_FIELDS: list[type] = [<class 'marshmallow.fields.List'>, <class 'marshmallow.fields.Tuple'>]#

field types which should always be treated as if they set is_multiple=True

async async_parse(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Any[source]#

Coroutine variant of webargs.core.Parser.parse.

Receives the same arguments as webargs.core.Parser.parse.

error_handler(func: ErrorHandlerT) ErrorHandlerT[source]#

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)
Parameters:

func (callable) – The error callback to register.

get_default_arg_name(location: str, schema: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema]) str[source]#

This method provides the rule by which an argument name is derived for use_args() if no explicit arg_name is provided.

By default, the format used is {location}_args. Users may override this method to customize the default argument naming scheme.

schema will be the argument map or schema passed to use_args() unless a dict was used, in which case it will be the schema derived from that dict.

get_default_request() Request | None[source]#

Optional override. Provides a hook for frameworks that use thread-local request objects.

get_request_from_view_args(view: Callable, args: tuple, kwargs: Mapping[str, Any]) Request | None[source]#

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.

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

handle_error(error: ValidationError, req: Request, schema: Schema, *, error_status_code: int | None, error_headers: Mapping[str, str] | None) NoReturn[source]#

Called if an error occurs while parsing args. By default, just logs and raises error.

load_cookies(req: Request, schema: Schema) Any[source]#

Load the cookies from the request or return missing if no value can be found.

load_files(req: Request, schema: Schema) Any[source]#

Load files from the request or return missing if no values can be found.

load_form(req: Request, schema: Schema) Any[source]#

Load the form data of a request object or return missing if no value can be found.

load_headers(req: Request, schema: Schema) Any[source]#

Load the headers or return missing if no value can be found.

load_json(req: Request, schema: Schema) Any[source]#

Load JSON from a request object or return missing if no value can be found.

load_json_or_form(req: Request, schema: Schema) Any[source]#

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_querystring(req: Request, schema: Schema) Any[source]#

Load the query string of a request object or return missing if no value can be found.

location_loader(name: str) Callable[[C], C][source]#

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
Parameters:

name (str) – The name of the location to register.

parse(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Any[source]#

Main request parsing method.

Parameters:
  • 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 marshmallow.EXCLUDE for non-body locations and marshmallow.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) –

    Headers passed to error handler functions when a

    a ValidationError is raised.

    return:

    A dictionary of parsed arguments

pre_load(location_data: Mapping, *, schema: Schema, req: Request, location: str) Mapping[source]#

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.

use_args(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', as_kwargs: bool = False, arg_name: str | None = None, validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Callable[[...], Callable][source]#

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(querystring_args):
    return 'Hello ' + querystring_args['name']
Parameters:
  • 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.

  • arg_name (str) – Keyword argument name to use for arguments. Mutually exclusive with as_kwargs.

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

use_kwargs(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Callable[[...], Callable][source]#

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().

exception webargs.core.ValidationError(message: str | list | dict, field_name: str = '_schema', data: Mapping[str, Any] | Iterable[Mapping[str, Any]] | None = None, valid_data: list[dict[str, Any]] | dict[str, Any] | None = None, **kwargs)[source]#

Raised when validation fails on a field or schema.

Validators and custom fields should raise this exception.

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

add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

webargs.fields#

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"),
}
class webargs.fields.DelimitedList(cls_or_instance: Field | type, *, delimiter: str | None = None, **kwargs)[source]#

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.

Parameters:
  • cls_or_instance (Field) – A field class or instance.

  • delimiter (str) – Delimiter between values.

default_error_messages = {'invalid': 'Not a valid delimited list.'}#

Default error messages.

class webargs.fields.Nested(nested, *args, **kwargs)[source]#

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.

webargs.multidictproxy#

class webargs.multidictproxy.MultiDictProxy(multidict, schema: ~marshmallow.schema.Schema, known_multi_fields: ~typing.Tuple[~typing.Type, ...] = (<class 'marshmallow.fields.List'>, <class 'marshmallow.fields.Tuple'>))[source]#

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.

webargs.asyncparser#

Asynchronous request parser.

class webargs.asyncparser.AsyncParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Asynchronous variant of webargs.core.Parser.

The parse method is redefined to be async.

DEFAULT_LOCATION: str = 'json'#

Default location to check for data

DEFAULT_SCHEMA_CLASS#

alias of Schema

DEFAULT_VALIDATION_MESSAGE: str = 'Invalid value.'#

Default error message for validation errors

DEFAULT_VALIDATION_STATUS: int = 422#

Default status code to return for validation errors

KNOWN_MULTI_FIELDS: list[type] = [<class 'marshmallow.fields.List'>, <class 'marshmallow.fields.Tuple'>]#

field types which should always be treated as if they set is_multiple=True

async async_parse(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Any#

Coroutine variant of webargs.core.Parser.parse.

Receives the same arguments as webargs.core.Parser.parse.

error_handler(func: ErrorHandlerT) ErrorHandlerT#

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)
Parameters:

func (callable) – The error callback to register.

get_default_arg_name(location: str, schema: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema]) str#

This method provides the rule by which an argument name is derived for use_args() if no explicit arg_name is provided.

By default, the format used is {location}_args. Users may override this method to customize the default argument naming scheme.

schema will be the argument map or schema passed to use_args() unless a dict was used, in which case it will be the schema derived from that dict.

get_default_request() Request | None#

Optional override. Provides a hook for frameworks that use thread-local request objects.

get_request_from_view_args(view: Callable, args: tuple, kwargs: Mapping[str, Any]) Request | None#

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.

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

handle_error(error: ValidationError, req: Request, schema: Schema, *, error_status_code: int | None, error_headers: Mapping[str, str] | None) NoReturn#

Called if an error occurs while parsing args. By default, just logs and raises error.

load_cookies(req: Request, schema: Schema) Any#

Load the cookies from the request or return missing if no value can be found.

load_files(req: Request, schema: Schema) Any#

Load files from the request or return missing if no values can be found.

load_form(req: Request, schema: Schema) Any#

Load the form data of a request object or return missing if no value can be found.

load_headers(req: Request, schema: Schema) Any#

Load the headers or return missing if no value can be found.

load_json(req: Request, schema: Schema) Any#

Load JSON from a request object or return missing if no value can be found.

load_json_or_form(req: Request, schema: Schema) Any#

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_querystring(req: Request, schema: Schema) Any#

Load the query string of a request object or return missing if no value can be found.

location_loader(name: str) Callable[[C], C]#

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
Parameters:

name (str) – The name of the location to register.

async parse(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Any[source]#

Coroutine variant of webargs.core.Parser.

Receives the same arguments as webargs.core.Parser.parse.

pre_load(location_data: Mapping, *, schema: Schema, req: Request, location: str) Mapping#

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.

use_args(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', as_kwargs: bool = False, arg_name: str | None = None, validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Callable[[...], Callable]#

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(querystring_args):
    return 'Hello ' + querystring_args['name']
Parameters:
  • 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.

  • arg_name (str) – Keyword argument name to use for arguments. Mutually exclusive with as_kwargs.

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

use_kwargs(argmap: Schema | Type[Schema] | Mapping[str, Field | Type[Field]] | Callable[[Request], Schema], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: None | Callable | Iterable[Callable] = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) Callable[[...], Callable]#

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().

webargs.flaskparser#

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"]
    )
class webargs.flaskparser.FlaskParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Flask request argument parser.

get_default_request() Request[source]#

Override to use Flask’s thread-local request object by default

handle_error(error: ValidationError, req: Request, schema: Schema, *, error_status_code: int | None, error_headers: Mapping[str, str] | None) NoReturn[source]#

Handles errors during parsing. Aborts the current HTTP request and responds with a 422 error.

load_cookies(req: Request, schema: Schema) Any[source]#

Return cookies from the request.

load_files(req: Request, schema: Schema) Any[source]#

Return files from the request as a MultiDictProxy.

load_form(req: Request, schema: Schema) Any[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req: Request, schema: Schema) Any[source]#

Return headers from the request as a MultiDictProxy.

load_querystring(req: Request, schema: Schema) Any[source]#

Return query params from the request as a MultiDictProxy.

load_view_args(req: Request, schema: Schema) Any[source]#

Return the request’s view_args or missing if there are none.

webargs.flaskparser.abort(http_status_code: int, exc: Exception | None = None, **kwargs: Any) NoReturn[source]#

Raise a HTTPException for the given http_status_code. Attach any keyword arguments to the exception for later processing.

From Flask-Restful. See NOTICE file for license information.

webargs.djangoparser#

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(load_default='World')
}

class MyView(View):

    @use_args(hello_args)
    def get(self, args, request):
        return HttpResponse('Hello ' + args['name'])
class webargs.djangoparser.DjangoParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

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.

get_request_from_view_args(view, args, kwargs)[source]#

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.

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

load_cookies(req: HttpRequest, schema)[source]#

Return cookies from the request.

load_files(req: HttpRequest, schema)[source]#

Return files from the request as a MultiDictProxy.

load_form(req: HttpRequest, schema)[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req: HttpRequest, schema)[source]#

Return headers from the request.

load_querystring(req: HttpRequest, schema)[source]#

Return query params from the request as a MultiDictProxy.

webargs.bottleparser#

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(load_default='World')
}
@route('/', method='GET', apply=use_args(hello_args))
def index(args):
    return 'Hello ' + args['name']

if __name__ == '__main__':
    run(debug=True)
class webargs.bottleparser.BottleParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Bottle.py request argument parser.

get_default_request()[source]#

Override to use bottle’s thread-local request object by default.

handle_error(error, req, schema, *, error_status_code, error_headers)[source]#

Handles errors during parsing. Aborts the current request with a 400 error.

load_cookies(req, schema)[source]#

Return cookies from the request.

load_files(req, schema)[source]#

Return files from the request as a MultiDictProxy.

load_form(req, schema)[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req, schema)[source]#

Return headers from the request as a MultiDictProxy.

load_querystring(req, schema)[source]#

Return query params from the request as a MultiDictProxy.

webargs.tornadoparser#

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(load_default='World')})
    def get(self, args):
        response = {'message': 'Hello {}'.format(args['name'])}
        self.write(response)
exception webargs.tornadoparser.HTTPError(*args, **kwargs)[source]#

tornado.web.HTTPError that stores validation errors.

class webargs.tornadoparser.TornadoParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Tornado request argument parser.

get_request_from_view_args(view, args, kwargs)[source]#

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.

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

handle_error(error, req: HTTPServerRequest, schema, *, error_status_code, error_headers)[source]#

Handles errors during parsing. Raises a tornado.web.HTTPError with a 400 error.

load_cookies(req: HTTPServerRequest, schema)[source]#

Return cookies from the request as a MultiDictProxy.

load_files(req: HTTPServerRequest, schema)[source]#

Return files from the request as a MultiDictProxy.

load_form(req: HTTPServerRequest, schema)[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req: HTTPServerRequest, schema)[source]#

Return headers from the request as a MultiDictProxy.

load_querystring(req: HTTPServerRequest, schema)[source]#

Return query params from the request as a MultiDictProxy.

class webargs.tornadoparser.WebArgsTornadoCookiesMultiDictProxy(multidict, schema: ~marshmallow.schema.Schema, known_multi_fields: ~typing.Tuple[~typing.Type, ...] = (<class 'marshmallow.fields.List'>, <class 'marshmallow.fields.Tuple'>))[source]#

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

class webargs.tornadoparser.WebArgsTornadoMultiDictProxy(multidict, schema: ~marshmallow.schema.Schema, known_multi_fields: ~typing.Tuple[~typing.Type, ...] = (<class 'marshmallow.fields.List'>, <class 'marshmallow.fields.Tuple'>))[source]#

Override class for Tornado multidicts, handles argument decoding requirements.

webargs.pyramidparser#

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(load_default='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()
class webargs.pyramidparser.PyramidParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Pyramid request argument parser.

handle_error(error, req: Request, schema, *, error_status_code, error_headers)[source]#

Handles errors during parsing. Aborts the current HTTP request and responds with a 400 error.

load_cookies(req: Request, schema)[source]#

Return cookies from the request as a MultiDictProxy.

load_files(req: Request, schema)[source]#

Return files from the request as a MultiDictProxy.

load_form(req: Request, schema)[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req: Request, schema)[source]#

Return headers from the request as a MultiDictProxy.

load_matchdict(req: Request, schema)[source]#

Return the request’s matchdict as a MultiDictProxy.

load_querystring(req: Request, schema)[source]#

Return query params from the request as a MultiDictProxy.

use_args(argmap, req: Request | None = None, *, location='json', unknown=None, as_kwargs=False, arg_name=None, validate=None, error_status_code=None, error_headers=None)[source]#

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.

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

  • arg_name (str) – Keyword argument name to use for arguments. Mutually exclusive with as_kwargs.

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

webargs.pyramidparser.use_args(argmap, req: Request | None = None, *, location='json', unknown=None, as_kwargs=False, arg_name=None, validate=None, error_status_code=None, error_headers=None)#

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.

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

  • arg_name (str) – Keyword argument name to use for arguments. Mutually exclusive with as_kwargs.

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

webargs.falconparser#

Falcon request argument parsing module.

class webargs.falconparser.FalconParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

Falcon request argument parser.

Defaults to using the media location. See load_media() for details on the media location.

DEFAULT_LOCATION: str = 'media'#

Default location to check for data

get_request_from_view_args(view, args, kwargs)[source]#

Get request from a resource method’s arguments. Assumes that request is the second argument.

handle_error(error, req: Request, schema, *, error_status_code, error_headers)[source]#

Handles errors during parsing.

load_cookies(req: Request, schema)[source]#

Return cookies from the request.

load_files(req: Request, schema)[source]#

Load files from the request or return missing if no values can be found.

load_form(req: Request, schema)[source]#

Return form values from the request as a MultiDictProxy

Note

The request stream will be read and left at EOF.

load_headers(req: Request, schema)[source]#

Return headers from the request.

load_media(req: Request, schema)[source]#

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.

load_querystring(req: Request, schema)[source]#

Return query params from the request as a MultiDictProxy.

exception webargs.falconparser.HTTPError(status, errors, *args, **kwargs)[source]#

HTTPError that stores a dictionary of validation error messages.

to_dict(*args, **kwargs)[source]#

Override falcon.HTTPError to include error messages in responses.

webargs.aiohttpparser#

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)
class webargs.aiohttpparser.AIOHTTPParser(location: str | None = None, *, unknown: str | None = '_default', error_handler: Callable[[...], NoReturn] | None = None, schema_class: type[Schema] | None = None)[source]#

aiohttp request argument parser.

get_request_from_view_args(view: Callable, args: Iterable, kwargs: Mapping)[source]#

Get request object from a handler function or method. Used internally by use_args and use_kwargs.

handle_error(error: ValidationError, req, schema: Schema, *, error_status_code: int | None, error_headers: Mapping[str, str] | None) NoReturn[source]#

Handle ValidationErrors and return a JSON response of error messages to the client.

load_cookies(req, schema: Schema) MultiDictProxy[source]#

Return cookies from the request as a MultiDictProxy.

load_files(req, schema: Schema) NoReturn[source]#

Load files from the request or return missing if no values can be found.

async load_form(req, schema: Schema) MultiDictProxy[source]#

Return form values from the request as a MultiDictProxy.

load_headers(req, schema: Schema) MultiDictProxy[source]#

Return headers from the request as a MultiDictProxy.

async load_json(req, schema: Schema)[source]#

Return a parsed json payload from the request.

async load_json_or_form(req, schema: Schema) dict | MultiDictProxy[source]#

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_match_info(req, schema: Schema) Mapping[source]#

Load the request’s match_info.

load_querystring(req, schema: Schema) MultiDictProxy[source]#

Return query params from the request as a MultiDictProxy.

exception webargs.aiohttpparser.HTTPUnprocessableEntity(*, headers: Mapping[str | istr, str] | CIMultiDict | CIMultiDictProxy | None = None, reason: str | None = None, body: Any = None, text: str | None = None, content_type: str | None = None)[source]#