sandman API

exception Module

Exception specifications for Sandman

exception sandman.exception.InvalidAPIUsage(code=400, message=None, payload=None)

Bases: exceptions.Exception

Excecption which generates a flask.Response object whose data is JSON rather than HTML

abort()

Return an HTML Response representation of the exception.

to_dict()

Return a dictionary representation of the exception.

model Module

The model module is repsonsible exposes the sandman.model.Model class, from which user models should derive. It also makes the register() function available, which maps endpoints to their associated classes.

sandman.model.register(cls, use_admin=True)

Register with the API a sandman.model.Model class and associated endpoint.

Parameters:cls (sandman.model.Model or tuple) – User-defined class derived from sandman.model.Model to be registered with the endpoint returned by endpoint()

sandman.model.activate(admin=True, browser=True, name='admin', reflect_all=False)

Activate each pre-registered model or generate the model classes and (possibly) register them for the admin.

Parameters:

• admin (bool) – should we generate the admin interface?
• browser (bool) – should we open the browser for the user?
• name – name to use for blueprint created by the admin interface. Set this to avoid naming conflicts with other blueprints (if trying to use sandman to connect to multiple databases simultaneously)

The Model class is meant to be the base class for user Models. It represents a table in the database that should be modeled as a resource.

class sandman.model.models.AdminModelViewWithPK(model, session, name=None, category=None, endpoint=None, url=None)

Bases: flask_admin.contrib.sqla.view.ModelView

Mixin admin view class that displays primary keys on the admin form

_default_view = 'index_view'

_urls = [('/action/', 'action_view', ('POST',)), ('/ajax/lookup/', 'ajax_lookup', ('GET',)), ('/new/', 'create_view', ('GET', 'POST')), ('/delete/', 'delete_view', ('POST',)), ('/edit/', 'edit_view', ('GET', 'POST')), ('/', 'index_view', ('GET',))]

action_view(*args, **kwargs)

Mass-model action view.

ajax_lookup(*args, **kwargs)

column_display_pk = True

create_view(*args, **kwargs)

Create model view

delete_view(*args, **kwargs)

Delete model view. Only POST method is allowed.

edit_view(*args, **kwargs)

Edit model view

index_view(*args, **kwargs)

List view

class sandman.model.models.Model

Bases: object

A mixin class containing the majority of the RESTful API functionality.

