Update docs and examples

- Add Falcon section in Framework Support page
- Use webargs.validate in examples
- Add logging in FalconParser.handle_error

Author: sloria

README.rst

@@ -10,7 +10,7 @@ webargs
 
 Homepage: https://webargs.readthedocs.org/
 
-webargs is a Python library for parsing HTTP request arguments, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, and webapp2.
+webargs is a Python library for parsing HTTP request arguments, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, webapp2, and Falcon.
 
 .. code-block:: python
 

docs/api.rst

@@ -14,42 +14,48 @@ webargs.fields
 --------------
 
 .. automodule:: webargs.fields
-    :members: Nested
+    :members: Nested, DelimitedList
 
 webargs.flaskparser
 -------------------
 
 .. automodule:: webargs.flaskparser
-    :inherited-members:
+    :members:
 
 webargs.djangoparser
 --------------------
 
 .. automodule:: webargs.djangoparser
-    :inherited-members:
+    :members:
 
 webargs.bottleparser
 --------------------
 
 .. automodule:: webargs.bottleparser
-    :inherited-members:
+    :members:
 
 webargs.tornadoparser
 ---------------------
 
 .. automodule:: webargs.tornadoparser
-    :inherited-members:
+    :members:
 
 webargs.pyramidparser
 ---------------------
 
 .. automodule:: webargs.pyramidparser
-    :inherited-members:
+    :members:
 
 
 webargs.webapp2parser
 ---------------------
 
 .. automodule:: webargs.webapp2parser
-    :inherited-members:
+    :members:
+
+
+webargs.falconparser
+---------------------
 
+.. automodule:: webargs.falconparser
+    :members:

docs/framework_support.rst

@@ -248,3 +248,59 @@ The `PyramidParser` supports parsing values from a request's matchdict.
     @parser.use_args({'mymatch': fields.Int()}, locations=('matchdict',))
     def matched(request, args):
         return Response('The value for mymatch is {}'.format(args['mymatch'])))
+
+Falcon
+------
+
+Falcon support is available via the :mod:`webargs.falconparser` module.
+
+Decorator Usage
++++++++++++++++
+
+When using the :meth:`use_args <webargs.falconparser.FalconParser.use_args>` decorator on a resource method, the arguments dictionary will be positioned as the first argument after ``self``.
+
+.. code-block:: python
+
+    import falcon
+    from webargs import fields
+    from webargs.falconparser import use_args
+
+    class BlogResource:
+        request_args = {
+            'title': fields.Str(required=True)
+        }
+
+        @use_args(request_args)
+        def on_post(self, args, req, resp, post_id):
+            content = args['title']
+            # ...
+
+    api = application = falcon.API()
+    api.add_route('/blogs/{post_id}')
+
+As with the other parser modules, :meth:`use_kwargs <webargs.falconparser.FalconParser.use_kwargs>` will add keyword arguments to your resource methods.
+
+Hook Usage
+++++++++++
+
+You can easily implement hooks by using `parser.parse <webargs.falconparser.FalconParser.parse>` directly.
+
+.. code-block:: python
+
+    import falcon
+    from webargs import fields
+    from webargs.falconparser import parser
+
+    def add_args(argmap, **kwargs):
+        def hook(req, resp, params):
+            parsed_args = parser.parse(argmap, req=req, **kwargs)
+            req.context['args'] = parsed_args
+        return hook
+
+    @falcon.before(add_args({'page': fields.Int(location='query')}))
+    class AuthorResource:
+
+        def on_get(self, req, resp):
+            args = req.context['args']
+            author_name = args.get('page')
+            # ...

docs/index.rst

@@ -11,7 +11,7 @@ webargs
 
 Release v\ |version|. (:ref:`Changelog <changelog>`)
 
-**webargs** is a Python library for parsing HTTP request arguments, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, and Pyramid.
+**webargs** is a Python library for parsing HTTP request arguments, with built-in support for popular web frameworks, including Flask, Django, Bottle, Tornado, Pyramid, webapp2, and Falcon.
 
 
 .. code-block:: python

examples/__init__.py

@@ -16,7 +16,7 @@
 import json
 
 from bottle import route, run, error, response
-from webargs import fields, ValidationError
+from webargs import fields, validate
 from webargs.bottleparser import use_args, use_kwargs
 
 
@@ -40,14 +40,10 @@ def add(x, y):
     """An addition endpoint."""
     return {'result': x + y}
 
