API Reference

FlumpBlueprint

class flump.FlumpBlueprint(*args, **kwargs)[source]

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)[source]

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)[source]

A class decorator for registering a flump view.

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

FlumpView

class flump.view.FlumpView[source]

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)[source]

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[source]

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)[source]
Returns:Should return an integer of the total number of entities.
get_many_entities(pagination_args, **kwargs)[source]
Returns:Should return an iterable of entities.
get_entity(entity_id=None, **kwargs)[source]

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[source]

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)[source]

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)[source]

Should save an entity from the given data.

Parameters:data – The deserialized data dict.
Returns:The newly created entity.
update_entity(existing_entity, data)[source]

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.

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)[source]

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)[source]

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