sandman API — sandman 0.7.7rc2 documentation

### Navigation

- index
- modules |
- previous |
- sandman 0.7.7rc2 documentation »

# 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`()

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

    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.

  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`(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`(collection)

  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_resource`(collection, key)

  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`(collection, key, attribute)

  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.` `no_content_response`()

  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)

  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

### Navigation

- index
- modules |
- previous |
- sandman 0.7.7rc2 documentation »