API Docs

Resources

Resource view.

class flask_resources.resources.Resource(config)

Resource interface.

A resource is a factory for creating Flask Blueprint that’s parameterized via a config.

Initialize the base resource.

as_blueprint(**options)

Create the blueprint with all views and error handlers.

The method delegates to create_blueprint(), create_url_rules() and create_error_handlers() so usually you don’t have to overwrite this method.

create_blueprint(**options)

Create the blueprint.

Override this function to customize the creation of the Blueprint object itself.

create_error_handlers()

Create all error handlers for this resource.

This function should return a dictionary that maps an exception or HTTP response code to and error handler function. By default it merges error handlers defined on the resource itself with error handlers defined in the config. The error handlers in the config takes precedence over the resource defined error handlers.

The error handlers are registered on the blueprint using the Blueprint.register_error_handler().

create_url_rules()

Create all the blueprint URL rules for this resource.

The URL rules are registered on the blueprint using the Blueprint.add_url_rule().

decorators = [<function with_content_negotiation.<locals>.decorator>]

Decorators applied to all view functions.

By default, the resource request context and content negotiation is enabled. Provide an empty list to disable them.

error_handlers = {}

Mapping of exceptions or HTTP codes to error handler functions.

By default this mapping is merged with the error handlers mapping defined in the config.

class flask_resources.resources.ResourceConfig

Configuration for a resource.

This object is used for dependency injection in a resource.

blueprint_name = None

Name of the blueprint being created (used e.g. for prefix endpoint name).

default_accept_mimetype = 'application/json'

The default Accept MIME type if not defined by the request. Set to None, to require an Accept header.

default_content_type = 'application/json'

The default content type used to select the default request_body_parser. Set to None to require a Content-Type header.

error_handlers = {}

A mapping of exception or HTTP status code to error handler functions.

request_body_parsers = {'application/json': <flask_resources.parsers.body.RequestBodyParser object>}

Request body parser (i.e. request.data).

response_handlers = {'application/json': <flask_resources.responses.ResponseHandler object>}

Mapping of Accept MIME types to response handlers.

url_prefix = None

The URL prefix for the blueprint (all URL rules will be prefixed with this value)

flask_resources.resources.route(method, rule, view_meth, endpoint=None, rule_options=None, apply_decorators=True)

Create a route.

Use this method in create_url_rules() to build your list of rules.

The view_method parameter should be a bound method (e.g. self.myview).

Parameters

• method – The HTTP method for this URL rule.

• rule – A URL rule.

• view_meth – The view method (a bound method) for this URL rule.

• endpoint – The name of the endpoint. By default the name is taken from the method name.

• rule_options – A dictionary of extra options passed to Blueprint.add_url_rule.

• apply_decorators – Apply the decorators defined by the resource. Defaults to True. This allows you to selective disable decorators which are normally applied to all view methods.

Context

Resource request context.

The purpose of the resource request context is similar to the Flask request context. The main difference is it serves as a state object that can hold validated request data as well as the result of e.g. content negotiation.

The resource request context is used by default, and when it is used it consumes all the view arguments. These can either be retrieved via a request parser (preferably), or accessing request.view_args. The goal of this is to ensure that the view function access only validated data.

class flask_resources.context.ResourceRequestCtx(config)

Context manager for the resource context.

The resource request context encodes information about the currently executing request for a given resource, such as:

• The mimetype selected by the content negotiation.

• The content type of the request payload

Initialize the resource context.

update(values)

Update the context fields present in the received dictionary values.

Content negotiation and response handling

Response module.

class flask_resources.responses.ResponseHandler(serializer, headers=None)

Response handler which delegates to the a serializer.

Example usage:

def obj_headers(obj_or_list, code, many=False):
    return {'etag': ... }

class Config(ResourceConfig):
    response_handlers = {
        "application/json": ResponseHandler(
            JSONSerializer(), headers=obj_headers)
    }

Constructor.

make_headers(obj_or_list, code, many=False)

Builds the headers fo the response.

make_response(obj_or_list, code, many=False)

Builds a response for one object.

flask_resources.responses.response_handler(many=False)

Decorator for using the response handler to create the HTTP response.

The response handler works in conjunction with with_content_negotiation() which is responsible for selecting the correct response handler based on the content negotiation.

@response_handler()
def read(self):
    return obj, 200

@response_handler(many=True)
def search(self):
    return [obj], 200

Content negotiation API.

class flask_resources.content_negotiation.ContentNegotiator

Content negotiation API.

Implements a procedure for selecting a mimetype best matching what the client is requesting.