sandman.model.Model is the base class of :class:`sandman.Model, from which user models are derived.

__endpoint__ = None

override __endpoint__ if you wish to configure the sandman.model.Model’s endpoint.

Default: __tablename__ in lowercase and pluralized

__methods__ = ('GET', 'POST', 'PATCH', 'DELETE', 'PUT')

override __methods__ if you wish to change the HTTP methods this sandman.model.Model supports.

Default: ('GET', 'POST', 'PATCH', 'DELETE', 'PUT')

__table__ = None

Will be populated by SQLAlchemy with the table’s meta-information.

__tablename__ = None

The name of the database table this class should be mapped to

Default: None

as_dict(depth=0)

Return a dictionary containing only the attributes which map to an instance’s database columns.

Parameters:depth (int) – Maximum depth to recurse subobjects Return type:dict

classmethod endpoint()

Return the sandman.model.Model’s endpoint.

Return type:string

from_dict(dictionary)

Set a set of attributes which correspond to the sandman.model.Model’s columns.

Parameters:dictionary (dict) – A dictionary of attributes to set on the instance whose keys are the column names of the sandman.model.Model’s underlying database table.

links()

Return a list of links for endpoints related to the resource.

Return type:list

classmethod meta()

Return a dictionary containing meta-information about the given resource.

classmethod primary_key()

Return the name of the table’s primary key

Return type:string

replace(dictionary)

Set all attributes which correspond to the sandman.model.Model’s columns to the values in dictionary, inserting None if an attribute’s value is not specified.

Parameters:dictionary (dict) – A dictionary of attributes to set on the instance whose keys are the column names of the sandman.model.Model’s underlying database table.

resource_uri()

Return the URI at which the resource can be found.

Return type:string

sandman Module

Sandman REST API creator for Flask and SQLAlchemy

sandman.sandman.attribute_response(resource, name, value)

Return a response for the resource of the appropriate content type.

Parameters:resource (sandman.model.Model) – resource to be returned in request Return type:flask.Response

sandman.sandman.collection_response(cls, resources, start=None, stop=None)

Return a response for the resources of the appropriate content type.

Parameters:resources – resources to be returned in request Return type:flask.Response

sandman.sandman.delete_resource(collection, key)

Return the appropriate Response for deleting an existing resource in collection.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – the primary key for the sandman.model.Model

Return type:

flask.Response

sandman.sandman.endpoint_class(collection)

Return the sandman.model.Model associated with the endpoint collection.

Parameters:collection (string) – a sandman.model.Model endpoint Return type:sandman.model.Model

sandman.sandman.get_collection(*args, **kwargs)

Return the appropriate Response for retrieving a collection of resources.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – the primary key for the sandman.model.Model

Return type:

flask.Response

sandman.sandman.get_meta(*args, **kwargs)

Return the meta-description of a given resource.

Parameters:collection – The collection to get meta-info for

sandman.sandman.get_resource(*args, **kwargs)

Return the appropriate Response for retrieving a single resource.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – the primary key for the sandman.model.Model

Return type:

flask.Response

sandman.sandman.get_resource_attribute(*args, **kwargs)

Return the appropriate Response for retrieving an attribute of a single resource.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – the primary key for the sandman.model.Model

Return type:

flask.Response

sandman.sandman.get_resource_data(incoming_request)

Return the data from the incoming request based on the Content-type.

sandman.sandman.handle_exception(error)

Return a response with the appropriate status code, message, and content type when an InvalidAPIUsage exception is raised.

sandman.sandman.index(*args, **kwargs)

Return information about each type of resource and how it can be accessed.

sandman.sandman.no_content_response(*args, **kwargs)

Return the appropriate Response with status code 204, signaling a completed action which does not require data in the response body

Return type:flask.Response

sandman.sandman.patch_resource(collection, key)

“Upsert” a resource identified by the given key and return the appropriate Response.

If no resource currently exists at /<collection>/<key>, create it with key as its primary key and return a resource_created_response().

If a resource does exist at /<collection>/<key>, update it with the data sent in the request and return a no_content_response().

Note: HTTP PATCH (and, thus, patch_resource()) is idempotent

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – the primary key for the sandman.model.Model

Return type:

flask.Response

sandman.sandman.post_resource(collection)

Return the appropriate Response based on adding a new resource to collection.

Parameters:collection (string) – a sandman.model.Model endpoint Return type:flask.Response

sandman.sandman.put_resource(collection, key)

Replace the resource identified by the given key and return the appropriate response.

Parameters:collection (string) – a sandman.model.Model endpoint Return type:flask.Response

sandman.sandman.resource_created_response(resource)

Return HTTP response with status code 201, signaling a created resource

Parameters:resource (sandman.model.Model) – resource created as a result of current request Return type:flask.Response

sandman.sandman.resource_response(resource, depth=0)

Return a response for the resource of the appropriate content type.

Parameters:resource (sandman.model.Model) – resource to be returned in request Return type:flask.Response

sandman.sandman.retrieve_collection(collection, query_arguments=None)

Return the resources in collection, possibly filtered by a series of values to use in a ‘where’ clause search.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• query_arguments (dict) – a list of filter query arguments

Return type:

class:sandman.model.Model

sandman.sandman.retrieve_resource(collection, key)

Return the resource in collection identified by key key.

Parameters:

• collection (string) – a sandman.model.Model endpoint
• key (string) – primary key of resource

Return type:

class:sandman.model.Model

sandman.sandman.update_resource(resource, incoming_request)

Replace the contents of a resource with data and return an appropriate Response.

Parameters:

• resource – sandman.model.Model to be updated
• data – New values for the fields in resource