partial=True on schema issues non-unique warning

[mekanix]

The following code gives:

/usr/home/meka/.virtualenvs/rest/lib/python3.6/site-packages/apispec/ext/marshmallow/common.py:145: UserWarning: Multiple schemas resolved to the name Pet. The name has been modified. Either manually add each of the schemas with a different name or provide a custom schema_name_resolver.

If I remove partial=True, the warning goes away. In SwaggerUI, there are two schemas that corespond to PetSchema when partial is usedb.

import marshmallow as ma
from flask import Flask
from flask.views import MethodView
from flask_rest_api import Api, Blueprint, abort


class Pet:
    id = 1
    name = 'Cat'


class PetSchema(ma.Schema):
    id = ma.fields.Int(dump_only=True)
    name = ma.fields.String()

    class Meta:
        strict = True


app = Flask('My API')
app.config['OPENAPI_VERSION'] = '3.0.2'
api = Api(app)

blp = Blueprint('pets', 'pets')


@blp.route('/')
class Pets(MethodView):
    @blp.arguments(PetSchema, location='query')
    @blp.response(PetSchema(many=True))
    def get(self, args):
        """List pets"""
        return [Pet()]

    @blp.arguments(PetSchema)
    @blp.response(PetSchema, code=201)
    def post(self, new_data):
        """Add a new pet"""
        return Pet()


@blp.route('/<pet_id>')
class PetsById(MethodView):
    @blp.response(PetSchema)
    def get(self, pet_id):
        """Get pet by ID"""
        try:
            item = Pet()
        except ItemNotFoundError:
            abort(404, message='Item not found.')
        return item

    @blp.arguments(PetSchema(partial=True))
    @blp.response(PetSchema)
    def put(self, update_data, pet_id):
        """Update existing pet"""
        try:
            item = Pet()
        except ItemNotFoundError:
            abort(404, message='Item not found.')
        return item

    @blp.response(code=204)
    def delete(self, pet_id):
        """Delete pet"""
        pass


api.register_blueprint(blp)

if __name__ == '__main__':
    app.run()

[lafrech]

Duplicate of #444.

The warning says what it says. You have two schemas that resolve to the same name. apispec generates two different names so this is fine, but you may want to provide different names explicitly, so apispec issues a warning to let you know.

You can register the partial schema manually with another name:

spec.components.schema("PartialPet", schema=PetSchema(partial=True))

If you have the same issue with many schemas, consider creating a manual schema name resolver, for instance one that prepends "Partial" to schema names when partial is True.

[lafrech]

I used marshmallow-code/flask-smorest#38 (comment) as a base for the custom schema resolver, but I don't know how to check if partial is passed or not. I assume the same goes for exclude.

My bad. I thought the resolver received the schema instance, but it only gets the schema class, so you can't.

This leaves you with only the verbose manual method.

@Bangertm, I can't figure out the reason we pass the class to the resolver and not the instance. I suppose most case of schemas resolving to the same name will be instances of the same schema with different modifiers. Or am I missing something?

[Bangertm]

There's not a good reason to pass the class anymore, I'm afraid. When the schema name resolver functionality was initially implemented we were primarily using schema classes so that's what was passed in. When I refactored I kept that interface, but then when started taking modifiers into account we switched to primarily working with schema instances but I didn't change the interface for the name resolver.

So we could just switch to passing a schema instance to the schema name resolver, but in some cases users wanted the ability to override the way schema classes are resolved. So now what I'm thinking is that we should just pass the schema parameter from resolve_nested_schema directly to the name resolver. That parameter could be a schema class, schema instance, or a string that resolves to a schema class.

Then in our default implementation we can just call resolve_schema_cls on it. Uses that want to work with parameters can call resolve_schema_instance on it. And users who want to do something custom can do that.

I'll have some time tomorrow to put together a PR to illustrate what I'm thinking.

[lafrech]

Great, thanks!

This can be considered a breaking change (for a hypothetical user who would have implemented a resolver that expects classes only) but it is not a problem to bump the major version.