0
# WebArgs
1

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

4
## Package Information
5

6
- **Package Name**: webargs
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install webargs`
10

11
## Core Imports
12

13
```python
14
import webargs
15
from webargs import fields, validate, ValidationError, missing
16
```
17

18
Framework-specific imports:
19

20
```python
21
from webargs.flaskparser import use_args, use_kwargs
22
from webargs.djangoparser import use_args, use_kwargs
23
from webargs.aiohttpparser import use_args, use_kwargs
24
# ... other framework parsers
25
```
26

27
## Basic Usage
28

29
```python
30
from flask import Flask
31
from webargs import fields
32
from webargs.flaskparser import use_args
33

34
app = Flask(__name__)
35

36
# Define argument schema
37
user_args = {
38
    "name": fields.Str(required=True),
39
    "age": fields.Int(missing=18),
40
    "email": fields.Email(),
41
    "active": fields.Bool(location="query")
42
}
43

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

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

58
## Architecture
59

60
WebArgs follows a modular architecture with three main components:
61

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

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

69
## Capabilities
70

71
### Core Parsing
72

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

75
```python { .api }
76
class Parser:
77
    def parse(self, argmap, req=None, *, location=None, unknown=None, validate=None, error_status_code=None, error_headers=None): ...
78
    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): ...
79
    def use_kwargs(self, argmap, req=None, *, location=None, unknown=None, validate=None, error_status_code=None, error_headers=None): ...
80
```
81

82
[Core Parsing](./core-parsing.md)
83

84
### Field Types
85

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

88
```python { .api }
89
class DelimitedList(Field):
90
    def __init__(self, cls_or_instance, *, delimiter=None, **kwargs): ...
91

92
class DelimitedTuple(Field):
93
    def __init__(self, tuple_fields, *, delimiter=None, **kwargs): ...
94
```
95

96
[Field Types](./field-types.md)
97

98
### Framework Parsers
99

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

102
```python { .api }
103
class FlaskParser(Parser): ...
104
class DjangoParser(Parser): ...
105
class AIOHTTPParser(AsyncParser): ...
106
# ... other framework parsers
107

108
def use_args(argmap, req=None, **kwargs): ...
109
def use_kwargs(argmap, req=None, **kwargs): ...
110
```
111

112
[Framework Parsers](./framework-parsers.md)
113

114
### Testing Utilities
115

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

118
```python { .api }
119
class CommonTestCase:
120
    def create_app(self): ...
121
    def create_testapp(self, app): ...
122
```
123

124
[Testing Utilities](./testing-utilities.md)
125

126
## Types
127

128
```python { .api }
129
class ValidationError(marshmallow.ValidationError):
130
    """Exception raised when validation fails during request parsing."""
131

132
# Sentinel value representing missing data
133
missing = marshmallow.missing
134

135
ArgMap = Union[
136
    marshmallow.Schema,
137
    Type[marshmallow.Schema], 
138
    Mapping[str, marshmallow.fields.Field],
139
    Callable[[Request], marshmallow.Schema]
140
]
141

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

144
ErrorHandler = Callable[..., NoReturn]
145

146
Request = TypeVar("Request")
147
```