classmethod match(mimetypes, accept_mimetypes, formats_map, fmt, default=None)

Select the MIME type which best matches the client request.

Parameters

• mimetypes – Iterable of available MIME types.

• accept_mimetypes – The client’s “Accept” header as MIMEAccept object.

• formats_map – Map of format values to MIME type.

• format – The client’s selected format.

• default – Default MIMEtype if a wildcard was received.

classmethod match_by_accept(mimetypes, accept_mimetypes, default=None)

Select the MIME type which best matches Accept header.

NOTE: Our match policy differs from Werkzeug’s best_match policy:

If the client accepts a specific mimetype and wildcards, and the server serves that specific mimetype, then favour that mimetype no matter its quality over the wildcard. This is as opposed to Werkzeug which only cares about quality.

Parameters

• mimetypes – Iterable of available MIME types.

• accept_mimetypes – The client’s “Accept” header as MIMEAccept object.

• default – Default MIMEtype if wildcard received.

classmethod match_by_format(formats_map, fmt)

Select the MIME type based on a query parameters.

flask_resources.content_negotiation.with_content_negotiation(response_handlers=None, default_accept_mimetype=None)

Decorator to perform content negotiation.

The result of the content negotiation is stored in the resources request context.

Request body parsing

Request parser for the body, headers, query string and view args.

class flask_resources.parsers.RequestBodyParser(deserializer)

Parse the request body.

Constructor.

parse()

Parse the request body.

flask_resources.parsers.request_body_parser(parsers={'application/json': <flask_resources.parsers.body.RequestBodyParser object>}, default_content_type='application/json')

Create decorator for parsing the request body.

Both decorator parameters can be resolved from the resource configuration.

Parameters

• parsers – A mapping of content types to parsers.

• default_content_type_name – The default content type used to select a parser if no content type was provided.

Request parsing

Request parser for extracting URL args, headers and view args.

The request parser uses a declarative way to extract and validate request parameters. The parser can parse data in three different locations:

• args: URL query string (i.e. request.args)

• headers: Request headers (i.e. request.headers)

• view_args: Request view args (i.e. request.view_args)

The parser is not meant to parse the request body. For that you should use the RequestBodyParser.

The request parser can accept both a schema or a dictionary. Using the schema enables you to do further pre/post-processing of values, while the dict version can be more compact.

Example with schema:

class MyHeaders(ma.Schema):
    content_type = ma.fields.String()

parser = RequestParser(MyHeaders, location='headers')
parser.parse()

Same example with dict:

parser = RequestParser({
    'content_type': ma.fields.String()
}, location='headers')
parser.parse()

URL args parsing

If you are parsing URL args, be aware that a query string can have repeated variables (e.g. in ?type=a&type=b the value type is repeated).

Thus if you build your own schema for URL args, you should inherit from MultiDictSchema. If you don’t have repeated keys you can use a normal Marshmallow schema.

Unknown values

If you pass a dict for the schema, you can control what to do with unknown values:

parser = RequestParser({
    'id': ma.fields.String()
}, location='args', unknown=ma.RAISE)
parser.parse()

If you build your own schema, the same can be achieved with by providing the meta class:

class MyArgs(ma.Schema):
    id = ma.fields.String()

    class Meta:
        unknown = ma.INCLUDE

class flask_resources.parsers.base.RequestParser(schema_or_dict, location, unknown='exclude')

Request parser.

Constructor.

Parameters

• schema_or_dict – A marshmallow schema class or a mapping from keys to fields.

• location – Location where to load data from. Possible values: (args, headers, or view_args).

• unknown – Determines how to handle unknown values. Possible values: ma.EXCLUDE, ma.INCLUDE, ma.RAISE. Only used if the schema is a dict.

property default_schema_cls

Get the base schema class when dynamically creating the schema.

By default, request.args is a MultiDict which a normal Marshmallow schema does not know how to handle, we therefore change the schema only for request args parsing.

load_data()

Load data from request.

property location

The request location for this request parser.

parse()

Parse the request data.

property schema

Build the schema class.

schema_from_dict(schema_dict)

Construct a schema from a dict.

Decorator for invoking the request parser.

flask_resources.parsers.decorators.request_parser(schema_or_parser, location=None, **options)

Create decorator for parsing the request.

Both decorator parameters can be resolved from the resource configuration.

Parameters

• schema_or_parser – A mapping of content types to parsers.

• default_content_type_name – The default content type used to select a parser if no content type was provided.

Errors

Exceptions used in Flask Resources module.

exception flask_resources.errors.HTTPJSONException(code=None, errors=None, **kwargs)

