API¶
Configuration¶
-
pyramid_restler.config.
add_json_adapters
(self: pyramid.config.Configurator, *adapters)¶ Add default and additional JSON adapters.
Adds default JSON adapters for date, datetime, and decimal objects:
- date -> ISO date string
- datetime -> ISO datetime string
- decimal -> string
Also adds additional adapters if specified.
Note
If you don’t want the defaults, use
add_json_adapter()
instead.
-
pyramid_restler.config.
add_resource
(self: pyramid.config.Configurator, resource_class, name=None, renderers=['json'], acl=None, path=None, path_prefix=None, id_field=None, route_args=None, view=<class 'pyramid_restler.view.ResourceView'>, permission=None, view_args=None)¶ Add routes and views for a resource.
Given a resource (class), generates a set of routes and associated views.
- Args:
- resource_class: The class that implements the resource. An
allowed_methods
attribute will be attached to this class (if it doesn’t already have that attribute).- name: The base route name. If not specified, this will be
computed from the resource class’s module path and class name as follows:
- If the class name ends with “Resource”, that’s stripped off
- The class name is then converted to camel case
- The module name containing the class is joined to the converted class name with a dot
So, for a resource class named
ContainerResource
in a module namedapi
, the computed name will be “api.container”.- renderers: A list of renderers to generate routes and views for.
This can include entries like “json” and/or “template.mako”.
For each renderer, a route with an extension (like “.json” and/or “.html”) is generated with a view for each corresponding resource method. In this case, the response is rendered according to the extension.
In addition, a route with no extension is generated with a view for each corresponding resource method. In this case, the response is rendered according to the Accept header in the request.
- acl: An ACL list that will be attached to the resource class as
- its
__acl__
attribute. If this isn’t specified and the resource class doesn’t have an__acl__
attribute already, the default ACL will be attached instead (assuming a default ACL is configured). - path: The base route path. If not specified, this will be
- computed from
name
by replacing dots with slashes and underscores with dashes. For the example above, the computed path would be “/api/container”. - path_prefix: If specified, this will be prepended to all
- generated route paths.
- id_field: If specified, an ID-field path segment will be
- appended to
path
. E.g., if “id” is passed, the base path will be set to “/whatever/path/{id}”. This is useful when an explicitpath
isn’t passed. - route_args: Common route args that will be passed to every
- call to
config.add_view()
. - view: The view class that will call methods on the resource
- class. This is optional because in many cases the included/ default view class will suffice.
- permission: Permission that will be set on all generated views.
- This is a special case for convenience.
- view_args: Common view args that will be passed to every call
- to
config.add_view()
.
Settings can be set under the “pyramid_restler” key:
- default_acl: Default ACL to attach to resource classes that
don’t have an __acl__ attribute (when
acl
isn’t specified). - resource_methods: Methods on resource classes that will be
considered resource methods (these should be lower case); if not
specified, the default
RESOURCE_METHODS
will be used.
-
pyramid_restler.config.
add_resources
(self: pyramid.config.Configurator, path_prefix, add_method=None, **shared_kwargs)¶ Add multiple resources at the specified path prefix.
Example:
with config.add_resources("/api") as add_resource: add_resource(".resources.ContainerResource") # -> /api/resources/container add_resource(".resources.ItemResource") # -> /api/resources/item
-
pyramid_restler.config.
enable_cors
(self: pyramid.config.Configurator)¶ Enable CORS permissively (for use in development).
This allows CORS requests from anywhere, which is probably not what you want, other than in development.
Warning
Use with CAUTION. See
add_cors_headers()
for additional info.
-
pyramid_restler.config.
enable_post_tunneling
(self: pyramid.config.Configurator, allowed_methods=('DELETE', 'PATCH', 'PUT'), param_name='$method', header_name='X-HTTP-Method-Override')¶ Allow other request methods to be tunneled via POST.
This allows DELETE, PATCH, and PUT and 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.
Settings¶
-
pyramid_restler.settings.
DEFAULT_SETTINGS
= {'default_acl': None, 'get_default_response_fields': None, 'item_processor': None, 'resource_methods': ('delete', 'get', 'options', 'patch', 'post', 'put')}¶ Default settings.
-
pyramid_restler.settings.
get_setting
(all_settings, name, default=<object object>)¶ Get pyramid_restler setting from config.
If the setting wasn’t set in the app, the passed
default
value will be used. If adefault
value wasn’t passed, the default fromDEFAULT_SETTINGS
will be used.
Views¶
-
class
pyramid_restler.view.
ResourceView
(context, request: pyramid.request.Request)¶ -
get_standard_response
(data)¶ Get a standard response.
When there’s no data, return a
204 No Content
response regardless of the request method or configured renderers. Otherwise…For XHR requests, return a
200 OK
response with rendered data for all request methods (typically JSON).For non-XHR requests:
- Return a
200 OK
response with rendered data for GET requests (typically HTML rendered from a template). For HEAD requests, the data is also returned so that Pyramid can generate a HEAD response. - Return a
303 See Other
response for DELETE, PATCH, PUT, and POST requests:- For DELETEs, use the referrer if it’s safe (same origin) or fall back to the URL of the current resource.
- For other methods, fall back to the URL of the current resource (which is always safe).
- Return a
-