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/orhttp_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
orcustom
.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 calldeserialize_detail
.- Parameters
method (string) – The HTTP method of the current request
endpoint (string) – The endpoint style (
list
ordetail
)body (string) – The body of the current request
- Returns
The deserialized data
- Return type
list
ordict
- 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
ordetail
).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
ordict
), this will potentially go through & reshape the output based onself.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 callserialize_detail
.- Parameters
method (string) – The HTTP method of the current request
endpoint (string) – The endpoint style (
list
ordetail
)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
ordict
), 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
ordicts
), 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 theArray
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 optionalname_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
ordicts
), 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 forinclude(...)
- 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 theArray
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
) – TheFlask
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 optionalendpoint_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 pyramidConfigurator
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 optionalroutename_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
tornado.web.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