API Reference

FlumpBlueprint

class flump.FlumpBlueprint(*args, **kwargs)

A specialised Flask Blueprint for Marshmallow, which provides a convenience method for registering FlumpView routes.

Parameters:logging – If True, Provides some default logging. This logs the request HTTP method, the kwargs passed to the view endpoint, and the request JSON body.

Adds the ‘application/vnd.api+json’ Content-Type header to all responses.

register_flump_view(view_class, url)

Registers the various URL rules for the given flump_view on the Blueprint.

Parameters:flump_view – The view.FlumpView to register URLs for.

flump_view(url)

A class decorator for registering a flump view.

Parameters:url – The URL to register the view under.

FlumpView

class flump.view.FlumpView

A base view from which all views provided to FlumpBlueprint must inherit.

Classes which inherit from this must override:

ORM_INTEGRATION

A class which inherits from orm.OrmIntegration

FETCHER

A class which inherits from fetcher.Fetcher.

They also may override:

HTTP_METHODS

A set containing the HTTP Methods to use. See methods.HttpMethods

PAGINATOR

A paginator to use, the default provides NO pagination. If overridden must inherit from paginator.BasePagination

They MUST also provide provide RESOURCE_NAME & SCHEMA attributes that specify the name of the resource, and the schema to use for serialization/desieralization.

They MAY also provide a VIEW_NAME attribute that will be used as the name of the flask view. This can be used in url_for calls. If not provided, this will default to RESOURCE_NAME.

FlumpView HTTP Methods

FlumpView.get(entity_id=None, **kwargs)

Handles HTTP GET requests.

Dispatches to either flump.view.FlumpView.get() or flump.view.FlumpView.get_many() depending on whether an entity_id has been provided.

Raises werkzeug.exceptions.NotImplemented:  If the method requested has not been mixed in.

FlumpView.get_many(**kwargs)

Handles HTTP GET requests where no entity is specified.

Gets many instances using flump.view.FlumpView.get_many_entities(), and also requires flump.view.FlumpView.get_total_entities() to be implemented in order to provide the total count.

Parameters:**kwargs – kwargs taken from the url used for specifying the entities to be returned.

FlumpView.get_single(entity_id=None, **kwargs)

Handles HTTP GET requests where a entity is specified.

If an etag is provided and matches the current etag, returns a 304 (Not Modfied).

Otherwise dumps the retrieved entity to JSON based on the current schema and returns it.

Parameters:

• entity_id – The entity_id used to retrieve the entity using flump.view.FlumpView.get_entity()
• **kwargs – Any other kwargs taken from the url which are used for identifying the entity to retrieve.

FlumpView.delete(entity_id=None, **kwargs)

Handles HTTP DELETE requests.

Verifies that the etag is valid for deletion then deletes the entity with the given entity_id using flump.view.FlumpView.delete_entity()

Parameters:

• entity_id – The id of the entity to be deleted.
• **kwargs – Any other kwargs taken from the url which are used for identifying the entity to be deleted.

FlumpView.post(**kwargs)

Handles HTTP POST requests.

Creates an entity based on the current schema and request json. The view should provide a method for creating the entity using Post.create_entity()

Parameters:**kwargs – Any kwargs taken from the url which are used for building the url identifying the new entity.

FlumpView.patch(entity_id=None, **kwargs)

Handles HTTP PATCH requests.

Updates an entity based on the current schema and request json. The view should provide a method for updating the entity using Patch.update_entity().

Parameters:

• entity_id – The entity_id used to retrieve the entity using flump.view.FlumpView.get_entity()
• **kwargs – Any other kwargs taken from the url which are used for identifying the entity to patch.

FlumpView Properties

FlumpView.data_schema()

A Schema describing the main jsonapi format for SCHEMA.

FlumpView.response_schema()

A schema describing the format of a response according to jsonapi.

Fetcher

class flump.fetcher.Fetcher

Base Fetcher class. All flump.view.FlumpView should have a FETCHER which inherits from this class and implements the necessary methods for their chosen HTTP methods.

get_total_entities(**kwargs)

Returns:Should return an integer of the total number of entities.

get_many_entities(pagination_args, **kwargs)

Returns:Should return an iterable of entities.

