path: root/flup/publisher.py

# Copyright (c) 2002, 2005, 2006 Allan Saddi <allan@saddi.com>
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
#
# $Id$

__author__ = 'Allan Saddi <allan@saddi.com>'
__version__ = '$Revision$'

import os
import inspect
import cgi
import types
from Cookie import SimpleCookie

__all__ = ['Request',
           'Response',
           'Transaction',
           'Publisher',
           'File',
           'Action',
           'Redirect',
           'InternalRedirect',
           'getexpected',
           'trimkw']

class NoDefault(object):
    """Sentinel object so we can distinguish None in keyword arguments."""
    pass

class Request(object):
    """
    Encapsulates data about the HTTP request.

    Supported attributes that originate from here: (The attributes are
    read-only, however you may modify the contents of environ.)
      transaction - Enclosing Transaction object.
      environ - Environment variables, as passed from WSGI adapter.
      method - Request method.
      publisherScriptName - SCRIPT_NAME of Publisher.
      scriptName - SCRIPT_NAME for request.
      pathInfo - PATH_INFO for request.
      form - Dictionary containing data from query string and/or POST request.
      cookie - Cookie from request.
    """
    def __init__(self, transaction, environ):
        self._transaction = transaction

        self._environ = environ
        self._publisherScriptName = environ.get('SCRIPT_NAME', '')

        self._form = {}
        self._parseFormData()

        # Is this safe? Will it ever raise exceptions?
        self._cookie = SimpleCookie(environ.get('HTTP_COOKIE', None))

    def _parseFormData(self):
        """
        Fills self._form with data from a FieldStorage. May be overidden to
        provide custom form processing. (Like no processing at all!)
        """
        # Parse query string and/or POST data.
        form = FieldStorage(fp=self._environ['wsgi.input'],
                            environ=self._environ, keep_blank_values=1)

        # Collapse FieldStorage into a simple dict.
        if form.list is not None:
            for field in form.list:
                # Wrap uploaded files
                if field.filename:
                    val = File(field)
                else:
                    val = field.value

                # Add File/value to args, constructing a list if there are
                # multiple values.
                if self._form.has_key(field.name):
                    self._form[field.name].append(val)
                else:
                    self._form[field.name] = [val]

        # Unwrap lists with a single item.
        for name,val in self._form.items():
            if len(val) == 1:
                self._form[name] = val[0]

    def _get_transaction(self):
        return self._transaction
    transaction = property(_get_transaction, None, None,
                           "Transaction associated with this Request")
    
    def _get_environ(self):
        return self._environ
    environ = property(_get_environ, None, None,
                       "Environment variables passed from adapter")
    
    def _get_method(self):
        return self._environ['REQUEST_METHOD']
    method = property(_get_method, None, None,
                      "Request method")
    
    def _get_publisherScriptName(self):
        return self._publisherScriptName
    publisherScriptName = property(_get_publisherScriptName, None, None,
                                   'SCRIPT_NAME of Publisher')

    def _get_scriptName(self):
        return self._environ.get('SCRIPT_NAME', '')
    scriptName = property(_get_scriptName, None, None,
                        "SCRIPT_NAME of request")

    def _get_pathInfo(self):
        return self._environ.get('PATH_INFO', '')
    pathInfo = property(_get_pathInfo, None, None,
                        "PATH_INFO of request")

    def _get_form(self):
        return self._form
    form = property(_get_form, None, None,
                    "Parsed GET/POST data")

    def _get_cookie(self):
        return self._cookie
    cookie = property(_get_cookie, None, None,
                      "Cookie received from client")

