Documentation for pulsar 0.9.2. For development docs, go here.
Routing is the process of matching and parsing a URL to something we can use.
Pulsar provides a flexible integrated
routing system you can use for that. It works by creating a
Router
instance with its own rule
and, optionally, additional
sub-routers for handling additional urls:
class Page(Router):
response_content_types = RouterParam(('text/html',
'text/plain',
'application/json'))
def get(self, request):
"This method handle request with get-method"
...
def post(self, request):
"This method handle request with post-method"
...
middleware = Page('/bla')
The middleware constructed in the snippet above
handles get
and post
methods at the /bla
url.
The Router
introduces a new element into pulsar WSGI handlers, the
wsgi request, a light-weight wrapper of the
WSGI environ.
For an exaustive example on how to use the Router
middleware make sure
you check out the HttpBin example.
pulsar.apps.wsgi.routers.
Router
(rule, *routes, **parameters)[source]¶A WSGI middleware to handle client requests on multiple routes.
The user must implement the HTTP methods
required by the application. For example if the route needs to
serve a GET
request, the get(self, request)
method must
be implemented.
Parameters: |
---|
rule_methods
¶A class attribute built during class creation. It is an ordered
dictionary mapping method names with a five-elements tuple
containing information
about a child route (See the route
decorator).
response_content_types
¶A list/tuple of possible content types of a response to a client request.
The client request must accept at least one of the response content
types, otherwise an HTTP 415
exception occurs.
response_wrapper
¶Optional function which wraps all handlers of this Router
.
The function must accept two parameters, the original handler
and the WsgiRequest
:
def response_wrapper(handler, request):
...
return handler(request)
full_route
¶The full route
for this Router
.
It includes the parent
portion of the route if a parent
router is available.
rule
¶The full rule
string for this Router
.
It includes the parent
portion of the rule if a parent
router is available.
path
(**urlargs)[source]¶The full path of this Router
.
It includes the parent
portion of url if a parent router
is available.
content_type
(request)[source]¶Evaluate the content type for the response to a client request
.
The method uses the response_content_types
parameter of
accepted content types and the content types accepted by the client
request
and figures out the best match.
resolve
(path, urlargs=None)[source]¶Resolve a path and return a (handler, urlargs)
tuple or
None
if the path could not be resolved.
response
(environ, args)[source]¶Once the resolve()
method has matched the correct
Router
for serving the request, this matched router invokes
this method to produce the WSGI response.
get_route
(name)[source]¶Get a child Router
by its name
.
This method search child routes recursively.
link
(*args, **urlargs)[source]¶Return an anchor Html
element with the href attribute
set to the url of this Router
.
make_router
(rule, method=None, handler=None, cls=None, name=None, **params)[source]¶Create a new Router
from a rule
and parameters.
This method is used during initialisation when building child
Routers from the rule_methods
.
The MediaRouter
is a specialised Router
for serving static
files such ass css
, javascript
, images and so forth.
pulsar.apps.wsgi.routers.
MediaRouter
(rule, path, show_indexes=False, default_suffix=None, default_file='index.html', raise_404=True, **params)[source]¶A Router
for serving static media files from a given
directory.
Parameters: |
|
---|
path
¶The file-system path of the media files to serve.
show_indexes
¶If True
, the router will serve media file directories as
well as media files.
default_file
¶The default file to serve when a directory is requested.
pulsar.apps.wsgi.routers.
RouterParam
(value=None)[source]¶A RouterParam
is a way to flag a Router
parameter
so that children can inherit the value if they don’t define their own.
A RouterParam
is always defined as a class attribute and it
is processed by the Router
metaclass and stored in a dictionary
available as parameter
class attribute.
value
¶The value associated with this RouterParam
. THis is the value
stored in the Router.parameters
dictionary at key given by
the class attribute specified in the class definition.
Routing classes for matching and parsing urls.
Note
The route
module was originally from the routing
module in werkzeug. Original License:
copyright (c) 2011 by the Werkzeug Team. License BSD
A Route
is a class for relative url paths:
r1 = Route('bla')
r2 = Route('bla/foo')
Integers:
# accept any integer
Route('<int:size>')
# accept an integer between 1 and 200 only
Route('<int(min=1,max=200):size>')
Paths:
# accept any path (including slashes)
Route('<path:pages>')
Route('<path:pages>/edit')
pulsar.apps.wsgi.route.
route
(rule=None, method=None, defaults=None, position=None, **parameters)[source]¶Decorator to create a child route from a Router
method.
Typical usage:
from pulsar.apps.wsgi import Router, route
class View(Router):
def get(self, request):
...
@route()
def foo(self, request):
...
@route('/bla', method='post')
def handle2(self, request):
...
In this example, View
is the parent router which handle get
requests only.
The decorator injects the rule_method
attribute to the
method it decorates. The attribute is a five elements tuple
which contains the Route
, the HTTP method
, a
dictionary of additional parameters
, position
and
the order
. Position and order are internal integers used by the
Router
when deciding the order of url matching.
If position
is not passed,
the order will be given by the position of each method in the
Router
class.
The decorated method are stored in the Router.rule_methods
class
attribute.
>>> len(View.rule_methods)
2
>>> View.rule_methods['foo'].rule
/foo
>>> View.rule_methods['foo'].method
'get'
>>> View.rule_methods['handle2'].rule
/bla
>>> View.rule_methods['handle2'].method
'post'
Check the HttpBin example for a sample usage.
Parameters: |
|
---|
pulsar.apps.wsgi.route.
Route
(rule, defaults=None)[source]¶A Route is a class with a relative path
.
Parameters: |
|
---|
is_leaf
¶If True
, the route is equivalent to a file.
For example /bla/foo
rule
¶The rule string, does not include the initial '/'
path
¶The full rule for this route including initial '/'
.
variables
¶a set of variable names for this route. If the route has no variables, the set is empty.