Resources

restless.resources

class restless.resources.Resource(*args, **kwargs)

Defines a RESTful resource.

Users are expected to subclass this object & implement a handful of methods:

  • list

  • detail

  • create (requires authentication)

  • update (requires authentication)

  • delete (requires authentication)

Additionally, the user may choose to implement:

  • create_detail (requires authentication)

  • update_list (requires authentication)

  • delete_list (requires authentication)

Users may also wish to define a fields attribute on the class. By providing a dictionary of output names mapped to a dotted lookup path, you can control the serialized output.

Users may also choose to override the status_map and/or http_methods on the class. These respectively control the HTTP status codes returned by the views and the way views are looked up (based on HTTP method & endpoint).

classmethod as_detail(*init_args, **init_kwargs)

Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_list(*init_args, **init_kwargs)

Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_view(view_type, *init_args, **init_kwargs)

Used for hooking up the all endpoints (including custom ones), this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • view_type (string) – Should be one of list, detail or custom.

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

bubble_exceptions()

Controls whether or not exceptions will be re-raised when encountered.

The default implementation returns False, which means errors should return a serialized response.

If you’d like exceptions to be re-raised, override this method & return True.

Returns:

Whether exceptions should be re-raised or not

Return type:

boolean

build_error(err)

When an exception is encountered, this generates a JSON error message for display to the user.

Parameters:

err (Exception) – The exception seen. The message is exposed to the user, so beware of sensitive data leaking.

Returns:

A response object

build_response(data, status=200)

Given some data, generates an HTTP response.

If you’re integrating with a new web framework, you MUST override this method within your subclass.

Parameters:

  • data (string) – The body of the response to send

  • status (integer) – (Optional) The status code to respond with. Default is 200

Returns:

A response object

create(*args, **kwargs)

Allows for creating data via a POST on a list-style endpoint.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

May return the created item or None

create_detail(*args, **kwargs)

Creates a subcollection of data for a POST on a detail-style endpoint.

Uncommonly implemented due to the rarity of having nested collections.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

A collection of data

Return type:

list or iterable

delete(*args, **kwargs)

Deletes data for a DELETE on a detail-style endpoint.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

None

delete_list(*args, **kwargs)

Deletes ALL data in the collection for a DELETE on a list-style endpoint.

Uncommonly implemented due to potential of trashing large datasets. Implement with care.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

None

deserialize(method, endpoint, body)

A convenience method for deserializing the body of a request.

If called on a list-style endpoint, this calls deserialize_list. Otherwise, it will call deserialize_detail.

Parameters:

  • method (string) – The HTTP method of the current request

  • endpoint (string) – The endpoint style (list or detail)

  • body (string) – The body of the current request

Returns:

The deserialized data

Return type:

list or dict

deserialize_detail(body)

Given a string of text, deserializes a (presumed) object out of the body.

Parameters:

body (string) – The body of the current request

Returns:

The deserialized body or an empty dict

deserialize_list(body)

Given a string of text, deserializes a (presumed) list out of the body.

Parameters:

body (string) – The body of the current request

Returns:

The deserialized body or an empty list

detail(*args, **kwargs)

Returns the data for a GET on a detail-style endpoint.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

An item

Return type:

object or dict

handle(endpoint, *args, **kwargs)

A convenient dispatching method, this centralized some of the common flow of the views.

This wraps/calls the methods the user defines (list/detail/create etc.), allowing the user to ignore the authentication/deserialization/serialization/response & just focus on their data/interactions.

Parameters:

  • endpoint (string) – The style of URI call (typically either list or detail).

  • args – (Optional) Any positional URI parameter data is passed along here. Somewhat framework/URL-specific.

  • kwargs – (Optional) Any keyword/named URI parameter data is passed along here. Somewhat framework/URL-specific.

Returns:

A response object

handle_error(err)

When an exception is encountered, this generates a serialized error message to return the user.

Parameters:

err (Exception) – The exception seen. The message is exposed to the user, so beware of sensitive data leaking.

Returns:

A response object

http_methods = {'detail': {'DELETE': 'delete', 'GET': 'detail', 'POST': 'create_detail', 'PUT': 'update'}, 'list': {'DELETE': 'delete_list', 'GET': 'list', 'POST': 'create', 'PUT': 'update_list'}}
is_authenticated()

A simple hook method for controlling whether a request is authenticated to continue.

By default, we only allow the safe GET methods. All others are denied.

Returns:

Whether the request is authenticated or not.

Return type:

boolean

is_debug()