class Response(object):
    """
    Encapsulates response-related data.

    Supported attributes:
      transaction - Enclosing Transaction object.
      status - Response status code (and message).
      headers - Response headers.
      cookie - Response cookie.
      contentType - Content type of body.
      body - Response body. Must be an iterable that yields strings.

    Since there are multiple ways of passing response info back to
    Publisher, here is their defined precedence:
      status - headers['Status'] first, then status
      cookie - Any values set in this cookie are added to the headers in
        addition to existing Set-Cookie headers.
      contentType - headers['Content-Type'] first, then contentType. If
        neither are specified, defaults to 'text/html'.
      body - Return of function takes precedence. If function returns None,
        body is used instead.
    """
    _initialHeaders = {
        'Pragma': 'no-cache',
        'Cache-Control': 'no-cache'
        }

    def __init__(self, transaction):
        self._transaction = transaction

        self._status = '200 OK'

        # Initial response headers.
        self._headers = header_dict(self._initialHeaders)

        self._cookie = SimpleCookie()

        self.body = []

    def _get_transaction(self):
        return self._transaction
    transaction = property(_get_transaction, None, None,
                           "Transaction associated with this Response")
    
    def _get_status(self):
        status = self._headers.get('Status')
        if status is not None:
            return status
        return self._status
    def _set_status(self, value):
        if self._headers.has_key('Status'):
            self._headers['Status'] = value
        else:
            self._status = value
    status = property(_get_status, _set_status, None,
                      'Response status')

    def _get_headers(self):
        return self._headers
    headers = property(_get_headers, None, None,
                       "Headers to send in response")

    def _get_cookie(self):
        return self._cookie
    cookie = property(_get_cookie, None, None,
                      "Cookie to send in response")

    def _get_contentType(self):
        return self._headers.get('Content-Type', 'text/html')
    def _set_contentType(self, value):
        self._headers['Content-Type'] = value
    contentType = property(_get_contentType, _set_contentType, None,
                           'Content-Type of the response body')

class Transaction(object):
    """
    Encapsulates objects associated with a single transaction (Request,
    Response, and possibly a Session).

    Public attributes: (all read-only)
      request - Request object.
      response - Response object.

    If Publisher sits on top of SessionMiddleware, the public API of
    SessionService is also available through the Transaction object.
    """
    _requestClass = Request
    _responseClass = Response

    def __init__(self, publisher, environ):
        self._publisher = publisher
        self._request = self._requestClass(self, environ)
        self._response = self._responseClass(self)

        # Session support.
        self._sessionService = environ.get('com.saddi.service.session')
        if self._sessionService is not None:
            self.encodeURL = self._sessionService.encodeURL

    def _get_request(self):
        return self._request
    request = property(_get_request, None, None,
                       "Request associated with this Transaction")

    def _get_response(self):
        return self._response
    response = property(_get_response, None, None,
                        "Response associated with this Transaction")

    # Export SessionService API

    def _get_session(self):
        assert self._sessionService is not None, 'No session service found'
        return self._sessionService.session
    session = property(_get_session, None, None,
                       'Returns the Session object associated with this '
                       'client')

    def _get_hasSession(self):
        assert self._sessionService is not None, 'No session service found'
        return self._sessionService.hasSession
    hasSession = property(_get_hasSession, None, None,
                          'True if a Session currently exists for this client')

    def _get_isSessionNew(self):
        assert self._sessionService is not None, 'No session service found'
        return self._sessionService.isSessionNew
    isSessionNew = property(_get_isSessionNew, None, None,
                            'True if the Session was created in this '
                            'transaction')

    def _get_hasSessionExpired(self):
        assert self._sessionService is not None, 'No session service found'
        return self._sessionService.hasSessionExpired
    hasSessionExpired = property(_get_hasSessionExpired, None, None,
                                 'True if the client was associated with a '
                                 'non-existent Session')

    def _get_encodesSessionInURL(self):
        assert self._sessionService is not None, 'No session service found'
        return self._sessionService.encodesSessionInURL
    def _set_encodesSessionInURL(self, value):
        assert self._sessionService is not None, 'No session service found'
        self._sessionService.encodesSessionInURL = value
    encodesSessionInURL = property(_get_encodesSessionInURL,
                                   _set_encodesSessionInURL, None,
                                   'True if the Session ID should be encoded '
                                   'in the URL')

    def prepare(self):
        """
        Called before resolved function is invoked. If overridden,
        super's prepare() MUST be called and it must be called first.
        """
        # Pass form values as keyword arguments.
        args = dict(self._request.form)

        # Pass Transaction to function if it wants it.
        args['transaction'] = args['trans'] = self

        self._args = args

    def call(self, func, args):
        """
        May be overridden to provide custom exception handling and/or
        per-request additions, e.g. opening a database connection,
        starting a transaction, etc.
        """
        # Trim down keywords to only what the callable expects.
        expected, varkw = getexpected(func)
        trimkw(args, expected, varkw)

        return func(**args)

    def run(self, func):
        """
        Execute the function, doing any Action processing and also
        post-processing the function/Action's return value.
        """
        try:
            # Call the function.
            result = self.call(func, self._args)
        except Action, a:
            # Caught an Action, have it do whatever it does
            result = a.run(self)

        response = self._response
        headers = response.headers

        if result is not None:
            if type(result) in types.StringTypes:
                assert type(result) is str, 'result cannot be unicode!'

                # Set Content-Length, if needed
                if not headers.has_key('Content-Length'):
                    headers['Content-Length'] = str(len(result))

                # Wrap in list for WSGI
                response.body = [result]
            else:
                if __debug__:
                    try:
                        iter(result)
                    except TypeError:
                        raise AssertionError, 'result not iterable!'
                response.body = result

        # If result was None, assume response.body was appropriately set.

    def finish(self):
        """
        Called after resolved function returns, but before response is
        sent. If overridden, super's finish() should be called last.
        """
        response = self._response
        headers = response.headers

        # Copy cookie to headers.
        items = response.cookie.items()
        items.sort()
        for name,morsel in items:
            headers.add('Set-Cookie', morsel.OutputString())

        # If there is a Status header, transfer its value to response.status.
        # It must not remain in the headers!
        status = headers.get('Status', NoDefault)
        if status is not NoDefault:
            del headers['Status']
            response.status = status

        code = int(response.status[:3])
        # Check if it's a response that must not include a body.
        # (See 4.3 in RFC2068.)
        if code / 100 == 1 or code in (204, 304):
            # Remove any trace of the response body, if that's the case.
            for header,value in headers.items():
                if header.lower().startswith('content-'):
                    del headers[header]
            response.body = []
        else:
            if self._request.method == 'HEAD':
                # HEAD reponse must not return a body (but the headers must be
                # kept intact).
                response.body = []

            # Add Content-Type, if missing.
            if not headers.has_key('Content-Type'):
                headers['Content-Type'] = response.contentType

        # If we have a close() method, ensure that it is called.
        if hasattr(self, 'close'):
            response.body = _addClose(response.body, self.close)