-def validate_unit(val):
-    if val not in ['minutes', 'days']:
-        raise ValidationError("Unit must be either 'minutes' or 'days'.")
-
 dateadd_args = {
     'value': fields.DateTime(required=False),
-    'addend': fields.Int(required=True, validate=lambda val: val >= 0),
-    'unit': fields.Str(validate=validate_unit)
+    'addend': fields.Int(required=True, validate=validate.Range(min=1)),
+    'unit': fields.Str(missing='days', validate=validate.OneOf(['minutes', 'days']))
 }
 @route('/dateadd', method='POST')
 @use_kwargs(dateadd_args)

examples/bottle_example.py

@@ -0,0 +1,95 @@
+"""A simple number and datetime addition JSON API.
+Demonstrates different strategies for parsing arguments
+with the FalconParser.
+
+Run the app:
+
+    $ pip install gunicorn
+    $ gunicorn examples.falcon_example:app
+
+Try the following with httpie (a cURL-like utility, http://httpie.org):
+
+    $ pip install httpie
+    $ http GET :8000/
+    $ http GET :8000/ name==Ada
+    $ http POST :8000/add x=40 y=2
+    $ http POST :8000/dateadd value=1973-04-10 addend=63
+    $ http POST :8000/dateadd value=2014-10-23 addend=525600 unit=minutes
+"""
+import datetime as dt
+try:
+    import simplejson as json
+except ImportError:
+    import json
+
+import falcon
+from webargs import fields, validate
+from webargs.falconparser import use_args, use_kwargs, parser
+
+### Middleware and hooks ###
+
+class JSONTranslator(object):
+    def process_response(self, req, resp, resource):
+        if 'result' not in req.context:
+            return
+        resp.body = json.dumps(req.context['result'])
+
+
+def add_args(argmap, **kwargs):
+    def hook(req, resp, params):
+        req.context['args'] = parser.parse(argmap, req=req, **kwargs)
+    return hook
+
+### Resources ###
+
+class HelloResource(object):
+    """A welcome page."""
+
+    hello_args = {
+        'name': fields.Str(missing='Friend', location='query')
+    }
+
+    @use_args(hello_args)
+    def on_get(self, args, req, resp):
+        req.context['result'] = {'message': 'Welcome, {}!'.format(args['name'])}
+
+class AdderResource(object):
+    """An addition endpoint."""
+
+    adder_args = {
+        'x': fields.Float(required=True),
+        'y': fields.Float(required=True),
+    }
+
+    @use_kwargs(adder_args)
+    def on_post(self, req, resp, x, y):
+        req.context['result'] = {'result': x + y}
+
+
+class DateAddResource(object):
+    """A datetime adder endpoint."""
+
+    dateadd_args = {
+        'value': fields.DateTime(required=False),
+        'addend': fields.Int(required=True, validate=validate.Range(min=1)),
+        'unit': fields.Str(missing='days', validate=validate.OneOf(['minutes', 'days']))
+    }
+
+    @falcon.before(add_args(dateadd_args))
+    def on_post(self, req, resp):
+        """A datetime adder endpoint."""
+        args = req.context['args']
+        value = args['value'] or dt.datetime.utcnow()
+        if args['unit'] == 'minutes':
+            delta = dt.timedelta(minutes=args['addend'])
+        else:
+            delta = dt.timedelta(days=args['addend'])
+        result = value + delta
+        req.context['result'] = {'result': result.isoformat()}
+
+app = falcon.API(middleware=[
+    JSONTranslator()
+])
+app.add_route('/', HelloResource())
+app.add_route('/add', AdderResource())
+app.add_route('/dateadd', DateAddResource())

examples/falcon_example.py

@@ -15,7 +15,7 @@
 import datetime as dt
 
 from flask import Flask, jsonify
-from webargs import fields, ValidationError
+from webargs import fields, validate
 from webargs.flaskparser import use_args, use_kwargs
 
 app = Flask(__name__)
@@ -40,14 +40,10 @@ def add(x, y):
     """An addition endpoint."""
     return jsonify({'result': x + y})
 
-def validate_unit(val):
-    if val not in ['minutes', 'days']:
-        raise ValidationError("Unit must be either 'minutes' or 'days'.")
-
 dateadd_args = {
     'value': fields.DateTime(required=False),
-    'addend': fields.Int(required=True, validate=lambda val: val >= 0),
-    'unit': fields.Str(validate=validate_unit)
+    'addend': fields.Int(required=True, validate=validate.Range(min=1)),
+    'unit': fields.Str(missing='days', validate=validate.OneOf(['minutes', 'days']))
 }
 @app.route('/dateadd', methods=['POST'])
 @use_kwargs(dateadd_args)

