flask-smorest Documentation

When input data contains fields not defined in the marshmallow Schema, you can control the behavior using the unknown attribute.

1. Via Schema Meta: Set unknown to RAISE, EXCLUDE, or INCLUDE in the Schema.Meta class.
2. Via FlaskParser customization: For locations like query, headers, cookies, and files, flask-smorest defaults to unknown=EXCLUDE. To change this globally for specific locations, subclass webargs.flaskparser.FlaskParser and assign it to your Blueprint.ARGUMENTS_PARSER.

Note: For locations that support nested schemas (json, form, json_or_form), it is recommended to set the unknown behavior in the Schema.Meta class, as the FlaskParser override only applies to the top-level schema and does not propagate to nested ones.

import marshmallow as ma
from webargs.flaskparser import FlaskParser
from flask_smorest import Blueprint

class MyFlaskParser(FlaskParser):
    DEFAULT_UNKNOWN_BY_LOCATION = {
        "query": ma.RAISE,
    }

class MyBlueprint(Blueprint):
    ARGUMENTS_PARSER = MyFlaskParser()

When you want the view function to be responsible for selecting specific elements (e.g., using LIMIT and OFFSET in a database query), use the 'Pagination in View Function' mode.

To implement this:

1. Decorate the view method with @blp.paginate().
2. Accept a pagination_parameters argument in your view method (of type PaginationParameters).
3. Set the item_count attribute on the pagination_parameters object to the total number of available items.
4. Use the first_item and last_item attributes from pagination_parameters to slice your data source.

@blp.route("/")
class Pets(MethodView):
    @blp.response(200, PetSchema(many=True))
    @blp.paginate()
    def get(self, pagination_parameters):
        # Set the total count of items available
        pagination_parameters.item_count = Pet.size
        # Return only the slice requested by the client
        return Pet.get_elements(
            first_item=pagination_parameters.first_item,
            last_item=pagination_parameters.last_item,
        )

To set up a flask-smorest API, follow these steps:

1. Initialize the API: Instantiate the Api class with your Flask app and configure API metadata using app.config.
2. Define Schemas: Create Marshmallow schemas for your data models and for validating query arguments.
3. Create a Blueprint: Use Blueprint to define a logical grouping of routes, including a url_prefix and description.
4. Implement MethodViews: Use @blp.arguments to handle request deserialization and @blp.response to handle response serialization.
5. Handle Errors: Use the abort function to return errors, passing a status code and a message (which is passed to the error handler).
6. Register the Blueprint: Register your blueprint with the Api instance using api.register_blueprint(blp).

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

# 1. Initialize API
app = Flask(__name__)
app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "v1"
app.config["OPENAPI_VERSION"] = "3.0.2"
api = Api(app)

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

class PetQueryArgsSchema(ma.Schema):
    name = ma.fields.String()

# 3. Create Blueprint
blp = Blueprint("pets", "pets", url_prefix="/pets", description="Operations on pets")

# 4. Implement MethodViews
@blp.route("/")
class Pets(MethodView):
    @blp.arguments(PetQueryArgsSchema, location="query")
    @blp.response(200, PetSchema(many=True))
    def get(self, args):
        """List pets"""
        return Pet.get(filters=args)

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

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

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

    @blp.response(204)
    def delete(self, pet_id):
        """Delete pet"""
        try:
            Pet.delete(pet_id)
        except ItemNotFoundError:
            abort(404, message="Item not found.")

# 6. Register Blueprint
api.register_blueprint(blp)