API - webargs 8.1.0 documentation

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# API

## webargs.core

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

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

  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`

  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_request() → Optional[Request]

    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]) → Optional[Request]

    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, error_headers: Mapping[str, str]) → NoReturn

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

  load_cookies(req: Request, schema: Schema)

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

  load_files(req: Request, schema: Schema)

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

  load_form(req: Request, schema: Schema)

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

  load_headers(req: Request, schema: Schema)

    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)

    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)

    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.

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

    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 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) –

        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

    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: Union[Schema, Dict[str, Union[Field, Type[Field]]], Callable[[Request], Schema]], req: Optional[Request] = None, *, location: Optional[str] = None, unknown: str | None = '_default', as_kwargs: bool = False, validate: Union[None, Callable, Iterable[Callable]] = None, error_status_code: Optional[int] = None, error_headers: Optional[Mapping[str, str]] = 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(args):
            return 'Hello ' + 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.

      - 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(*args, **kwargs) → 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()`.

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

  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.

  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: marshmallow.fields.Field | type, *, delimiter: Optional[str] = None, **kwargs)

  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)

  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'>))

  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: Optional[str] = None, *, unknown: str | None = '_default', error_handler: Optional[Callable[[...], NoReturn]] = None, schema_class: Optional[type[marshmallow.schema.Schema]] = None)

  Asynchronous variant of `webargs.core.Parser`, where parsing methods may be either coroutines or regular methods.

  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`

  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_request() → Optional[Request]

    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]) → Optional[Request]

    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, error_headers: Mapping[str, str]) → NoReturn

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

  load_cookies(req: Request, schema: Schema)

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

  load_files(req: Request, schema: Schema)

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

  load_form(req: Request, schema: Schema)

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

  load_headers(req: Request, schema: Schema)

    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)

    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)

    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: Union[Schema, Dict[str, Union[Field, Type[Field]]], Callable[[Request], Schema]], req: Optional[Request] = None, *, location: Optional[str] = None, unknown: str | None = '_default', validate: Union[None, Callable, Iterable[Callable]] = None, error_status_code: Optional[int] = None, error_headers: Optional[Mapping[str, str]] = None) → Optional[Mapping]

    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: Union[Schema, Dict[str, Union[Field, Type[Field]]], Callable[[Request], Schema]], req: Optional[Request] = None, *, location: Optional[str] = None, unknown='_default', as_kwargs: bool = False, validate: Union[None, Callable, Iterable[Callable]] = None, error_status_code: Optional[int] = None, error_headers: Optional[Mapping[str, str]] = None) → Callable[[...], Callable]

    Decorator that injects parsed arguments into a view function or method.

    Receives the same arguments as `webargs.core.Parser.use_args`.

  use_kwargs(*args, **kwargs) → 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

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

    class MyView(View):

        @use_args(hello_args)
        def get(self, args, request):
            return HttpResponse('Hello ' + args['name'])

class webargs.djangoparser.DjangoParser(location: Optional[str] = None, *, unknown: str | None = '_default', error_handler: Optional[Callable[[...], NoReturn]] = None, schema_class: Optional[type[marshmallow.schema.Schema]] = None)

  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)

    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, schema)

    Return cookies from the request.

  load_files(req, schema)

    Return files from the request as a MultiDictProxy.

  load_form(req, schema)

    Return form values from the request as a MultiDictProxy.

  load_headers(req, schema)

    Return headers from the request.

  load_querystring(req, schema)

    Return query params from the request as a MultiDictProxy.

## webargs.bottleparser

## webargs.tornadoparser

## webargs.pyramidparser

## webargs.falconparser

## webargs.aiohttpparser