0
# Framework Parsers
1

2
Framework-specific parser implementations that provide seamless integration with popular Python web frameworks. Each parser extends the core Parser class with framework-specific request handling, error responses, and integration patterns while maintaining a consistent API across all frameworks.
3

4
## Capabilities
5

6
### Flask Parser
7

8
Parser for Flask web framework with support for Flask request objects and error handling.
9

10
```python { .api }
11
class FlaskParser(Parser[flask.Request]):
12
    """
13
    Parser for Flask framework.
14
    
15
    Integrates with Flask's request context and error handling system.
16
    Automatically detects Flask request objects and provides appropriate error responses.
17
    """
18
    def __init__(self, **kwargs): ...
19
    
20
    def load_json(self, req, schema): ...
21
    def load_querystring(self, req, schema): ...
22
    def load_form(self, req, schema): ...
23
    def load_headers(self, req, schema): ...
24
    def load_cookies(self, req, schema): ...
25
    def load_files(self, req, schema): ...
26
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
27

28
# Module-level parser instance and decorators
29
parser = FlaskParser()
30

31
def use_args(argmap, req=None, **kwargs):
32
    """Flask-specific use_args decorator."""
33

34
def use_kwargs(argmap, req=None, **kwargs):
35
    """Flask-specific use_kwargs decorator."""
36

37
def abort(http_status_code, exc=None, **kwargs):
38
    """Raise HTTPException with Flask-specific error handling."""
39
```
40

41
### Django Parser
42

43
Parser for Django web framework with support for Django HttpRequest objects.
44

45
```python { .api }
46
class DjangoParser(Parser[django.http.HttpRequest]):
47
    """
48
    Parser for Django framework.
49
    
50
    Integrates with Django's request/response cycle and error handling.
51
    Handles Django-specific request object structure and content types.
52
    """
53
    def __init__(self, **kwargs): ...
54
    
55
    def load_json(self, req, schema): ...
56
    def load_querystring(self, req, schema): ...
57
    def load_form(self, req, schema): ...
58
    def load_headers(self, req, schema): ...
59
    def load_cookies(self, req, schema): ...
60
    def load_files(self, req, schema): ...
61
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
62

63
# Module-level parser instance and decorators
64
parser = DjangoParser()
65

66
def use_args(argmap, req=None, **kwargs):
67
    """Django-specific use_args decorator."""
68

69
def use_kwargs(argmap, req=None, **kwargs):
70
    """Django-specific use_kwargs decorator."""
71
```
72

73
### Bottle Parser
74

75
Parser for Bottle web framework with support for Bottle request objects.
76

77
```python { .api }
78
class BottleParser(Parser[bottle.Request]):
79
    """
80
    Parser for Bottle framework.
81
    
82
    Integrates with Bottle's request handling and provides appropriate error responses.
83
    """
84
    def __init__(self, **kwargs): ...
85
    
86
    def load_json(self, req, schema): ...
87
    def load_querystring(self, req, schema): ...
88
    def load_form(self, req, schema): ...
89
    def load_headers(self, req, schema): ...
90
    def load_cookies(self, req, schema): ...
91
    def load_files(self, req, schema): ...
92
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
93

94
# Module-level parser instance and decorators
95
parser = BottleParser()
96

97
def use_args(argmap, req=None, **kwargs):
98
    """Bottle-specific use_args decorator."""
99

100
def use_kwargs(argmap, req=None, **kwargs):
101
    """Bottle-specific use_kwargs decorator."""
102
```
103

104
### Tornado Parser
105

106
Parser for Tornado web framework with support for HTTPServerRequest objects.
107

108
```python { .api }
109
class TornadoParser(Parser[tornado.httpserver.HTTPServerRequest]):
110
    """
111
    Parser for Tornado framework.
112
    
113
    Handles Tornado's request structure and provides framework-appropriate error responses.
114
    """
115
    def __init__(self, **kwargs): ...
116
    
117
    def load_json(self, req, schema): ...
118
    def load_querystring(self, req, schema): ...
119
    def load_form(self, req, schema): ...
120
    def load_headers(self, req, schema): ...
121
    def load_cookies(self, req, schema): ...
122
    def load_files(self, req, schema): ...
123
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
124

125
# Module-level parser instance and decorators
126
parser = TornadoParser()
127

128
def use_args(argmap, req=None, **kwargs):
129
    """Tornado-specific use_args decorator."""
130

131
def use_kwargs(argmap, req=None, **kwargs):
132
    """Tornado-specific use_kwargs decorator."""
133
```
134

