# 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

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

## 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_`

    alias of `tornado.web.RequestHandler`

  `application` = None

    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

  `r_handler`

    access to `tornado.web.RequestHandler`

  `request` = None

    a reference to `tornado.httpclient.HTTPRequest`