Controls whether or not the resource is in a debug environment.

If so, tracebacks will be added to the serialized response.

The default implementation simply returns False, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.

Returns:

If the resource is in a debug environment

Return type:

boolean

list(*args, **kwargs)

Returns the data for a GET on a list-style endpoint.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

A collection of data

Return type:

list or iterable

prepare(data)

Given an item (object or dict), this will potentially go through & reshape the output based on self.prepare_with object.

Parameters:

data (object or dict) – An item to prepare for serialization

Returns:

A potentially reshaped dict

Return type:

dict

preparer = <restless.preparers.Preparer object>
request_body()

Returns the body of the current request.

Useful for deserializing the content the user sent (typically JSON).

If you’re integrating with a new web framework, you might need to override this method within your subclass.

Returns:

The body of the request

Return type:

string

request_method()

Returns the HTTP method for the current request.

If you’re integrating with a new web framework, you might need to override this method within your subclass.

Returns:

The HTTP method in uppercase

Return type:

string

serialize(method, endpoint, data)

A convenience method for serializing data for a response.

If called on a list-style endpoint, this calls serialize_list. Otherwise, it will call serialize_detail.

Parameters:

  • method (string) – The HTTP method of the current request

  • endpoint (string) – The endpoint style (list or detail)

  • data (string) – The body for the response

Returns:

A serialized version of the data

Return type:

string

serialize_detail(data)

Given a single item (object or dict), serializes it.

Parameters:

data (object or dict) – The item to serialize

Returns:

The serialized body

Return type:

string

serialize_list(data)

Given a collection of data (objects or dicts), serializes them.

Parameters:

data (list or iterable) – The collection of items to serialize

Returns:

The serialized body

Return type:

string

serializer = <restless.serializers.JSONSerializer object>
status_map = {'create': 201, 'create_detail': 201, 'delete': 204, 'delete_list': 204, 'detail': 200, 'list': 200, 'update': 202, 'update_list': 202}
update(*args, **kwargs)

Updates existing data for a PUT on a detail-style endpoint.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

May return the updated item or None

update_list(*args, **kwargs)

Updates the entire collection for a PUT on a list-style endpoint.

Uncommonly implemented due to the complexity & (varying) busines-logic involved.

MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.

Returns:

A collection of data

Return type:

list or iterable

wrap_list_response(data)

Takes a list of data & wraps it in a dictionary (within the objects key).

For security in JSON responses, it’s better to wrap the list results in an object (due to the way the Array constructor can be attacked in Javascript). See http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ & similar for details.

Overridable to allow for modifying the key names, adding data (or just insecurely return a plain old list if that’s your thing).

Parameters:

data (list) – A list of data about to be serialized

Returns:

A wrapping dict

Return type:

dict

restless.resources.skip_prepare(func)

A convenience decorator for indicating the raw data should not be prepared.

restless.dj

class restless.dj.DjangoResource(*args, **kwargs)

A Django-specific Resource subclass.

Doesn’t require any special configuration, but helps when working in a Django environment.

classmethod as_detail(*args, **kwargs)

Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_list(*args, **kwargs)

Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

build_error(err)

When an exception is encountered, this generates a JSON error message for display to the user.

Parameters:

err (Exception) – The exception seen. The message is exposed to the user, so beware of sensitive data leaking.

Returns:

A response object

build_response(data, status=200)

Given some data, generates an HTTP response.

If you’re integrating with a new web framework, you MUST override this method within your subclass.

Parameters:

  • data (string) – The body of the response to send

  • status (integer) – (Optional) The status code to respond with. Default is 200

Returns:

A response object

classmethod build_url_name(name, name_prefix=None)

Given a name & an optional name_prefix, this generates a name for a URL.

Parameters:

  • name (string) – The name for the URL (ex. ‘detail’)

  • name_prefix (string) – (Optional) A prefix for the URL’s name (for resolving). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blog_post_list

Returns:

The final name

Return type:

string

is_debug()

Controls whether or not the resource is in a debug environment.

If so, tracebacks will be added to the serialized response.

The default implementation simply returns False, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.

Returns:

If the resource is in a debug environment

Return type:

boolean

serialize_list(data)

Given a collection of data (objects or dicts), serializes them.

Parameters:

data (list or iterable) – The collection of items to serialize

Returns:

The serialized body

Return type:

string

classmethod urls(name_prefix=None)

A convenience method for hooking up the URLs.

This automatically adds a list & a detail endpoint to your URLconf.

Parameters:

name_prefix (string) – (Optional) A prefix for the URL’s name (for resolving). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blogpost_list

