or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-parsing.mdfield-types.mdframework-parsers.mdindex.mdtesting-utilities.md
tile.json

tessl/pypi-webargs

Declarative parsing and validation of HTTP request objects, with built-in support for popular web frameworks.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/webargs@8.7.x

To install, run

npx @tessl/cli install tessl/pypi-webargs@8.7.0

index.mddocs/

WebArgs

Declarative parsing and validation of HTTP request objects, with built-in support for popular web frameworks including Flask, Django, Bottle, Tornado, Pyramid, Falcon, and aiohttp. WebArgs provides a unified interface for parsing request arguments across different web frameworks, using marshmallow schemas for validation and type conversion.

Package Information

  • Package Name: webargs
  • Package Type: pypi
  • Language: Python
  • Installation: pip install webargs

Core Imports

import webargs
from webargs import fields, validate, ValidationError, missing

Framework-specific imports:

from webargs.flaskparser import use_args, use_kwargs
from webargs.djangoparser import use_args, use_kwargs
from webargs.aiohttpparser import use_args, use_kwargs
# ... other framework parsers

Basic Usage

from flask import Flask
from webargs import fields
from webargs.flaskparser import use_args

app = Flask(__name__)

# Define argument schema
user_args = {
    "name": fields.Str(required=True),
    "age": fields.Int(missing=18),
    "email": fields.Email(),
    "active": fields.Bool(location="query")
}

@app.route("/users", methods=["POST"])
@use_args(user_args)
def create_user(args):
    name = args["name"]
    age = args["age"]
    return f"Created user {name}, age {age}"

# Using as kwargs
@app.route("/users/<int:user_id>", methods=["PUT"])
@use_kwargs(user_args)
def update_user(user_id, name, age, email, active):
    return f"Updated user {user_id}: {name}"

Architecture

WebArgs follows a modular architecture with three main components:

  • Core Parser: Base Parser class providing framework-agnostic parsing logic
  • Framework Parsers: Specialized parsers for each web framework that extend the core parser
  • Field System: Integration with marshmallow fields for validation and type conversion
  • Location System: Configurable parsing from different request locations (JSON, query params, form data, headers, cookies, files)

The architecture enables consistent request parsing across different web frameworks while maintaining framework-specific optimizations and error handling patterns.

Capabilities

Core Parsing

Central parsing functionality including the base Parser class, parse methods, decorators for automatic argument injection, and location-based data loading.

class Parser:
    def parse(self, argmap, req=None, *, location=None, unknown=None, validate=None, error_status_code=None, error_headers=None): ...
    def use_args(self, argmap, req=None, *, location=None, unknown=None, as_kwargs=False, arg_name=None, validate=None, error_status_code=None, error_headers=None): ...
    def use_kwargs(self, argmap, req=None, *, location=None, unknown=None, validate=None, error_status_code=None, error_headers=None): ...

Core Parsing

Field Types

Custom field types and marshmallow field integration for parsing delimited strings, handling nested data structures, and extending field validation capabilities.

class DelimitedList(Field):
    def __init__(self, cls_or_instance, *, delimiter=None, **kwargs): ...

class DelimitedTuple(Field):
    def __init__(self, tuple_fields, *, delimiter=None, **kwargs): ...

Field Types

Framework Parsers

Framework-specific parser implementations that provide seamless integration with Flask, Django, Bottle, Tornado, Pyramid, Falcon, and aiohttp, including async support.

class FlaskParser(Parser): ...
class DjangoParser(Parser): ...
class AIOHTTPParser(AsyncParser): ...
# ... other framework parsers

def use_args(argmap, req=None, **kwargs): ...
def use_kwargs(argmap, req=None, **kwargs): ...

Framework Parsers

Testing Utilities

Testing support including base test classes for parser validation, common test scenarios, and utilities for testing request parsing across different web frameworks.

class CommonTestCase:
    def create_app(self): ...
    def create_testapp(self, app): ...

Testing Utilities

Types

class ValidationError(marshmallow.ValidationError):
    """Exception raised when validation fails during request parsing."""

# Sentinel value representing missing data
missing = marshmallow.missing

ArgMap = Union[
    marshmallow.Schema,
    Type[marshmallow.Schema], 
    Mapping[str, marshmallow.fields.Field],
    Callable[[Request], marshmallow.Schema]
]

ValidateArg = Union[None, Callable, Iterable[Callable]]

ErrorHandler = Callable[..., NoReturn]

Request = TypeVar("Request")