pyramid-marshmallow

pyramid-marshmallow is a simple Pyramid plugin that allows you to validate and marshal a JSON HTTP request or response using Marshmallow schemas. You can then leverage this to automatically generate an OpenAPI specification for your API.

Version 0.5 and greater requires Marshmallow 3.x. For Marshmallow 2.x, use version 0.4.

Basic usage

Install the project with pip install pyramid-marshmallow.

Activate it by adding config.include('pyramid_marshmallow') into your config function or adding pyramid.includes = pyramid_marshmallow into your ini file.

To validate incoming data, set validate to a Marshmallow schema in your view_config. The request body is parsed as JSON then passed through the schema's load function. You can access the processed data with request.data.

from marshmallow import Schema, String


class HelloSchema(Schema):
    name = String()


@view_config(
    context=Root,
    name='hello',
    request_method='post',
    validate=HelloSchema(),
)
def hello(context, request):
    return Response(body='Hello, {}'.format(
        request.data['name']
    ))

For GET requests, the URL parameters are passed into the schema. Value lists are not currently supported.

Setting marshal in your view_config will run the view output through marshmallow (i.e. Schema.dump) before going to the renderer. You probably will want to set the renderer to json.

@view_config(
    context=Root,
    name='hello',
    request_method='get',
    marshal=HelloSchema(),
    renderer='json',
)
def hello(context, request):
    name = fetch_name()
    return {
        'name': name,
    }

validate and marshal operate independently, so can be used separately or together.

As a convenience, you can pass in a dictionary to validate or marshal and pyramid-marshmallow will turn it into a schema for you.

@view_config(
    context=Root,
    name='hello',
    request_method='post',
    validate={
        'name': String(),
    },
)

You can also get a schema made from a dictionary by using Marshmallow's Schema.from_dict classmethod. This can be useful for Nested fields.

Error handling

pyramid-marshmallow passes through exceptions from marshmallow. So errors during validation will raise a marshmallow.exceptions.ValidationError exception. (Documentation)

You may want to attach a view to this exception to expose the error messages to the user.

@view_config(
    context=ValidationError,
    renderer='json',
)
def validation_error(context, request):
    request.response.status = 401  # HTTP Bad Request
    return {
        'errors': context.normalized_messages(),
    }

OpenAPI

By adding validation and marshalling to your views, we have the opportunity to utilize that data to generate documentation. pyramid-marshmallow includes an utility that uses apispec to generate an OpenAPI specification for your application.

First, you'll need to install some extra dependencies.

pip install pyramid-marshmallow[openapi]

You can generate your spec by calling the generate-spec command with your application as the first argument, formatted as [module]:[name].

generate-spec myproject:app

If you configure your application via an ini file (Paste), you can also use that.

generate-spec --ini development.ini

This will output the spec to stdout as JSON. You can set the --output flag to output the results to a file.

You can set --format yaml to output the spec as YAML instead or --format html to output the spec as an HTML file, powered by ReDoc.

By default, your spec will be titled "Untitled" and versioned "0.1.0". You can change this by setting openapi.title and openapi.version in your ini file.

Documenting Your API

Documentation will be autogenerated from the structure of your Pyramid app and your validate and marshal declarations. You can document schema fields by setting the description property.

class Hello(Schema):
    name = String(required=True, description='Your first and last name.')

The first line of a view callable's docstring will be used as the summary property. The following lines will be used for the description.

Documentation for the endpoint will be pulled from the view callable's docstring. The first line becomes the summary and the remaining lines become the description.

You can also a line with three hyphens followed by a YAML object. This will be merged with the auto-generated operation object and can be used to manually augment the spec.

@view_config(
    context=WidgetResource,
    method='post',
    validate=WidgetSchema(),
)
def create_widget(context, request):
    """
    Create new widget

    Creates a new widget with an attached plumbus.

    ---
    responses:
        201:
            description: Indicates the widget was successfully created.
    """
    widget.make()
    return HTTPCreated()

You can also pass a dictionary as the api_spec property to Configurator.add_view or @view_config, which will be merged with the spec in the same way. This can be advantageous if a single function services multiple views.

@view_config(
    context=WidgetResource,
    method='post',
    validate=WidgetSchema(),
    api_spec={
        'summary': 'Create widget',
    },
)
@view_config(
    context=WidgetResource,
    method='put',
    validate=WidgetSchema(),
    api_spec={
        'summary': 'Update widget',
    },
)
def create_widget(context, request):
    """
    Create/update new widget

    ---
    responses:
        201:
            description: Indicates the widget was successfully created.
    """
    widget.create_or_update()
    return HTTPCreated()

URL Traversal

If you're using Pyramid's URL traversal, the generated spec may be mostly empty. This is because pyramid-marshmallow has no way of knowing where in the resource tree a resource is. You can denote this by setting the __path__ property on each resource.

class Widget(Resource):
    __path__ = '/widget'

Views attached to this resource will then be added to the spec.

You can add parameters to your path via the __params__ property. You can also tag all attached views via __tag__. Once you define a tag in one resource, you can use it elsewhere by setting __tag__ to the tag name.

class Widget(Resource):
    __path__ = '/widget/{widgetId}'
    __params__ = [{
        'name': 'widgetId',
        'schema': {
            'type': 'integer',
        },
    }]
    __tag__ = {
        'name': 'widgets',
        'description': 'Endpoints for managing a widget.',
    }

Mergefile

You likely will wish to augment your API spec with a description, additional components, and more. This can be achieved with a mergefile. Write a YAML file with the parts of the spec you wish to augment and pass the filename as the --merge flag with generate-spec. You can also reference a package resource in the format [package]:[path]. The file will be loaded and merged into the generated spec. You can use the --merge flag multiple times to merge in multiple files. You can also add a merge file by adding the path to the openapi.merge setting in your Pyramid application. Multiple mergefiles can be separated with a comma.

Zones

It may be that not all endpoints are made available to all users. For example, you may have all endpoints available internally but only select ones available publicly. You would then want separate API docs for internal users versus external users. This can be achieved using zones.

Tag each endpoint by setting api_zone in Configuration.add_view or @view_config. By default, all endpoints regardless of zone will be added to the spec. Set the --zone flag in generate-spec to only put endpoints assigned to that zone in the spec.

Prior Art

pyramid-apispec allows you to augment view callable docstrings with OpenAPI definitions and can reference Marshmallow schemas with the apispec Marshmallow plugin. It does not support validating input and marshalling output. Schemas and routes must be manually declared.

Cornice supports validation with Marshmallow schemas, however only on Cornice resources, not arbitrary Pyramid endpoints. It does not support auto-generating OpenAPI documentation.