how to read openstack code : routes

xajh32y

　　When coding a web system, you have to think about an important problem, how to map urls to logic.
　　Openstack use routes to solve this problem.

What is routes
　　Routes is a python package used to map urls to program logic. Normally this is the web framework`s responsibility, so besides openstack, routes is also used in several other python web frameworks.

Quick start
　　

>>> from routes import Mapper　　
>>> map = Mapper()
　　
>>> map.connect('route_name_update_net', '/nets/{net_id}', controller='nets_controller', conditions=dict(method=['PUT']), self_defined_key='self_defined_value')
　　# Above code created a route named "route_name_update_net"
　　# It match any two component urls started with /nets
　　# Controller which will process the request is nets_controller
　　# Conditions parameter restrict the route only accept PUT request
　　

　　
>>> map.match('/nets/123')
　　
{'controller': u'nets_controller', 'net_id': u'123', "self_defined_key":"self_defined_value"}
　　# As you can see, the url which match the route will return a dict. The dict contains the controller information and necessary var
　　# The self_defined_key and self_defined_value also included.
　　

　　
>>> print map
　　
Route name            Methods Path         
　　
route_name_update_net PUT     /nets/{net_id}
　　
>>>
　　

Basic usage

Requirements
　　Some times you want to restrict the path var, you can use the requirements parameter in below ways
　　

map.connect(R"/download/{platform:windows|mac}/{filename}")　　

　　This line restrict the platform var could only be windows or mac. You can also write it in below way
　　

map.connect("/download/{platform}/{filename}", requirements={"platform": R"windows|mac"})　　

　　The R char here is very important. Without it you may need to double your slash in your url.
　　Once you restrict your route, you can try it like below:
　　

# The platform must be windows or mac so below url match　　
>>> map.match('/download/windows/myfile')
　　
{'platform': u'windows', 'filename': u'myfile'}
　　
# The linux is not valid here so does not match
　　
>>> map.match('/download/linux/myfile')
　　

PATH_INFO
　　In WSIG env, the url information is stored in the environ dict with key PATH_INFO.
　　
Routes treat the path_info specially. When the “path_info” variable is used at the end of the URL, Routes moves everything preceding it into the “SCRIPT_NAME” environment variable. This is useful when delegating to another WSGI application that does its own routing: the subapplication will route on the remainder of the URL rather than the entire URL
　　For example
　　

>>> from routes import Mapper　　
>>> map=Mapper()
　　
>>> map.connect('/classes/{path_info:.*}')
　　
>>> map.match('/classes/students/tom')
　　
{'path_info': 'students/tom'}
　　
>>>
　　

　　The subsequent system will see PATH_INFO: /students/tom and SCRIPT_NAME:classes. So the sub system can use its own route system.

Format extensions
　　Consider to design a url /neutron/networks/{network_id} which will used to access the network resource. The network can be returned in JSON format or XML format. So we can do it in routes like this:
　　

>>> from routes import Mapper　　
>>> map=Mapper()
　　
>>>
　　
>>> map.connect('/neutron/networks/{network_id}{.format:json|xml}')
　　
>>> map.match('/neutron/networks/123.json')
　　
{'network_id': u'123', 'format': u'json'}
　　
>>> map.match('/neutron/networks/123.xml')
　　
{'network_id': u'123', 'format': u'xml'}
　　
>>> map.match('/neutron/networks/123.html')
　　
{'network_id': u'123.html', 'format': None}
　　

　　Use the format parameter to specify the resource format

RESTful
　　Use routes can generate restful routes very conveniently
　　

>>> from routes import Mapper　　
>>> map=Mapper()
　　
>>> map.resource('net','nets')
　　
>>> print map
　　
Route name         Methods Path                     
　　POST    /nets.:(format)           
　　POST    /nets                     
　　
formatted_nets     GET     /nets.:(format)           
　　
nets               GET     /nets                     
　　
formatted_new_net  GET     /nets/new.:(format)      
　　
new_net            GET     /nets/new                 
　　PUT     /nets/:(id).:(format)     
　　PUT     /nets/:(id)               
　　DELETE  /nets/:(id).:(format)     
　　DELETE  /nets/:(id)               
　　
formatted_edit_net GET     /nets/:(id)/edit.:(format)
　　
edit_net           GET     /nets/:(id)/edit         
　　
formatted_net      GET     /nets/:(id).:(format)     
　　
net                GET     /nets/:(id)
　　

　　The first parameter is resource name also called member in RESTful
　　
The second is the plural of resource name which is also called collection in RESTful
　　the resource function have several parameters and we will learn them one by one

controller
　　This parameter specify the controller to handle the request. For example:
　　

>>> map=Mapper()　　
>>> map.resource('net','nets', controller='net_controller')
　　
>>> map.match('/nets/123')
　　
{'action': u'update', 'controller': u'net_controller', 'id': u'123'}
　　

collection
　　This parameter add more additional urls for the collection operations. For example:
　　Before use the parameter the map is like below
　　

>>> map=Mapper()　　
>>> map.resource('net','nets', controller='net_controller')
　　
>>> print map
　　
Route name         Methods Path                     
　　POST    /nets.:(format)           
　　POST    /nets                     
　　
formatted_nets     GET     /nets.:(format)           
　　
nets               GET     /nets                     
　　
formatted_new_net  GET     /nets/new.:(format)      
　　
new_net            GET     /nets/new                 
　　PUT     /nets/:(id).:(format)     
　　PUT     /nets/:(id)               
　　DELETE  /nets/:(id).:(format)     
　　DELETE  /nets/:(id)               
　　
formatted_edit_net GET     /nets/:(id)/edit.:(format)
　　
edit_net           GET     /nets/:(id)/edit         
　　
formatted_net      GET     /nets/:(id).:(format)     
　　
net                GET     /nets/:(id)               
　　

　　After we add the collection parameter
　　

>>> map.resource('net','nets', controller='net_controller', collection={'subnets':'POST'})　　
>>> print map
　　
Route name             Methods Path                     
　　
formatted_subnets_nets POST    /nets/subnets.:(format)   
　　
subnets_nets           POST    /nets/subnets            
　　POST    /nets.:(format)           
　　POST    /nets                     
　　
formatted_nets         GET     /nets.:(format)           
　　
nets                   GET     /nets                     
　　
formatted_new_net      GET     /nets/new.:(format)      
　　
new_net                GET     /nets/new                 
　　PUT     /nets/:(id).:(format)     
　　PUT     /nets/:(id)               
　　DELETE  /nets/:(id).:(format)     
　　DELETE  /nets/:(id)               
　　
formatted_edit_net     GET     /nets/:(id)/edit.:(format)
　　
edit_net               GET     /nets/:(id)/edit         
　　
formatted_net          GET     /nets/:(id).:(format)     
　　
net                    GET     /nets/:(id)            
　　

　　The collection operation can mathc /nets/subnets on POST method.

member
　　

>>> map=Mapper()　　
>>> map.resource('net','nets', controller='net_controller', member={'subnets':'POST'})
　　
>>> print map
　　
Route name            Methods Path                        
　　POST    /nets.:(format)              
　　POST    /nets                        
　　
formatted_nets        GET     /nets.:(format)              
　　
nets                  GET     /nets                        
　　
formatted_new_net     GET     /nets/new.:(format)         
　　
new_net               GET     /nets/new                    
　　PUT     /nets/:(id).:(format)        
　　PUT     /nets/:(id)                  
　　
formatted_subnets_net POST    /nets/:(id)/subnets.:(format)
　　
subnets_net           POST    /nets/:(id)/subnets         
　　DELETE  /nets/:(id).:(format)        
　　DELETE  /nets/:(id)                  
　　
formatted_edit_net    GET     /nets/:(id)/edit.:(format)   
　　
edit_net              GET     /nets/:(id)/edit            
　　
formatted_net         GET     /nets/:(id).:(format)        
　　
net                   GET     /nets/:(id)                  
　　

　　After use member parameter, the member operation can match /nets/{id}/subnets

path_prefix and name_prefix
　　This two parameter are used together. For example:
　　

>>> map=Mapper()　　
>>> map.resource("message", "messages", controller="categories", path_prefix="/category/{category_id}", name_prefix="category_")
　　
>>> print map
　　
Route name                      Methods Path                                                
　　POST    /category/{category_id}/messages.:(format)           
　　POST    /category/{category_id}/messages                     
　　
formatted_category_messages     GET     /category/{category_id}/messages.:(format)           
　　
category_messages               GET     /category/{category_id}/messages                     
　　
formatted_category_new_message  GET     /category/{category_id}/messages/new.:(format)      
　　
category_new_message            GET     /category/{category_id}/messages/new                 
　　PUT     /category/{category_id}/messages/:(id).:(format)     
　　PUT     /category/{category_id}/messages/:(id)               
　　DELETE  /category/{category_id}/messages/:(id).:(format)     
　　DELETE  /category/{category_id}/messages/:(id)               
　　
formatted_category_edit_message GET     /category/{category_id}/messages/:(id)/edit.:(format)
　　
category_edit_message           GET     /category/{category_id}/messages/:(id)/edit         
　　
formatted_category_message      GET     /category/{category_id}/messages/:(id).:(format)     
　　
category_message                GET     /category/{category_id}/messages/:(id)           
　　

　　The path_prefix add a url prefix to the urls that can be matched. The name_prefix is the prefix of route name.
　　They actually are parent resource of message.

Parent resource
　　

>>> from routes import Mapper　　
>>> map=Mapper()
　　
>>> map.resource('location', 'locations', parent_resource=dict(member_name='region', collection_name='regions'))
　　
>>> print map
　　
Route name                     Methods Path                                             
　　POST    /regions/:region_id/locations.:(format)           
　　POST    /regions/:region_id/locations                     
　　
formatted_region_locations     GET     /regions/:region_id/locations.:(format)           
　　
region_locations               GET     /regions/:region_id/locations                     
　　
formatted_region_new_location  GET     /regions/:region_id/locations/new.:(format)      
　　
region_new_location            GET     /regions/:region_id/locations/new                 
　　PUT     /regions/:region_id/locations/:(id).:(format)     
　　PUT     /regions/:region_id/locations/:(id)               
　　DELETE  /regions/:region_id/locations/:(id).:(format)     
　　DELETE  /regions/:region_id/locations/:(id)               
　　
formatted_region_edit_location GET     /regions/:region_id/locations/:(id)/edit.:(format)
　　
region_edit_location           GET     /regions/:region_id/locations/:(id)/edit         
　　
formatted_region_location      GET     /regions/:region_id/locations/:(id).:(format)     
　　
region_location                GET     /regions/:region_id/locations/:(id)               
　　

　　This is the same as path_prefix and name_prefix. The path_prefix here is /regions/{region_id} and name_prefix is region_
　　openstack use routes to map url to controller, so it is necessary to know about routes. Routes are came from Ruby on rails. It is rewritten in python. So docs about routes are not very clear might because the author think we should learn Ruby on rails routes first.

Submapper
　　submapper is a lazy way to write code. See examples below:
　　You want to generate a series route， they have common attributes like
　　

controller: common_controller　　
action: index
　　
path_prefix: api/v2
　　
conditions: {'method':'GET'}
　　

　　You can write the code in this way
　　

>>> from routes import Mapper　　
>>> map = Mapper()
　　
>>> with map.submapper(controller='common_controller', action='index', path_prefix='api/v2/', contidions={'method':'GET'}) as submapper:
　　
...     submapper.connect('api/v2/'+'nets', 'nets')
　　
...     submapper.connect('api/v2/'+'subnets', 'subnets')
　　
...
　　
>>> print map
　　
Route name     Methods Path         
　　
api/v2/nets            api/v2/nets   
　　
api/v2/subnets         api/v2/subnets
　　

　　In this way you can put the common attributes in submapper.