class Publisher(object):
    """
    WSGI application that publishes Python functions as web pages. Constructor
    takes an instance of a concrete subclass of Resolver, which is responsible
    for mapping requests to functions.

    Query string/POST data values are passed to the function as keyword
    arguments. If the function does not support variable keywords (e.g.
    does not have a ** parameter), the function will only be passed
    keywords which it expects. It is recommended that all keyword parameters
    have defaults so that missing form data does not raise an exception.

    A Transaction instance is always passed to the function via the
    "transaction" or "trans" keywords. See the Transaction, Request, and
    Response classes.

    Valid return types for the function are: a string, None, or an iterable
    that yields strings. If returning None, it is expected that Response.body
    has been appropriately set. (It must be an iterable that yields strings.)

    An instance of Publisher itself is the WSGI application.
    """
    _transactionClass = Transaction

    def __init__(self, resolver, transactionClass=None, error404=None):
        self._resolver = resolver

        if transactionClass is not None:
            self._transactionClass = transactionClass

        if error404 is not None:
            self._error404 = error404

    def _get_resolver(self):
        return self._resolver
    resolver = property(_get_resolver, None, None,
                        'Associated Resolver for this Publisher')

    def __call__(self, environ, start_response):
        """
        WSGI application interface. Creates a Transaction (which does most
        of the work) and sends the response.
        """
        # Set up a Transaction.
        transaction = self._transactionClass(self, environ)

        # Make any needed preparations.
        transaction.prepare()

        redirect = False

        while True:
            # Attempt to resolve the function.
            func = self._resolver.resolve(transaction.request,
                                          redirect=redirect)
            if func is None:
                func = self._error404

            try:
                # Call the function.
                transaction.run(func)
            except InternalRedirect, r:
                # Internal redirect. Set up environment and resolve again.
                environ['SCRIPT_NAME'] = transaction.request.publisherScriptName
                environ['PATH_INFO'] = r.pathInfo
                redirect = True
            else:
                break

        # Give Transaction a chance to do modify/add to the response.
        transaction.finish()

        # Transform headers into a list. (Need to pay attention to
        # multiple values.)
        responseHeaders = []
        for key,value in transaction.response.headers.items():
            if type(value) is list:
                for v in value:
                    responseHeaders.append((key, v))
            else:
                responseHeaders.append((key, value))

        start_response(transaction.response.status, responseHeaders)
        return transaction.response.body

    def _error404(self, transaction):
        """Error page to display when resolver fails."""
        transaction.response.status = '404 Not Found'
        request_uri = transaction.request.environ.get('REQUEST_URI')
        if request_uri is None:
            request_uri = transaction.request.environ.get('SCRIPT_NAME', '') + \
                          transaction.request.environ.get('PATH_INFO', '')
        return ["""<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
The requested URL %s was not found on this server.<p>
<hr>
%s</body></html>
""" % (request_uri, transaction.request.environ.get('SERVER_SIGNATURE', ''))]

