Mulib/Documentation
Mulib Documentation
Mulib is a Python web application library. Mulib provides various functions and classes which implement WSGI applications for various Python types and MIME content types. The two main features of Mulib are object traversal over arbitrary Python types (such as dict, list, and string) using an extensible handler adapter registry, and content negotiation to arbitrary MIME content types (such as text/html and application/json) using the same extensible handler adapter registry.
Basics
To use Mulib in a wsgi environment, there are two different options. mulib.mu.Publisher(any_obj) is a class which takes any Python object as it's only argument, whose instances are WSGI applications which will traverse over the object graph rooted in that object. mulib.mu.delegate(env, start_response, any_obj, path_segments=None) is a function which takes a WSGI request, any Python object, and a tuple or list of path segments to traverse over the object. If path_segments is ommitted, the path in the WSGI environment PATH_INFO variable will be split on '/' and used for traversal.
Perhaps some examples will help to clarify. To create a WSGI application object which responds to two urls, 'hello' and 'foo', the following would be used:
Publisher example
from eventlet import api, wsgi
from mulib import mu
application = mu.Publisher({'hello': 'world', 'foo': 'bar'})
wsgi.server(api.tcp_listener(('', 8080)), application)
eventlet.wsgi is used as an example wsgi server, but any wsgi server may be used to serve this WSGI application. The application will respond to two urls: the url '/hello', to which it will reply 'world', and the url '/foo', to which it will reply 'bar'. This is because the handler registered for type dict knows show to turn url segments into accesses of dictionary keys. Note that the url '/foo/bar' would not be valid because the handler for type str does not allow child access since strings do not have conceptual children.
This is what is meant by object traversal; we start with a root Python object and look for a handler based on the object's type. We then call this handler, which may call other handlers if there are more path segments to consume, until we reach the leaf node.
Delegate Example
Another usage of Mulib would be inside an existing WSGI application. In this case, the mulib.mu.delegate function can be quite useful.
from eventlet import api, wsgi
from mulib import mu
def application(env, start_response):
return mu.delegate(env, start_response, "hello, world", ())
wsgi.server(api.tcp_listener(('', 8080)), application)
This will result in an application which responds to ALL urls with "hello, world". This is because we explicitly pass () as the path segments, which means mulib will ignore PATH_INFO entirely and assume the string "hello, world" is the leaf node immediately.
Content Negotiation Example
Here is another more complicated example, which highlights the content negotiation feature of mulib:
from eventlet import api, wsgi
from mulib import mu
def application(env, start_response):
return mu.delegate(env, start_response, {"hello": "world"}, ())
wsgi.server(api.tcp_listener(('', 8080)), application)
In this case, we delegate to a Python dictionary, but we still don't pass any path segments. This application will also respond to any URL, but the actual bytes which are sent in the response will be based on the result of content negotiation. content negotiation is a process where the HTTP client sends an Accept header containing a list of acceptable mime types along with weights indicating the browser's preferences. Mulib will look at the Python type of the object being traversed (in this case, a dict) and determine which handler to pull out of the adapter registry based on the mime type of the handler.
In the case of dict, mulib has several handlers registered for different mime types. application/json, text/html, and text/plain. If the browser specifies application/json as the content type, the result will be
{"hello": "world"}. However, if the browser specifies text/html as the content type, the result will be
<html><body><dl><dt>hello</dt><dd>world</dd></dl></body></html>
.
Subclassing mu.Handler
Sometimes, it is nice to write Python classes which implement a REST interface. mulib.mu.Handler provides an easy way to do this. There are three things you need to know about when subclassing mu.Handler.
First, by default mu.Handler will allow traversal to any attributes of self which do not start with an underscore (_).
Second, once an instance of mu.Handler has been selected as the leaf node, the REQUEST_METHOD is examined to determine which method to call on the Handler instance. If the REQUEST_METHOD is GET, _handle_GET(env, start_response) will be called. If the REQUEST_METHOD is PUT, _handle_PUT(env, start_response) will be called, and so on.
Implementing REST Example
import os.path
from eventlet import api, wsgi
from mulib import mu
def relative(filename):
return os.path.join(os.path.split(os.path.abspath(__file__))[0], filename)
class Baz(mu.Handler):
def _handle_GET(self, env, start_response):
start_response('200 OK', [('Content-type', 'text/plain')])
return ["Baz!\n"]
class Bar(mu.Handler):
index = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Url Hierarchy Example</title>
</head>
<body>
<a href="..">up</a>
<h1>Bar!</h1>
<a href="baz">baz</a>
</body>
</html>"""
baz = Baz()
class Foo(mu.Handler):
def _handle_GET(self, env, start_response):
start_response('200 OK', [('Content-type', 'text/plain')])
return ["Foo!\n"]
class Root(mu.Handler):
index = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Url Hierarchy Example</title>
</head>
<body>
<a href="foo">foo</a>
<a href="bar/">bar</a>
</body>
</html>"""
foo = Foo()
bar = Bar()
wsgi.server(
api.tcp_listener(('', 8080)), ## Socket to listen on
mu.Publisher(Root())) ## wsgi app to run
Customizing Handler traversal example
Finally, if you wish to customize traversal over your Handler subclass, override the _traverse(env, start_response, segments) method. Although the traverse method has a signature which does not exactly match the WSGI application signature, it's semantics are the same. If there are additional unhandled segments below what your Handler wants to handle, it's convenient to call the delegate function to dispatch the request to another handler.
"""This is a port of the web.py example from the homepage.
http://webpy.org/
Since mulib is now pure wsgi, it doesn't have nice request
and response abstractions. This example would be a lot nicer
if it used WebOb, a wsgi request/response abstraction.
"""
import cgi
from eventlet import api, wsgi
from mulib import mu, handlers
class HelloServer(handlers.Handler):
def _traverse(self, env, start_response, segments):
return mu.delegate(
env, start_response,
Hello('/'.join(segments)), ## This object will handle the request.
()) ## This is a tuple of the unhandled segments.
## We handled them all, so this is an empty tuple.
class Hello(handlers.Handler):
def __init__(self, who):
if not who:
who = 'world'
self.who = who
def _handle_GET(self, env, start_response):
times = cgi.parse_qs(env['QUERY_STRING']).get('times', [1])[0]
start_response('200 OK', [('Content-type', 'text/plain')])
for c in range(int(times)):
yield 'Hello, %s!\n' % self.who
wsgi.server(
api.tcp_listener(('', 8080)), ## Socket to listen on
mu.Publisher(HelloServer())) ## wsgi app to run
Handler Adapters
A handler adapter is a WSGI application callable which is associated with a Python type using the mu.set_handler(typ, callable, content_type='text/plain') function. Whenever mulib is traversing an object of type typ, or an object of type typ has been selected as the leaf node and content negotiation has selected the content type text/plain, the WSGI application callable will be called.
Handler Adapters Example
import os.path
from eventlet import api, wsgi
from mulib import mu
class MyClass(object):
def __init__(self, name):
self.name = name
def handle_myclass(env, start_response):
instance, path = mu.get_current(env)
if env['PATH_INFO'] != '/':
return mu.not_found(env, start_response)
start_response('200 OK', [('Content-type', 'text/plain')])
return ["Hello, %s!" % instance.name]
mu.set_handler(MyClass, handle_myclass)
wsgi.server(
api.tcp_listener(('', 8080)), ## Socket to listen on
mu.Publisher(MyClass('World')) ## wsgi app to run
Object Traversal Details
First, the environment variable 'mu.remaining_segments' is calculated by splitting the url segments from PATH_INFO. Then, a handler for the type of the mu environment variable 'mu.current_node' is selected from the mu.adapters.Handlers instance from the environment variable 'mu.handler_adapters' and called, until the wsgi environment variable 'mu.remanining_segments' is (), indicating that we have reached the leaf node. Once we have reached the leaf node, content negotiation is performed to actually render the response to the request.
Content Negotiation Details
Once the leaf node has been reached (indicated by setting the WSGI environment variable 'mu.remaining_segments' to ()), the Accept header is parsed and iterated. For each content type a handler is selected from 'mu.handler_adapters'. If a handler is available, that handler is the final WSGI application which will render the response.
Parsers
The mu.parsers WSGI environment variable should be set to a dictionary of MIME type to callable(str) function. If this environment variable is not set, the default parsers will be used (parsers for application/x-www-form-urlenpred and application/json). The function mu.parsed_body can be used to read the request body and parse it based on the Content-Type and the parsers dictionary.
The implementations of the handlers for dict and list use parsed_body to implement PUT, allowing dictionary and list values to be set to arbitrary objects.
Parsers Example
from mulib import mu
from eventlet import api, wsgi
root = {'hello':'Hello World', 'contacts': {}}
wsgi.server(api.tcp_listener(('', 5000)), mu.SiteMap(root))
With the above server running, execute the following curl commands in a shell:
curl -X PUT -H "Content-type: application/json" -d '{"Chuck" : { "Name": "Chuck", "Age":99, "Languages": ["Python", "C++"]}}' http://localhost:5000/contacts
Then, visiting the url http://localhost:5000/contacts will display the newly-uploaded data either in JSON or HTML formats.
Glossary
object traversal: The process of recursively selecting handlers based on the types of the objects in the object graph, starting at the root node and traversing over the path segments split from PATH_INFO.
content negotiation: The process of selecting a handler based on the Accept header given by the browser once object traversal has been completed.
leaf node: The object which was selected as the target of rendering for a WSGI request. content negotiation will be performed and the negotiated handler will be called to finalize and render the response.