135
### Pyramid Parser
136

137
Parser for Pyramid web framework with support for Pyramid Request objects.
138

139
```python { .api }
140
class PyramidParser(Parser[pyramid.request.Request]):
141
    """
142
    Parser for Pyramid framework.
143
    
144
    Integrates with Pyramid's request/response system and error handling.
145
    """
146
    def __init__(self, **kwargs): ...
147
    
148
    def load_json(self, req, schema): ...
149
    def load_querystring(self, req, schema): ...
150
    def load_form(self, req, schema): ...
151
    def load_headers(self, req, schema): ...
152
    def load_cookies(self, req, schema): ...
153
    def load_files(self, req, schema): ...
154
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
155

156
# Module-level parser instance and decorators
157
parser = PyramidParser()
158

159
def use_args(argmap, req=None, **kwargs):
160
    """Pyramid-specific use_args decorator."""
161

162
def use_kwargs(argmap, req=None, **kwargs):
163
    """Pyramid-specific use_kwargs decorator."""
164
```
165

166
### Falcon Parser
167

168
Parser for Falcon web framework with support for Falcon Request objects.
169

170
```python { .api }
171
class FalconParser(Parser[falcon.Request]):
172
    """
173
    Parser for Falcon framework.
174
    
175
    Handles Falcon's request structure and provides appropriate error responses.
176
    """
177
    def __init__(self, **kwargs): ...
178
    
179
    def load_json(self, req, schema): ...
180
    def load_querystring(self, req, schema): ...
181
    def load_form(self, req, schema): ...
182
    def load_headers(self, req, schema): ...
183
    def load_cookies(self, req, schema): ...
184
    def load_files(self, req, schema): ...
185
    def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
186

187
# Module-level parser instance and decorators
188
parser = FalconParser()
189

190
def use_args(argmap, req=None, **kwargs):
191
    """Falcon-specific use_args decorator."""
192

193
def use_kwargs(argmap, req=None, **kwargs):
194
    """Falcon-specific use_kwargs decorator."""
195
```
196

197
### aiohttp Parser (Async)
198

199
Parser for aiohttp web framework with full async/await support.
200

201
```python { .api }
202
class AIOHTTPParser(AsyncParser[aiohttp.web.Request]):
203
    """
204
    Parser for aiohttp framework with async support.
205
    
206
    Extends AsyncParser to provide async request parsing capabilities.
207
    All parsing operations are async-aware and integrate with aiohttp's async request handling.
208
    """
209
    def __init__(self, **kwargs): ...
210
    
211
    async def load_json(self, req, schema): ...
212
    def load_querystring(self, req, schema): ...
213
    async def load_form(self, req, schema): ...
214
    def load_headers(self, req, schema): ...
215
    def load_cookies(self, req, schema): ...
216
    def load_files(self, req, schema): ...
217
    async def load_json_or_form(self, req, schema): ...
218
    async def handle_error(self, error, req, schema, *, error_status_code, error_headers): ...
219

220
# Module-level parser instance and decorators
221
parser = AIOHTTPParser()
222

223
def use_args(argmap, req=None, **kwargs):
224
    """aiohttp-specific use_args decorator with async support."""
225

226
def use_kwargs(argmap, req=None, **kwargs):
227
    """aiohttp-specific use_kwargs decorator with async support."""
228
```
229

230
### Async Parser Base
231

232
Base class for async-aware parsers that support coroutine-based parsing.
233

234
```python { .api }
235
class AsyncParser(Parser[Request]):
236
    """
237
    Asynchronous variant of webargs.core.Parser.
238
    
239
    The parse method is redefined to be async and delegates to the async_parse method
240
    from the base Parser class. This provides a cleaner interface for async frameworks
241
    while maintaining compatibility with all the core parsing functionality.
242
    """
243
    async def parse(self, argmap, req=None, *, location=None, unknown=None, validate=None, error_status_code=None, error_headers=None):
244
        """
245
        Coroutine variant of webargs.core.Parser.parse.
246
        
247
        Receives the same arguments as webargs.core.Parser.parse but returns
248
        a coroutine that must be awaited.
249
        
250
        Args:
251
            argmap: Either a marshmallow.Schema, a dict of argname -> marshmallow.fields.Field pairs,
252
                   or a callable which accepts a request and returns a marshmallow.Schema
253
            req: The request object to parse
254
            location (str): Where on the request to load values
255
            unknown (str): A value to pass for unknown when calling the schema's load method
256
            validate: Validation function or list of validation functions
257
            error_status_code (int): Status code passed to error handler functions
258
            error_headers (dict): Headers passed to error handler functions
259
            
260
        Returns:
261
            Any: A dictionary of parsed arguments
262
        """
263
```
264