Returns:

A list of url objects for include(...)

wrap_list_response(data)

Takes a list of data & wraps it in a dictionary (within the objects key).

For security in JSON responses, it’s better to wrap the list results in an object (due to the way the Array constructor can be attacked in Javascript). See http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ & similar for details.

Overridable to allow for modifying the key names, adding data (or just insecurely return a plain old list if that’s your thing).

Parameters:

data (list) – A list of data about to be serialized

Returns:

A wrapping dict

Return type:

dict

restless.fl

class restless.fl.FlaskResource(*args, **kwargs)

A Flask-specific Resource subclass.

Doesn’t require any special configuration, but helps when working in a Flask environment.

classmethod add_url_rules(app, rule_prefix, endpoint_prefix=None)

A convenience method for hooking up the URLs.

This automatically adds a list & a detail endpoint to your routes.

Parameters:

  • app (flask.Flask) – The Flask object for your app.

  • rule_prefix (string) – The start of the URL to handle.

  • endpoint_prefix (string) – (Optional) A prefix for the URL’s name (for endpoints). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blog_post_list

Returns:

Nothing

classmethod as_detail(*init_args, **init_kwargs)

Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_list(*init_args, **init_kwargs)

Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod build_endpoint_name(name, endpoint_prefix=None)

Given a name & an optional endpoint_prefix, this generates a name for a URL.

Parameters:

  • name (string) – The name for the URL (ex. ‘detail’)

  • endpoint_prefix (string) – (Optional) A prefix for the URL’s name (for resolving). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blogpost_list

Returns:

The final name

Return type:

string

build_response(data, status=200)

Given some data, generates an HTTP response.

If you’re integrating with a new web framework, you MUST override this method within your subclass.

Parameters:

  • data (string) – The body of the response to send

  • status (integer) – (Optional) The status code to respond with. Default is 200

Returns:

A response object

is_debug()

Controls whether or not the resource is in a debug environment.

If so, tracebacks will be added to the serialized response.

The default implementation simply returns False, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.

Returns:

If the resource is in a debug environment

Return type:

boolean

request_body()

Returns the body of the current request.

Useful for deserializing the content the user sent (typically JSON).

If you’re integrating with a new web framework, you might need to override this method within your subclass.

Returns:

The body of the request

Return type:

string

restless.pyr

class restless.pyr.PyramidResource(*args, **kwargs)

A Pyramid-specific Resource subclass.

Doesn’t require any special configuration, but helps when working in a Pyramid environment.

classmethod add_views(config, rule_prefix, routename_prefix=None)

A convenience method for registering the routes and views in pyramid.

This automatically adds a list and detail endpoint to your routes.

Parameters:

  • config (pyramid.config.Configurator) – The pyramid Configurator object for your app.

  • rule_prefix (string) – The start of the URL to handle.

  • routename_prefix (string) – (Optional) A prefix for the route’s name. The default is None, which will autocreate a prefix based on the class name. Ex: PostResource -> api_post_list

Returns:

pyramid.config.Configurator

classmethod as_detail(*init_args, **init_kwargs)

Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_list(*args, **kwargs)

Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

build_response(data, status=200)

Given some data, generates an HTTP response.

If you’re integrating with a new web framework, you MUST override this method within your subclass.

Parameters:

  • data (string) – The body of the response to send

  • status (integer) – (Optional) The status code to respond with. Default is 200

Returns:

A response object

classmethod build_routename(name, routename_prefix=None)

Given a name & an optional routename_prefix, this generates a name for a URL.

Parameters:

  • name (string) – The name for the URL (ex. ‘detail’)

  • routename_prefix (string) – (Optional) A prefix for the URL’s name (for resolving). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blogpost_list

Returns:

The final name

Return type:

string

restless.it

restless.tnd

class restless.tnd.TornadoResource(*args, **kwargs)

A Tornado-specific Resource subclass.

_request_handler_base_

To override tornado.web.RequestHandler we used, please assign your RequestHandler via this attribute.

alias of RequestHandler

application

a reference to tornado.web.Application

classmethod as_detail(*init_args, **init_kwargs)

Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

classmethod as_list(*init_args, **init_kwargs)

Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.

Parameters:

  • init_args – (Optional) Positional params to be persisted along for instantiating the class itself.

  • init_kwargs – (Optional) Keyword params to be persisted along for instantiating the class itself.

Returns:

View function

property r_handler

access to tornado.web.RequestHandler

request

a reference to tornado.httpclient.HTTPRequest