API

Configuration

pyramid_restler.config.add_restful_routes(self, name, factory, view=<class 'pyramid_restler.view.RESTfulView'>, route_kw=None, view_kw=None)

Add a set of RESTful routes for an entity.

URL patterns for an entity are mapped to a set of views encapsulated in a view class. The view class interacts with the model through a context adapter that knows the particulars of that model.

To use this directive in your application, first call config.include(‘pyramid_restler’) somewhere in your application’s main function, then call config.add_restful_routes(...).

name is used as the base name for all route names and patterns. In route names, it will be used as-is. In route patterns, underscores will be converted to dashes.

factory is the model adapter that the view interacts with. It can be any class that implements the pyramid_restler.interfaces.IContext interface.

view must be a view class that implements the pyramid_restler.interfaces.IView interface.

Additional route and view keyword args can be passed directly through to all add_route and add_view calls. Pass route_kw and/or view_kw as dictionaries to do so.

pyramid_restler.config.enable_POST_tunneling(self, allowed_methods=('PUT', 'DELETE'))

Allow other request methods to be tunneled via POST.

This allows PUT and DELETE requests to be tunneled via POST requests. The method can be specified using a parameter or a header...

The name of the parameter is ‘$method’; it can be a query or POST parameter. The query parameter will be preferred if both the query and POST parameters are present in the request.

The name of the header is ‘X-HTTP-Method-Override’. If the parameter described above is passed, this will be ignored.

The request method will be overwritten before it reaches application code, such that the application will never be aware of the original request method. Likewise, the parameter and header will be removed from the request, and the application will never see them.

Interfaces

interface pyramid_restler.interfaces.IView

update_member(id)

Update an existing member.

PUT /entity/id?POST_data -> 204 No Content

get_member()

Get a specific member by ID.

GET /entity/id -> 200 OK, member

delete_member(id)

Delete an existing member.

DELETE /entity/id -> 204 No Content

get_collection()

Get the entire collection.

GET /entity -> 200 OK, list of members

If a query parameter named $$ is present on the request, it must be a JSON object with keys that correspond to the keyword args of the context’s get_collection method. The object will be JSON-decoded, but no further processing will be done on the resulting dict (i.e., types won’t be coerced, etc).

render_to_response(value, fields=None)

Render a member or list of members to an appropriate response.

The request should include an indication of the client’s preferred representation. This can be specified via the Accept header or by using the {.renderer} notation at the end of the URL path.

create_member()

Create a new member.

POST /entity?POST_data -> 201 Created, location of new member

__init__(context, request)

Initialize view class.

interface pyramid_restler.interfaces.IContext

Interface for adapting a model entity to a view context.

update_member(id, **data)

Update an existing member.

get_member(id)

Return the member identified by id.

delete_member(id)

Delete an existing member.

entity

The entity to operate on.

get_collection(**kwargs)

Return the entire collection by default.

Implementation-specific keyword args may be passed to filter the collection or alter it in various ways.

create_member(**data)

Create a new member.

get_member_id_as_string(member)

Get string representation of member ID.

__init__(request)

Initialize context.

default_fields

A list of fields to include in the result.

View

class pyramid_restler.view.RESTfulView(context, request)

Model

class pyramid_restler.model.SQLAlchemyORMContext(request)

Adapts a SQLAlchemy ORM class to the pyramid_restler.interfaces.IContext interface.

get_collection(distinct=False, order_by=None, limit=None, offset=None, filters=None)

Get the entire collection or a subset of it.

By default, this will fetch all records for entity. Various types of filtering can be applied to instead fetch a subset.

The simplest “filter” is LIMIT. This can be used by itself or in conjunction with other filters.

There are two types of filters that can be applied: global filters that will be applied to all queries of this collection and per-query filters.

Global filters are specified by the filters attribute. Generally, it will be a class-level attribute, but an instance can also set filters (perhaps to disable the global defaults). The items in the filters list can be anything that can be passed into SQLAlchemy’s Query.filter method.

Per-query filters are specified by passing a dict of filters via the filters keyword arg. A key in the dict names either a method on the entity that is named as {key}_filter or an entity attribute. In the first case, the {key}_filter method is expected to return a filter that can be passed into Query.filter. In the second case, a simple filter_by(key=value) is applied to the query.

to_json(value, fields=None, wrap=True)

Convert instance or sequence of instances to JSON.

value is a single ORM instance or an iterable that yields instances.

fields is a list of fields to include for each instance.

wrap indicates whether or not the result should be wrapped or returned as-is.