'''Module milla.app

Please give me a docstring!

:Created: Mar 26, 2011
:Author: dustin
:Updated: $Date$
:Updater: $Author$
'''
import milla.dispatch.traversal
from webob.exc import HTTPNotFound, WSGIHTTPException
import webob

class Application(object):
    '''Represents a Milla web application
    
    Constructing an ``Application`` instance needs a dispatcher, or
    alternatively, a root object that will be passed to a new
    :py:class:``milla.dispatch.traversal.Traverser`. 
    
    :param root: A root object, passed to a traverser, which is
       automatically created if a root is given
    :param dispatcher: An object implementing the dispatcher protocol 
    
    ``Application`` instances are WSGI applications
    '''

    def __init__(self, root=None, dispatcher=None):
        if not dispatcher:
            if root:
                self.dispatcher = milla.dispatch.traversal.Traverser(root)
            else:
                raise ValueError('Must specify either a root object or a '
                                 'dispatcher')
        else:
            self.dispatcher = dispatcher

    def __call__(self, environ, start_response):
        try:
            func = self.dispatcher.resolve(environ['PATH_INFO'])
        except milla.dispatch.UnresolvedPath:
            return HTTPNotFound()(environ, start_response)

        request = webob.Request(environ)
        try:
            response = func(request)
        except WSGIHTTPException as e:
            return e(environ, start_response)

        if isinstance(response, basestring):
            response = webob.Response(response)

        start_response(response.status, response.headerlist)
        return response.app_iter