HTTP Exception delivering JSON error responses.

Initialize HTTPJSONException.

get_body(environ=None, scope=None)

Get the request body.

get_description(environ=None, scope=None)

Returns an unescaped description.

get_errors()

Get errors.

Returns

A list containing the errors.

get_headers(environ=None, scope=None)

Get a list of headers.

property name

The status name.

exception flask_resources.errors.InvalidContentType(allowed_mimetypes=None, **kwargs)

Error for when an invalid Content-Type header is provided.

Initialize exception.

exception flask_resources.errors.MIMETypeException(allowed_mimetypes=None, **kwargs)

Error for when an invalid Content-Type is provided.

Initialize exception.

exception flask_resources.errors.MIMETypeNotAccepted(allowed_mimetypes=None, **kwargs)

Error for when an invalid Accept header is provided.

Initialize exception.

flask_resources.errors.create_error_handler(map_func_or_exception)

Creates a resource error handler.

The handler is used to map business logic exceptions to REST exceptions. The original exceptions is being stored in the __original_exc__ attribute of the mapped exception.

Parameters

map_func_or_exception – Function or exception to map originally raised exception to a flask_resources.errors.HTTPJSONException.

Serializers/deserializers

Serializers.

class flask_resources.serializers.BaseSerializer

Serializer Interface.

abstract serialize_object(obj)

Serialize a single object according to the response ctx.

serialize_object_list(obj_list)

Serialize a list of objects according to the response ctx.

class flask_resources.serializers.BaseSerializerSchema(dumpers=None, **kwargs)

Enables the extension of Marshmallow schemas serialization.

Constructor.

post_dump_pipeline(data, original, many, **kwargs)

Applies a sequence of post-dump steps to the serialized data.

Parameters

• data – The result of serialization.

• original – The original object that was serialized.

• many – Whether the serialization was done on a collection of objects.

Returns

The result of the pipeline processing on the serialized data.

pre_dump_pipeline(data, many, **kwargs)

Applies a sequence of pre-dump steps to the input data.

Parameters

• data – The result of serialization.

• many – Whether the serialization was done on a collection of objects.

Returns

The result of the pipeline processing on the serialized data.

class flask_resources.serializers.DumperMixin

Abstract class that defines an interface for pre_dump and post_dump methods.

It allows to extend records serialization.

post_dump(data, original=None, **kwargs)

Hook called after the marshmallow serialization of the record.

Parameters

• data – The dumped record data.

• original – The original record data.

• kwargs – Additional keyword arguments.

Returns

The serialized record data.

pre_dump(data, original=None, **kwargs)

Hook called before the marshmallow serialization of the record.

Parameters

• data – The record data to dump.

• original – The original record data.

• kwargs – Additional keyword arguments.

Returns

The data to dump.

class flask_resources.serializers.JSONSerializer(encoder=None, options=None)

JSON serializer implementation.

Initialize the JSONSerializer.

property dumps_options

Support adding options for the dumps() method.

property encoder

Support overriding the JSONEncoder used for serialization.

serialize_object(obj)

Dump the object into a json string.

serialize_object_list(obj_list)

Dump the object list into a json string.

class flask_resources.serializers.MarshmallowSerializer(format_serializer_cls, object_schema_cls, list_schema_cls=None, schema_context=None, schema_kwargs=None, **serializer_options)

Marshmallow serializer that serializes an obj into defined schema.

Parameters

• format_serializer_cls – Serializer in charge of converting the data object into the desired format.

• object_schema_cls – Marshmallow Schema of the object.

• list_schema_cls – Marshmallow Schema of the object list.

• schema_context – Context of the Marshmallow Schema.

• schema_kwargs – Additional arguments to be passed to marshmallow schema.

Initialize the serializer.

dump_list(obj_list)

Dump the list of objects.

dump_obj(obj)

Dump the object using object schema class.

serialize_object(obj)

Dump the object using the serializer.

serialize_object_list(obj_list)

Dump the object list using the serializer.

class flask_resources.serializers.SimpleSerializer(encoder)

Simple serializer implementation.

Initialize the SimpleSerializer.

serialize_object(obj, **kwargs)

Dump the object into a string using the encoder function.

serialize_object_list(obj_list, **kwargs)

Dump the object list into a string separated by new lines.

Deserializers.

class flask_resources.deserializers.DeserializerMixin

Deserializer Interface.

deserialize(data)

Deserializes the data into an object.

class flask_resources.deserializers.JSONDeserializer

JSON Deserializer.

deserialize(data)

Deserializes JSON into a Python dictionary.