API - webargs 8.7.1 documentation

Skip to content
Back to top
View this page

# API

## webargs.core

class webargs.core.Parser(location: str | None = None, *, unknown: str | None = '_default', error_handler: ErrorHandler | None = None, schema_class: type[ma.Schema] | None = 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 `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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: ValidateArg = 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: ArgMap[Request]) → 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.

  parse(argmap: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: ValidateArg = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) → Any

    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

    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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', as_kwargs: bool = False, arg_name: str | None = None, validate: ValidateArg = 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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: ValidateArg = 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()`.

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)

  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(note, /)

    Add a note to the 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)

  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: ~collections.abc.MutableMapping, schema: ~marshmallow.schema.Schema, known_multi_fields: tuple[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: str | None = None, *, unknown: str | None = '_default', error_handler: ErrorHandler | None = None, schema_class: type[ma.Schema] | None = None)

  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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: ValidateArg = 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: ArgMap[Request]) → 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: core.ArgMap, req: core.Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: core.ValidateArg = None, error_status_code: int | None = None, error_headers: Mapping[str, str] | None = None) → Any

    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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', as_kwargs: bool = False, arg_name: str | None = None, validate: ValidateArg = 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: ArgMap[Request], req: Request | None = None, *, location: str | None = None, unknown: str | None = '_default', validate: ValidateArg = 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

## webargs.djangoparser

## webargs.bottleparser

## webargs.tornadoparser

## webargs.pyramidparser

## webargs.falconparser

## webargs.aiohttpparser