265
## Framework Integration Patterns
266

267
### Flask Integration
268

269
```python
270
from flask import Flask
271
from webargs import fields
272
from webargs.flaskparser import use_args, use_kwargs
273

274
app = Flask(__name__)
275

276
@app.route("/users", methods=["POST"])
277
@use_args({"name": fields.Str(required=True)})
278
def create_user(args):
279
    return {"message": f"Created user {args['name']}"}
280

281
@app.route("/users/<int:user_id>", methods=["PUT"]) 
282
@use_kwargs({"name": fields.Str(), "email": fields.Email()})
283
def update_user(user_id, name=None, email=None):
284
    return {"message": f"Updated user {user_id}"}
285
```
286

287
### Django Integration
288

289
```python
290
from django.http import JsonResponse
291
from webargs import fields
292
from webargs.djangoparser import use_args, use_kwargs
293

294
@use_args({"q": fields.Str(location="query")})
295
def search_view(request, args):
296
    query = args["q"]
297
    # Search logic here
298
    return JsonResponse({"results": []})
299

300
@use_kwargs({"name": fields.Str(), "age": fields.Int()})
301
def user_view(request, name=None, age=None):
302
    return JsonResponse({"name": name, "age": age})
303
```
304

305
### aiohttp Integration (Async)
306

307
```python
308
from aiohttp import web
309
from webargs import fields
310
from webargs.aiohttpparser import use_args, use_kwargs
311

312
@use_args({"name": fields.Str(required=True)})
313
async def create_user(request, args):
314
    name = args["name"]
315
    # Async database operations
316
    return web.json_response({"message": f"Created user {name}"})
317

318
@use_kwargs({"page": fields.Int(location="query", missing=1)})
319
async def list_users(request, page):
320
    # Async pagination logic
321
    return web.json_response({"page": page, "users": []})
322
```
323

324
### Custom Parser Creation
325

326
```python
327
from webargs.core import Parser
328

329
class CustomFrameworkParser(Parser):
330
    """Custom parser for a specific framework."""
331
    
332
    def load_json(self, req, schema):
333
        # Framework-specific JSON loading
334
        return req.get_json()
335
    
336
    def load_querystring(self, req, schema):
337
        # Framework-specific query parameter loading
338
        return self._makeproxy(req.args, schema)
339
    
340
    def handle_error(self, error, req, schema, *, error_status_code, error_headers):
341
        # Framework-specific error handling
342
        raise CustomFrameworkError(error.messages, error_status_code)
343

344
# Create parser instance and decorators
345
parser = CustomFrameworkParser()
346
use_args = parser.use_args
347
use_kwargs = parser.use_kwargs
348
```
349

350
## Error Handling Patterns
351

352
Each framework parser provides appropriate error handling for the target framework:
353

354
- **Flask**: Raises `werkzeug.exceptions.HTTPException` with error details
355
- **Django**: Returns `django.http.JsonResponse` with error information
356
- **aiohttp**: Returns `aiohttp.web.Response` with JSON error data
357
- **Tornado**: Raises `tornado.web.HTTPError` with structured error messages
358
- **Pyramid**: Raises `pyramid.httpexceptions.HTTPBadRequest` with error details
359
- **Falcon**: Sets response status and JSON error body on response object
360
- **Bottle**: Raises `bottle.HTTPError` with error information
361

362
## Types
363

364
```python { .api }
365
FlaskRequest = flask.Request
366
DjangoRequest = django.http.HttpRequest
367
BottleRequest = bottle.Request
368
TornadoRequest = tornado.httpserver.HTTPServerRequest
369
PyramidRequest = pyramid.request.Request
370
FalconRequest = falcon.Request
371
AIOHTTPRequest = aiohttp.web.Request
372
```