class File(object):
    """
    Wrapper so we can identify uploaded files.
    """
    def __init__(self, field):
        self.filename = field.filename
        self.file = field.file
        self.type = field.type
        self.type_options = field.type_options
        self.headers = field.headers
        
class Action(Exception):
    """
    Abstract base class for 'Actions', which are just exceptions.
    Within Publisher, Actions have no inherent meaning and are used
    as a shortcut to perform specific actions where it's ok for a
    function to abruptly halt. (Like redirects or displaying an
    error page.)

    I don't know if using exceptions this way is good form (something
    tells me no ;) Their usage isn't really required, but they're
    convenient in some situations.
    """
    def run(self, transaction):
        """Override to perform your action."""
        raise NotImplementedError, self.__class__.__name__ + '.run'

class Redirect(Action):
    """
    Redirect to the given URL.
    """
    def __init__(self, url, permanent=False):
        self._url = url
        self._permanent = permanent

    def run(self, transaction):
        response = transaction.response
        response.status = self._permanent and '301 Moved Permanently' or \
                          '302 Moved Temporarily'
        response.headers.reset()
        response.headers['Location'] = self._url
        response.contentType = 'text/html'
        return ["""<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>%s</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a href="%s">here</a>.</p>
<hr>
%s</body></html>
""" % (response.status, self._url,
       transaction.request.environ.get('SERVER_SIGNATURE', ''))]

class InternalRedirect(Exception):
    """
    An internal redirect using a new PATH_INFO (relative to Publisher's
    SCRIPT_NAME).

    When handling an InternalRedirect, the behavior of all included
    Resolvers is to expose a larger set of callables (that would normally
    be hidden). Therefore, it is important that you set pathInfo securely -
    preferably, it should not depend on any data from the request. Ideally,
    pathInfo should be a constant string.
    """
    def __init__(self, pathInfo):
        self.pathInfo = pathInfo

class FieldStorage(cgi.FieldStorage):
    def __init__(self, *args, **kw):
        """
        cgi.FieldStorage only parses the query string during a GET or HEAD
        request. Fix this.
        """
        cgi.FieldStorage.__init__(self, *args, **kw)

        environ = kw.get('environ') or os.environ
        method = environ.get('REQUEST_METHOD', 'GET').upper()
        if method not in ('GET', 'HEAD'): # cgi.FieldStorage already parsed?
            qs = environ.get('QUERY_STRING')
            if qs:
                if self.list is None:
                    self.list = []
                for key,value in cgi.parse_qsl(qs, self.keep_blank_values,
                                               self.strict_parsing):
                    self.list.append(cgi.MiniFieldStorage(key, value))

