pyramid_rpc
supports JSON-RPC 2.0 Specification .
from pyramid.config import Configurator
from pyramic_rpc import jsonrpc_method
@jsonrpc_method(endpoint='api')
def say_hello(request, name):
return 'hello, %s!' % name
def main(global_conf, **settings):
config = Configurator(settings=settings)
config.include('pyramid_rpc.jsonrpc')
config.add_jsonrpc_endpoint('api', '/api')
config.scan(__name__)
return config.make_wsgi_app()
if __name__ == '__main__':
from paste.httpserver import serve
app = main({})
serve(app, 'localhost', 8080)
Use the includeme
via pyramid.config.Configurator.include
:
config.include('pyramid_rpc.jsonrpc')
Once activated, the following happens:
- The
pyramid_rpc.jsonrpc.add_jsonrpc_endpoint
directive is added to theconfig
instance. - The
pyramid_rpc.jsonrpc.add_jsonrpc_method
directive is added to theconfig
instance. - An exception view is registered for
pyramid_rpc.jsonrpc.JsonRpcError
exceptions.
After including the pyramid_rpc.jsonrpc
package in your project, you can add an endpoint
for handling incoming requests. After that, attach several methods to the endpoint to handle specific functions within your api.
An endpoint
is added via the ~pyramid_rpc.jsonrpc.add_jsonrpc_endpoint
directive on the config
instance.
Example:
config = Configurator()
config.include('pyramid_rpc.jsonrpc')
config.add_jsonrpc_endpoint('api', '/api/jsonrpc')
It is possible to add multiple endpoints as well as pass extra arguments to ~pyramid_rpc.jsonrpc.add_jsonrpc_endpoint
to handle traversal, which can assist in adding security to your RPC API.
Methods on your API are exposed by attaching views to an endpoint
. Methods may be attached via the ~pyramid_rpc.jsonrpc.add_jsonrpc_method
which is a thin wrapper around pyramid.config.Configurator.add_view
method.
Example:
def say_hello(request, name):
return 'Hello, ' + name
config.add_jsonrpc_method(say_hello, endpoint='api', method='say_hello')
If you prefer, you can use the ~pyramid_rpc.jsonrpc.jsonrpc_method
view decorator to declare your methods closer to your actual code. Remember when using this lazy configuration technique, it's always necessary to call pyramid.config.Configurator.scan
from within your setup code.
from pyramid_rpc.jsonrpc import jsonrpc_method
@jsonrpc_method(endpoint='api')
def say_hello(request, name):
return 'Hello, ' + name
config.scan()
To set the RPC method to something other than the name of the view, specify the method
parameter:
from pyramid_rpc.jsonrpc import jsonrpc_method
@jsonrpc_method(method='say_hello', endpoint='api')
def say_hello_view(request, name):
return 'Hello, ' + name
config.scan()
Because methods are a thin layer around Pyramid's views, it is possible to add extra view predicates to the method, as well as permission
requirements.
By default, responses are rendered using the Python standard library's json.dumps
. This can be changed the same way any renderer is changed in Pyramid. See the Pyramid Renderers chapter for extra details. As an example, let's update an endpoint
to use Pyramid 1.4's cool new pyramid.renderers.JSON
renderer which supports custom adapters.
from pyramid.renderers import JSON
json_renderer = JSON()
json_renderer.add_adapter(datetime.datetime, lambda v: v.isoformat())
config.add_renderer('myjson', json_renderer)
config.add_jsonrpc_endpoint('api', '/api', default_renderer='myjson')
A default_renderer
can be specified on an endpoint
, which will propagate to all methods attached to the endpoint. Optionally, an individual method can also override the renderer.
A view mapper is registered for JSON-RPC methods by default which will match the arguments from request.rpc_args
to the parameters of the view. Optional arguments are allowed and an error will be returned if too many or too few arguments are supplied to the view.
This default view mapper may be overridden by setting the default_mapper
option on ~pyramid_rpc.jsonrpc.add_jsonrpc_endpoint
or the mapper
option when using ~pyramid_rpc.jsonrpc.jsonrpc_method
or ~pyramid_rpc.jsonrpc.add_jsonrpc_method
.
As of pyramid_rpc
version 0.5, JSON-RPC requests can be made using HTTP GET. By default, an endpoint will accept requests from both GET
and POST
methods. This can be controlled on either the endpoint
or on an individual method by using the request_method
predicate. For example, to limit requests to only POST
requests:
config.add_jsonrpc_endpoint('api', '/api', request_method='POST')
Pyramid comes with a pyramid.renderers.JSONP
which can be registered for the endpoint, using the method described within jsonrpc_custom_renderers
.
pyramid_rpc.jsonrpc
includeme
add_jsonrpc_endpoint
add_jsonrpc_method
jsonrpc_method
JsonRpcError
JsonRpcParseError
JsonRpcRequestInvalid
JsonRpcMethodNotFound
JsonRpcParamsInvalid
JsonRpcInternalError