Skip to main content

Validate request and response data with Marshmallow and optionally generate an OpenAPI spec.

Project description

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.

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 the pyramid_marshmallow.make_schema function. This can be useful for Nested fields.

Error handling

If the validation fails, a pyramid_marshmallow.ValidationError is raised. The errors property of the exception contains a dictionary of error messages, just like the Schema.load method returns.

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.errors,
    }

A failure during marshalling will result in a pyramid_marshmallow.MarshalError which behaves in the same manner. It's usually less useful to attach a view to that exception, since marshalling errors are usually not encountered during standard operation.

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]

Now you can generate your spec by simply passing in an ini file. pyramid-marshmallow needs to run your application in order to inspect it, so the ini file should contain all the necessary configuration to do so.

generate-spec 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 zip to output a zip file containing the spec and Swagger UI, a web interface for viewing the spec.

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.

Additional Documentation

To add additional documentation to schema fields, you can set the description property.

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

Documentation for the endpoint will be pulled from the view callable's docstring.

You can also augment the spec by adding a line of three hyphens followed by YAML. The YAML will be parsed and merged into to the endpoint's spec. This can be useful for documenting endpoints that cannot be validated or marshalled, such as endpoints that return an empty body.

@view_config(
    context=WidgetResource,
    method='post',
    validate=WidgetSchema(),
)
def create_widget(context, request):
    """
    Create a new widget.
    ---
    responses:
        201:
            description: Indicates the widget was successfully created.
    """
    create_widget()
    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.',
    }

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyramid-marshmallow-0.4.1.tar.gz (2.8 MB view hashes)

Uploaded Source

Built Distribution

pyramid_marshmallow-0.4.1-py3-none-any.whl (2.8 MB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page