class header_dict(dict):
    """
    This is essentially a case-insensitive dictionary, with some additions
    geared towards supporting HTTP headers (like __str__(), add(), and
    reset()).
    """
    def __init__(self, val=None):
        """
        If initialized with an existing dictionary, calling reset() will
        reset our contents back to that initial dictionary.
        """
        dict.__init__(self)
        self._keymap = {}
        if val is None:
            val = {}
        self.update(val)
        self._reset_state = dict(val)
        
    def __contains__(self, key):
        return key.lower() in self._keymap

    def __delitem__(self, key):
        lower_key = key.lower()
        real_key = self._keymap.get(lower_key)
        if real_key is None:
            raise KeyError, key
        del self._keymap[lower_key]
        dict.__delitem__(self, real_key)

    def __getitem__(self, key):
        lower_key = key.lower()
        real_key = self._keymap.get(lower_key)
        if real_key is None:
            raise KeyError, key
        return dict.__getitem__(self, real_key)

    def __str__(self):
        """Output as HTTP headers."""
        s = ''
        for k,v in self.items():
            if type(v) is list:
                for i in v:
                    s += '%s: %s\n' % (k, i)
            else:
                s += '%s: %s\n' % (k, v)
        return s
    
    def __setitem__(self, key, value):
        lower_key = key.lower()
        real_key = self._keymap.get(lower_key)
        if real_key is None:
            self._keymap[lower_key] = key
            dict.__setitem__(self, key, value)
        else:
            dict.__setitem__(self, real_key, value)

    def clear(self):
        self._keymap.clear()
        dict.clear(self)

    def copy(self):
        c = self.__class__(self)
        c._reset_state = self._reset_state
        return c

    def get(self, key, failobj=None):
        lower_key = key.lower()
        real_key = self._keymap.get(lower_key)
        if real_key is None:
            return failobj
        return dict.__getitem__(self, real_key)
    
    def has_key(self, key):
        return key.lower() in self._keymap

    def setdefault(self, key, failobj=None):
        lower_key = key.lower()
        real_key = self._keymap.get(lower_key)
        if real_key is None:
            self._keymap[lower_key] = key
            dict.__setitem__(self, key, failobj)
            return failobj
        else:
            return dict.__getitem__(self, real_key)
        
    def update(self, d):
        for k,v in d.items():
            self[k] = v
            
    def add(self, key, value):
        """
        Add a new header value. Does not overwrite previous value of header
        (in contrast to __setitem__()).
        """
        if self.has_key(key):
            if type(self[key]) is list:
                self[key].append(value)
            else:
                self[key] = [self[key], value]
        else:
            self[key] = value

    def reset(self):
        """Reset contents to that at the time this instance was created."""
        self.clear()
        self.update(self._reset_state)

def _addClose(appIter, closeFunc):
    """
    Wraps an iterator so that its close() method calls closeFunc. Respects
    the existence of __len__ and the iterator's own close() method.

    Need to use metaclass magic because __len__ and next are not
    recognized unless they're part of the class. (Can't assign at
    __init__ time.)
    """
    class metaIterWrapper(type):
        def __init__(cls, name, bases, clsdict):
            super(metaIterWrapper, cls).__init__(name, bases, clsdict)
            if hasattr(appIter, '__len__'):
                cls.__len__ = appIter.__len__
            cls.next = iter(appIter).next
            if hasattr(appIter, 'close'):
                def _close(self):
                    appIter.close()
                    closeFunc()
                cls.close = _close
            else:
                cls.close = closeFunc

    class iterWrapper(object):
        __metaclass__ = metaIterWrapper
        def __iter__(self):
            return self

    return iterWrapper()

# Utilities which may be useful outside of Publisher? Perhaps for decorators...

def getexpected(func):
    """
    Returns as a 2-tuple the passed in object's expected arguments and
    whether or not it accepts variable keywords.
    """
    assert callable(func), 'object not callable'

    if not inspect.isclass(func):
        # At this point, we assume func is either a function, method, or
        # callable instance.
        if not inspect.isfunction(func) and not inspect.ismethod(func):
            func = getattr(func, '__call__') # When would this fail?

        argspec = inspect.getargspec(func)
        expected, varkw = argspec[0], argspec[2] is not None
        if inspect.ismethod(func):
            expected = expected[1:]
    else:
        # A class. Try to figure out the calling conventions of the
        # constructor.
        init = getattr(func, '__init__', None)
        # Sigh, this is getting into the realm of black magic...
        if init is not None and inspect.ismethod(init):
            argspec = inspect.getargspec(init)
            expected, varkw = argspec[0], argspec[2] is not None
            expected = expected[1:]
        else:
            expected, varkw = [], False

    return expected, varkw

def trimkw(kw, expected, varkw):
    """
    If necessary, trims down a dictionary of keyword arguments to only
    what's expected.
    """
    if not varkw: # Trimming only necessary if it doesn't accept variable kw
        for name in kw.keys():
            if name not in expected:
                del kw[name]