examples/flask_example.py

@@ -18,7 +18,7 @@
 from flask import Flask
 from flask.ext import restful
 
-from webargs import fields, ValidationError
+from webargs import fields, validate
 from webargs.flaskparser import use_args, use_kwargs, parser
 
 app = Flask(__name__)
@@ -50,16 +50,12 @@ def post(self, x, y):
         """An addition endpoint."""
         return {'result': x + y}
 
-def validate_unit(val):
-    if val not in ['minutes', 'days']:
-        raise ValidationError("Unit must be either 'minutes' or 'days'.")
-
 class DateAddResource(restful.Resource):
 
     dateadd_args = {
         'value': fields.DateTime(required=False),
-        'addend': fields.Int(required=True, validate=lambda val: val >= 0),
-        'unit': fields.Str(validate=validate_unit)
+        'addend': fields.Int(required=True, validate=validate.Range(min=1)),
+        'unit': fields.Str(missing='days', validate=validate.OneOf(['minutes', 'days']))
     }
 
     @use_kwargs(dateadd_args)

examples/flaskrestful_example.py

@@ -16,7 +16,7 @@
 
 import tornado.ioloop
 from tornado.web import RequestHandler
-from webargs import fields, ValidationError
+from webargs import fields, validate
 from webargs.tornadoparser import use_args, use_kwargs
 
 
@@ -57,17 +57,13 @@ def post(self, x, y):
         self.write({'result': x + y})
 
 
-def validate_unit(val):
-    if val not in ['minutes', 'days']:
-        raise ValidationError("Unit must be either 'minutes' or 'days'.")
-
 class DateAddHandler(BaseRequestHandler):
     """A datetime adder endpoint."""
 
     dateadd_args = {
         'value': fields.DateTime(required=False),
-        'addend': fields.Int(required=True, validate=lambda val: val >= 0),
-        'unit': fields.Str(validate=validate_unit)
+        'addend': fields.Int(required=True, validate=validate.Range(min=1)),
+        'unit': fields.Str(missing='days', validate=validate.OneOf(['minutes', 'days']))
     }
 
     @use_kwargs(dateadd_args)

examples/tornado_example.py

@@ -8,6 +8,11 @@
 from webargs import fields
 from webargs.falconparser import parser, use_args, use_kwargs
 
+def use_args_hook(args, context_key='args', **kwargs):
+    def hook(req, resp, params):
+        parsed_args = parser.parse(args, req=req, **kwargs)
+        req.context[context_key] = parsed_args
+    return hook
 
 @pytest.fixture()
 def api():
@@ -56,10 +61,17 @@ class AlwaysErrorResource(object):
         def on_get(self, req, resp):
             parser.parse(self.args, req=req)
 
+    @falcon.before(use_args_hook(hello_args))
+    class HookResource(object):
+
+        def on_get(self, req, resp):
+            resp.body(req.context['args'])
+
     api_.add_route('/parse', ParseResource())
     api_.add_route('/use_args', UseArgsResource())
     api_.add_route('/use_args_with_param/{_id}', UseArgsWithParamResource())
     api_.add_route('/use_kwargs', UseKwargsResource())
+    api_.add_route('/hook', UseKwargsResource())
     api_.add_route('/error', AlwaysErrorResource())
 
     return api_
@@ -120,3 +132,9 @@ class TestUseKwargsResource:
 
     def test_parse_querystring(self, testapp):
         assert testapp.get(self.url + '?name=Fred').json == {'name': 'Fred'}
+
+class TestHookResource:
+    url = '/hook'
+
+    def test_parse_querystring(self, testapp):
+        assert testapp.get(self.url + '?name=Fred').json == {'name': 'Fred'}

tests/test_falconparser.py

@@ -18,7 +18,8 @@
 from tornado.testing import AsyncHTTPTestCase
 
 from webargs import fields, missing, ValidationError
-from webargs.tornadoparser import parser, use_args, use_kwargs, parse_json, get_value
+from webargs.tornadoparser import parser, use_args, use_kwargs, get_value
+from webargs.core import parse_json
 
 name = 'name'
 value = 'value'

tests/test_tornadoparser.py

@@ -85,6 +85,7 @@ def parse_files(self, req, name, field):
 
     def handle_error(self, error):
         """Handles errors during parsing."""
+        logger.error(error)
         raise HTTPError(HTTP_422, errors=error.messages)
 
 parser = FalconParser()