Migration to webargs

[vovanbo]

What you think about migration from reqparser to webargs? Flask-RESTful will be ready soon to rip out their reqparser and marshalling (see flask-restful/flask-restful#335).

Does it make sense?

[noirbizarre]

Yes it makes sense.

I'll be waiting for upstream work to advance and be merged.

Maybe I should open a webargs branch to prepare the migration and stay close to the upstream work in progress.

[noirbizarre]

I will probably add support for Webargs soon !

[croshchupkin]

The referenced flask-restful ticket also proposes to use marshmallow, does it not? As far as I've read the docs, marshmallow has many more features than webargs (besides retrieving data from several locations on the request) and looks more promising. Or did I accidentally miss something?

[noirbizarre]

Yes, in fact I/we can do both.

I'm thinking about dropping flask-restful.
It was a very good base to start, but now, it may be easier for me to only copy the code I'm depending on.
The hook and monkey-patch approach has some limits and introduce some complexity.

Dropping flask-restful doesn't mean API breakage, because I will still have to support their request parser, but it means I can let people choose their request parser (Webargs, Marshmallow...)

I'm very open to discussion, feedback or any advice on this topic.

[sloria]

To clarify: webargs is used for declaratively defining request arguments (e.g. query params, JSON body) and marshmallow is used for deserialization and serialization. webargs knows how to pull values from a framework's request objects; marshmallow does not. While there is some overlap in their functionality (both can do validation), they are meant to be used together.

+1 to the direction @noirbizarre is proposing. I've done very early work on a pluggable API doc generator (marshmallow-code/apispec#1). Would be open to collaborating.

[frol]

I would like to add here that webargs moved on using marshmallow fields under the hood (marshmallow-code/webargs#61).

I have also successfuly patched Flask-RESTplus to handle marshmallow schemas and webargs parameters (using flask-marshmallow, webargs, and apispec modules together). I may try to make a PR, but I'm not sure whether it should be done before Flask-RESTplus drops Flask-RESTful dependency.

Currently, my API looks like this:

@namespace.route('/')
@errors.DefaultHTTPError(code=422, description="Arguments are invalid")
@errors.AuthHTTPError()
class Users(Resource):
    """
    Manipulations with users.
    """

    @auth.login_required(scopes=['users:read'])
    @permissions.AdminRolePermission()
    @parameters.PaginationParameters()
    @schemas.BaseUserSchema(many=True)
    def get(self, args):
        """
        List of users.

        Returns a list of users starting from ``offset`` limited by ``limit``
        parameter.
        """
        return User.query.all()[args.offset: args.offset + args.limit]

Instead of

@namespace.route('/')
@api.doc(
    responses={
        401: ("Auth error", AUTH_HTTP_ERROR_MODEL),
        400: ("Arguments are invalid", INVALID_ARGS_HTTP_ERROR_MODEL),
    }
)
class Users(Resource):
    """
    Manipulations with users.
    """

    @auth.login_required(scopes=['users:read'])
    @permissions.AdminRolePermission()
    @api.doc(parser=pagination_arguments_parser)
    @api.marshal_with(BASE_USER_DEFINITION)
    def get(self):
        """
        List of users.

        Returns a list of users starting from ``offset`` limited by ``limit``
        parameter.
        """
        args = pagination_arguments_parser.parse()
        return User.query.all()[args.offset: args.offset + args.limit]

For me, the code became cleaner and also things like AUTH_HTTP_ERROR_MODEL and pagination_arguments_parser became classes, so it will be easier to maintain them.

[noirbizarre]

Hum, I'm really interested in.
I suggest you wait for flask-restful removal.
There might be an adaptter pattern to keep the legacy flask-restful request parser in the hood but allowing to provide different adapter for different frameworks, Marshmallow being one of them.

Until then don't hesitate to publish the code somewhere, it can be a good source of inspiration.

[frol]

@noirbizarre Here is my RESTful API example server using Flask-RESTplus with marshmallow, webargs, and JSON Editor and Password Flow patches to Swagger-UI: https://github.com/frol/flask-restplus-server-example

Notice that I have patched Flask-RESTplus right there (find flask_restplus_patched folder).

It still requires some polishing, so I will notify you once I am completely satisfied with its design. Actually, there is only one thing that is bothering me: I don't like that Schema (in flask_restplus_patched/model.py), Parameters (in flask_restplus_patched/parameters.py), and Permission (in app/users/permissions.py) handle api instance inside, it has to be done either by api instance call (like it is for parser - @api.doc(parser=parser_instance)), or something else (because I don't see a way api instance can handle Permission instance if it is not supported directly).

[noirbizarre]

Thansk @frol for the sample project.

I will take a closer look for the 0.9 release.