Dispatchers

Dispatchers are responsible for translating incoming requests and dispatching them to the appropriate resources. They then take the response from the ResourceBase subclass and uses to appropriate adapter to create a response. Dispatchers are responsible for coupling ripozo with a web framework. As such, the dispatcher is not fully implemented in ripozo. Rather there is an abstract base class that must be implemented for the specific framework that is being used.

Example

When using a ripozo implementation for your preferred framework, registering the resource classes is very easy.

# Import your resource classes
from my_resources import MyResource, MyOtherResource

# Import the adapters that you want to use
from ripozo.dispatch.adapters import SirenAdapter, HalAdapter

# Initialize your Dispatcher (this will be different for
# different web frameworks.  Please look at the specific documentation
# for that framework.
# For example, in flask-ripozo it would be
# app = Flask(app)
# dispatcher = FlaskDispatcher(app)

# register your adapters, the first adapter is the default adapter
dispatcher.register_adapters(SirenAdapter, HalAdapter)

# Register your resource classes
dispatcher.register_resources(MyResource, MyOtherResource)

I wasn’t lying, it’s pretty basic.

Implementing a Dispatcher

So you’ve just discovered the next great python web framework. Unfortunately, nobody has developed a ripozo dispatcher implementation for it yet. Don’t despair! Implementing a ripozo dispatcher is theoretically quite simple. There is only one method and one property you need to implement.

The first is the base_url property. This is base_url that is used when constructing urls. For example, it might include the the host, port and base path (e.g. 'http://localhost:5000/api'). If you absolutely need to make it a method, you will need to overrided the dispatch method as well, since it expects it to be a property.

DispatcherBase.base_url
Returns:The base url including the domain and protocol This needs to be included so that the adapters can construct fully qualified urls. However, they have no way of directly identifying that so they need to be able to get it from the dispatcher.
Return type:unicode

The second piece you’ll need to implement is the register_route method. This is the method that is responsible for taking an individual route and relaying it to the webframework.

DispatcherBase.register_route(endpoint, endpoint_func=None, route=None, methods=None, **options)[source]

Registers an individual route on the framework. This method gives a specific framework the opportunity to actually dispatch the incoming requests appropriately.

Parameters:
  • endpoint (unicode) – The name of the endpoint
  • endpoint_func (method) – The endpoint_func that is responsible for actually performing the actions requested
  • route (unicode) – The route template for this endpoint
  • methods (list) – A list of the methods on this route that will point to the endpoint_funct
  • options (dict) – A dictionary of additional options.

For a real life example of implementing a dispatcher check out the flask dispatcher.

Dispatcher API

class ripozo.dispatch_base.DispatcherBase(auto_options=True, auto_options_name=u'AutoOptionsResource')[source]

This is an abstract base class that is responsible for handling the interface between a request and the resource as well as the interface between the resource and the response. A new subclass should be developed for every framework that ripozo is supposed to work with. Those extensions should be in separate repositories though. This specific base class is mostly for shortcuts and to give an idea of how to actually implement ripozo with a framework.

__init__(auto_options=True, auto_options_name=u'AutoOptionsResource')[source]
Parameters:
  • auto_options (bool) – Automatically builds out an options endpoint on the base url that points to all other resources.
  • auto_options_name (unicode) – The name of the auto options resource class. Available in cases of multiple dispatchers.
__weakref__

list of weak references to the object (if defined)

adapter_formats

Returns the mutable _adapter_formats. If the _adapter_formats property is None then it first sets cls._adapter_formats to an empty dictionary.

Return type:dict
base_url
Returns:The base url including the domain and protocol This needs to be included so that the adapters can construct fully qualified urls. However, they have no way of directly identifying that so they need to be able to get it from the dispatcher.
Return type:unicode
default_adapter
Returns:The AdapterBase subclass that is the default adapter to use when the client doesn’t explicitly request a specific adapter. If no default adapter is set when register_adapters is called, then the first adapter provided to register_adapters will be set as the default adapter.
Return type:AdapterBase
dispatch(endpoint_func, accepted_mimetypes, request, *args, **kwargs)[source]

A helper to dispatch the endpoint_func, get the ResourceBase subclass instance, get the appropriate AdapterBase subclass and return an instance created with the ResourceBase.

Parameters:
  • endpoint_func (method) – The endpoint_func is responsible for actually get the ResourceBase response
  • accepted_mimetypes (list) – The mime types accepted by the client. If none of the mimetypes provided are available the default adapter will be used.
  • request (RequestContainer) – The request object
  • args (list) – a list of args that wll be passed to the endpoint_func
  • kwargs (dict) – a dictionary of keyword args to pass to the endpoint_func
Returns:

an instance of an AdapterBase subclass that can be used to find

Return type:

get_adapter_for_type(accept_mimetypes)[source]

Gets the appropriate adapter class for the specified format type. For example, if the format_type was siren it would return the SirenAdapter. Returns the default adapter If it cannot not find an adapter for the format_type.

Parameters:accept_mimetypes (list) – A list of the mime types accepted by the client.
Returns:A BaseAdapter subclass for the best matched accept type.
Return type:type
register_adapters(*adapter_classes)[source]

Registers a list of valid adapter classes with this dispatcher. It will take the formats attribute from the AdapterBase subclass and use each of those as a key with the value pointing.

If _default_adapter is not set, then the first adapter_class will be the default adapter to use when returning responses.

Parameters:adapter_classes (list) – A list of subclasses of AdapterBase that specify what formats are available for this dispatcher
Raises:AdapterFormatAlreadyRegisteredException
register_resources(*classes)[source]

A shortcut for register multiple classes at once.

Parameters:classes (list) – A list of ResourceBase subclasses that are being registered with this dispatcher.
register_route(endpoint, endpoint_func=None, route=None, methods=None, **options)[source]

Registers an individual route on the framework. This method gives a specific framework the opportunity to actually dispatch the incoming requests appropriately.

Parameters:
  • endpoint (unicode) – The name of the endpoint
  • endpoint_func (method) – The endpoint_func that is responsible for actually performing the actions requested
  • route (unicode) – The route template for this endpoint
  • methods (list) – A list of the methods on this route that will point to the endpoint_funct
  • options (dict) – A dictionary of additional options.