Update docs and bump dev version

- Update changelog
- Add @DamianHeard to AUTHORS
- Add Schema Factories section to Quickstart
- Document `use_args_with` pattern from
  #73 (comment)

Author: sloria

AUTHORS.rst

@@ -20,3 +20,4 @@ Contributors (chronological)
 * Rory Hart <https://github.com/hartror>
 * Jace Browning <https://github.com/jacebrowning>
 * @marcellarius <https://github.com/marcellarius>
+* Damian Heard <https://github.com/DamianHeard>

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 ---------
 
+1.1.0 (unreleased)
+******************
+
+Features:
+
+* ``Parser.parse``, ``Parser.use_args`` and ``Parser.use_kwargs`` can take a Schema factory as the first argument (:issue:`73`). Thanks :user:`DamianHeard` for the suggestion and the PR.
+
 1.0.0 (2015-10-19)
 ******************
 

docs/quickstart.rst

@@ -214,8 +214,8 @@ Nesting Fields
             })
         }
 
-Marshmallow Integration
------------------------
+Advanced: Marshmallow Integration
+---------------------------------
 
 When you need more flexibility in defining input schemas, you can pass a marshmallow `Schema <marshmallow.Schema>` instead of a dictionary to `Parser.parse <webargs.core.Parser.parse>`, `Parser.use_args <webargs.core.Parser.use_args>`, and `Parser.use_kwargs <webargs.core.Parser.use_kwargs>`.
 
@@ -254,6 +254,81 @@ When you need more flexibility in defining input schemas, you can pass a marshma
 .. note::
     You should always set ``strict=True`` (either as a ``class Meta`` option or in the Schema's constructor) when passing a schema to webargs. This will ensure that the parser's error handler is invoked when expected.
 
+
+Advanced: Schema Factories
+--------------------------
+
+If you need to parametrize a schema based on a given request, you can use a "Schema factory": a callable that receives the current `request` and returns a `marshmallow.Schema` instance.
+
+Consider the following use cases:
+
+- Handle partial updates for PATCH requests using marshmallow's `partial loading <https://marshmallow.readthedocs.org/en/latest/quickstart.html#partial-loading>`_ API.
+- Filtering via a query parameter by passing ``only`` to the Schema.
+
+.. code-block:: python
+
+    from marshmallow import Schema, fields
+    from webargs.flaskparser import use_args
+
+    class UserSchema(Schema):
+        id = fields.Int(dump_only=True)
+        username = fields.Str(required=True)
+        password = fields.Str(load_only=True)
+        first_name = fields.Str(missing='')
+        last_name = fields.Str(missing='')
+        date_registered = fields.DateTime(dump_only=True)
+
+        class Meta:
+            strict = True
+
+    def make_user_schema(request):
+        # Filter based on 'fields' query parameter
+        only = request.args.get('fields', None)
+        # Respect partial updates for PATCH requests
+        partial = request.method == 'PUT'
+        # Add current request to the schema's context
+        return UserSchema(only=only, partial=partial, context={'request': request})
+
+    # Pass the factory to .parse, .use_args, or .use_kwargs
+    @use_args(make_user_schema):
+    def profile_view(args):
+        # ...
+
+
+Reducing Boilerplate
+++++++++++++++++++++
+
+We can reduce boilerplate and improve [re]usability with a simple helper function:
+
+.. code-block:: python
+
+    from webargs.flaskparser import use_args
+
+    def use_args_with(schema_cls, schema_kwargs=None, **kwargs):
+        schema_kwargs = schema_kwargs or {}
+        def factory(request):
+            # Filter based on 'fields' query parameter
+            only = request.args.get('fields', None)
+            # Respect partial updates for PATCH requests
+            partial = request.method == 'PUT'
+            # Add current request to the schema's context
+            # and ensure we're always using strict mode
+            return schema_cls(
+                only=only, partial=partial, strict=True,
+                context={'request': request}, **schema_kwargs
+            )
+        return use_args(factory, **kwargs)
+
+
+Now we can attach input schemas to our view functions like so:
+
+.. code-block:: python
+
+    @use_args_with(UserSchema)
+    def profile_view(args):
+        # ...
+
+
 Next Steps
 ----------
 

webargs/__init__.py

@@ -6,7 +6,7 @@
 from webargs.core import argmap2schema, WebargsError, ValidationError
 from webargs import fields
 
-__version__ = '1.0.0'
+__version__ = '1.1.0.dev0'
 __author__ = 'Steven Loria'
 __license__ = 'MIT'
 

webargs/core.py

@@ -267,7 +267,8 @@ def _validate_arguments(self, data, validators):
     def _get_schema(self, argmap, req):
         """Return a `marshmallow.Schema` for the given argmap and request.
 
-        :param argmap: Either a `marshmallow.Schema`, `dict`, or callable that returns
+        :param argmap: Either a `marshmallow.Schema`, `dict`
+            of argname -> `marshmallow.fields.Field` pairs, or a callable that returns
             a `marshmallow.Schema` instance.
         :param req: The request object being parsed.
         :rtype: marshmallow.Schema
@@ -283,9 +284,9 @@ def _get_schema(self, argmap, req):
     def parse(self, argmap, req=None, locations=None, validate=None, force_all=False):
         """Main request parsing method.
 
-        :param argmap: Either a `marshmallow.Schema`, `dict`
-            of argname -> `marshmallow.fields.Field` pairs, or a callable that returns
-            a `marshmallow.Schema` instance.
+        :param argmap: Either a `marshmallow.Schema`, a `dict`
+            of argname -> `marshmallow.fields.Field` pairs, or a callable
+            which accepts a request and returns a `marshmallow.Schema`.
         :param req: The request object to parse.
         :param tuple locations: Where on the request to search for values.
             Can include one or more of ``('json', 'querystring', 'form',
@@ -350,7 +351,7 @@ def use_args(self, argmap, req=None, locations=None, as_kwargs=False, validate=N
             def greet(args):
                 return 'Hello ' + args['name']
 
-        :param dict argmap: Either a `marshmallow.Schema`, a `dict`
+        :param argmap: Either a `marshmallow.Schema`, a `dict`
             of argname -> `marshmallow.fields.Field` pairs, or a callable
             which accepts a request and returns a `marshmallow.Schema`.
         :param tuple locations: Where on the request to search for values.