get_entity(entity_id=None, **kwargs)

Should provide a method of retrieving a single entity given the entity_id and **kwargs.

Parameters:

• entity_id – The id of the entity to be retrieved.
• **kwargs – Any other kwargs taken from the url which are used for identifying the entity to be retrieved.

Returns:

The entity identified by entity_id and **kwargs.

OrmIntegration

class flump.orm.OrmIntegration

Base OrmIntegration class. view.FlumpView.ORM_INTEGRATION should inherit from this class and implements the necessary methods for the view.FlumpView.HTTP_METHODS.

delete_entity(entity)

Should provide a method of deleting the entity passed.

Parameters:entity – The entity returned by view.FlumpView.get_entity() which is to be deleted.

create_entity(data)

Should save an entity from the given data.

Parameters:data – The deserialized data dict. Returns:The newly created entity.

update_entity(existing_entity, data)

Should update an entity from the given data.

Parameters:

• existing_entity – The instance returned from view.FlumpView.get_entity()
• data – The deserialized data dict.

Returns:

The updated entity.

Pagination

class flump.pagination.BasePagination(fetcher)

Base Paginator class which all paginators should inherit from. Provides a transform_get_many_response function which is called from methods.get_many.GetMany._make_get_many_response() in order to add any meta information as needed.

get_pagination_args()

Gets the pagination args from the request.

transform_get_many_response(response, **kwargs)

Transforms the response to a get_many request. Mainly intended to add extra pagination links/meta information if pagination is implemented for the api.

Returns:schemas.ManyResponseData

class flump.pagination.PageSizePagination(fetcher)

Mixin class which provides methods for Number/Size based pagination.

get_pagination_args()

Gets the pagination args from the query string.

Returns:PaginationArgs containing the page number and page sizes specified. Accounts for :attribute:`PageSizePagination.DEFAULT_PAGE_SIZE` and :attribute:`PageSizePagination.MAX_PAGE_SIZE`.

get_pagination_links(**kwargs)

Returns a dict containing all of the pagination links required by jsonapi.

Parameters:`**kwargs – kwargs used for constructing the pagination links. Returns:Dict containing the pagination links required by jsonapi.

transform_get_many_response(response, **kwargs)

Returns a schemas.ManyResponseData with the links replaced with those returned by get_pagination_links.

Also adds the max_results and page args to the meta.

Schemas

schemas.make_data_schema(resource_schema, only=None, partial=False, id_required=False)

Constructs a Schema describing the main jsonapi format for the current resource_schema.

Parameters:

• resource_schema – The schema describing the resource. Should be an instance of marshmallow.Schema
• only – A list or tuple of fields to serialize on the resource_schema, if None, all fields will be serialized.
• partial – If True, ignore missing fields on the resource_schema when deserializing.
• id_required – Whether or not the id field of the returned JsonApiSchema

Returns:

make_data_schema.JsonApiSchema

schemas.make_response_schema(resource_schema, only=None, many=False)

Constructs Schema describing the format of a response according to jsonapi.

Parameters:

• resource_schema – The schema describing the resource. Should be an instance of marshmallow.Schema
• only – A list or tuple of fields to serialize on the resource_schema, if None, all fields will be serialized.
• many – Should be set to True if we are returning multiple entities.

Returns:

make_response_schema.JsonApiResponseSchema

schemas.make_entity_schema(resource_schema, resource_name, data_schema)

Constructs a schema describing the format of POST/PATCH requests for jsonapi. Provides automatic error checking for the data format.

Parameters:

• resource_schema – The schema describing the resource. Should be an instance of marshmallow.Schema
• resource_name – The name of the resource type defined for the API.
• data_schema – An instance or make_data_schema.JsonApiSchema.

Returns:

make_entity_schema.JsonApiPostSchema

_FlumpMethodView

class flump.view._FlumpMethodView(flump_view)

flask.Blueprint.add_url_rule() does not allow us to pass instantiated instances of MethodView as the view_func, so instead we store the instantiated instance of our route handlers on this class, and pass args and kwargs through to the view methods manually.

Validators

class flump.validators.Immutable(*args, **kwargs)

Validator which ensures that a field cannot be updated through a PATCH request.