1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
=======
webargs
=======
Release v\ |version|. (:doc:`Changelog <changelog>`)
webargs is a Python library for parsing and validating HTTP request objects, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, Falcon, and aiohttp.
Upgrading from an older version?
--------------------------------
See the :doc:`Upgrading to Newer Releases <upgrading>` page for notes on getting your code up-to-date with the latest version.
Usage and Simple Examples
-------------------------
.. code-block:: python
from flask import Flask
from webargs import fields
from webargs.flaskparser import use_args
app = Flask(__name__)
@app.route("/")
@use_args({"name": fields.Str(required=True)}, location="query")
def index(args):
return "Hello " + args["name"]
if __name__ == "__main__":
app.run()
# curl http://localhost:5000/\?name\='World'
# Hello World
By default Webargs will automatically parse JSON request bodies. But it also
has support for:
**Query Parameters**
::
$ curl http://localhost:5000/\?name\='Freddie'
Hello Freddie
# pass location="query" to use_args
**Form Data**
::
$ curl -d 'name=Brian' http://localhost:5000/
Hello Brian
# pass location="form" to use_args
**JSON Data**
::
$ curl -X POST -H "Content-Type: application/json" -d '{"name":"Roger"}' http://localhost:5000/
Hello Roger
# pass location="json" (or omit location) to use_args
and, optionally:
- Headers
- Cookies
- Files
- Paths
Why Use It
----------
* **Simple, declarative syntax**. Define your arguments as a mapping rather than imperatively pulling values off of request objects.
* **Code reusability**. If you have multiple views that have the same request parameters, you only need to define your parameters once. You can also reuse validation and pre-processing routines.
* **Self-documentation**. Webargs makes it easy to understand the expected arguments and their types for your view functions.
* **Automatic documentation**. The metadata that webargs provides can serve as an aid for automatically generating API documentation.
* **Cross-framework compatibility**. Webargs provides a consistent request-parsing interface that will work across many Python web frameworks.
* **marshmallow integration**. Webargs uses `marshmallow <https://marshmallow.readthedocs.io/en/latest/>`_ under the hood. When you need more flexibility than dictionaries, you can use marshmallow `Schemas <marshmallow.Schema>` to define your request arguments.
Get It Now
----------
::
pip install -U webargs
Ready to get started? Go on to the :doc:`Quickstart tutorial <quickstart>` or check out some `examples <https://github.com/marshmallow-code/webargs/tree/dev/examples>`_.
User Guide
----------
.. toctree::
:maxdepth: 2
install
quickstart
advanced
framework_support
ecosystem
API Reference
-------------
.. toctree::
:maxdepth: 2
api
Project Info
------------
.. toctree::
:maxdepth: 1
license
changelog
upgrading
authors
contributing
|
