path: root/pecan/hooks.py

import sys
from inspect   import getmembers
from webob.exc import HTTPFound

from util      import iscontroller, _cfg
from routing   import lookup_controller

__all__ = ['PecanHook', 'TransactionHook', 'HookController']


def walk_controller(root_class, controller, hooks):
    if not isinstance(controller, (int, dict)):
        for name, value in getmembers(controller):
            if name == 'controller': continue
            if name.startswith('__') and name.endswith('__'): continue
            
            if iscontroller(value):
                for hook in hooks:
                    value._pecan.setdefault('hooks', []).append(hook)
            elif hasattr(value, '__class__'):
                if name.startswith('__') and name.endswith('__'): continue
                walk_controller(root_class, value, hooks)


class HookController(object):
    '''
    A base class for controllers that would like to specify hooks on
    their controller methods. Simply create a list of hook objects 
    called ``__hooks__`` as a member of the controller's namespace.
    '''
    
    __hooks__ = []
    
    class __metaclass__(type):
        def __init__(cls, name, bases, dict_):
            walk_controller(cls, cls, dict_['__hooks__'])


class PecanHook(object):
    '''
    A base class for Pecan hooks. Inherit from this class to create your
    own hooks. Set a priority on a hook by setting the ``priority``
    attribute for the hook, which defaults to 100.
    '''
    
    priority = 100
    
    def on_route(self, state):
        '''
        Override this method to create a hook that gets called upon
        the start of routing.
        
        :param state: The Pecan ``state`` object for the current request.
        '''
        return
    
    def before(self, state):
        '''
        Override this method to create a hook that gets called after
        routing, but before the request gets passed to your controller.
        
        :param state: The Pecan ``state`` object for the current request.
        '''
        return
    
    def after(self, state):
        '''
        Override this method to create a hook that gets called after
        the request has been handled by the controller.
        
        :param state: The Pecan ``state`` object for the current request.
        '''
        return
    
    def on_error(self, state, e):
        '''
        Override this method to create a hook that gets called upon
        an exception being raised in your controller.
        
        :param state: The Pecan ``state`` object for the current request.
        :param e: The ``Exception`` object that was raised.
        '''
        return


class TransactionHook(PecanHook):
    '''
    A basic framework hook for supporting wrapping requests in
    transactions. By default, it will wrap all but ``GET`` and ``HEAD``
    requests in a transaction. Override the ``is_transactional`` method
    to define your own rules for what requests should be transactional.
    '''
    
    def __init__(self, start, start_ro, commit, rollback, clear):
        '''
        :param start: A callable that will bind to a writable database and start a transaction.
        :param start_ro: A callable that will bind to a readable database.
        :param commit: A callable that will commit the active transaction.
        :param rollback: A callable that will roll back the active transaction.
        :param clear: A callable that will clear your current context.
        '''
        
        self.start    = start
        self.start_ro = start_ro
        self.commit   = commit
        self.rollback = rollback
        self.clear    = clear

    def is_transactional(self, state):
        '''
        Decide if a request should be wrapped in a transaction, based
        upon the state of the request. By default, wraps all but ``GET``
        and ``HEAD`` requests in a transaction, along with respecting
        the ``transactional`` decorator from :mod:pecan.decorators.
        
        :param state: The Pecan state object for the current request.
        '''
        
        controller = getattr(state, 'controller', None)
        if controller:
            force_transactional = _cfg(controller).get('transactional', False)
        else:
            force_transactional = False

        if state.request.method not in ('GET', 'HEAD') or force_transactional:
            return True
        return False

    def on_route(self, state):
        state.request.error = False
        if self.is_transactional(state):
            state.request.transactional = True
            self.start()
        else:
            state.request.transactional = False
            self.start_ro()

    def before(self, state):
        if self.is_transactional(state) and not state.request.transactional:
            self.clear()
            state.request.transactional = True
            self.start()

    def on_error(self, state, e):
        #
        # If we should ignore redirects,
        # (e.g., shouldn't consider them rollback-worthy)
        # don't set `state.request.error = True`.
        #
        transactional_ignore_redirects = state.request.method not in ('GET', 'HEAD')
        if hasattr(state, 'controller'):
            transactional_ignore_redirects = _cfg(state.controller).get('transactional_ignore_redirects', transactional_ignore_redirects)
        if type(e) is HTTPFound and transactional_ignore_redirects is True:
            return
        state.request.error = True
    
    def after(self, state):
        if state.request.transactional:
            if state.request.error:
                self.rollback()
            else:
                self.commit()
                controller = getattr(state, 'controller', None)
                actions = _cfg(controller).get('after_commit', [])
                for action in actions:
                    action()
        self.clear()

class RequestViewerHook(PecanHook):
    '''
    Returns some information about what is going on in a single request.  It
    accepts specific items to report on but uses a default list of items when
    none are passed in.  Based on the requested ``url``, items can also be
    blacklisted.
    Configuration is flexible, can be passed in (or not) and can contain some or
    all the keys supported.

    ``items``
    ---------
    This key holds the items that this hook will display. When this key is passed 
    only the items in the list will be used.
    Valid items are *any* item that the ``request`` object holds, by default it uses
    the following:

    * url
    * method
    * response
    * context
    * params
    * hooks

    .. :note::
        This key should always use a ``list`` of items to use.

    ``blacklist``
    -------------
    This key holds items that will be blacklisted based on ``url``. If there is a need
    to ommit urls that start with `/javascript`, then this key would look like::

        'blacklist': ['/javascript']
        
    As many blacklisting items can be contained in the list. The hook will
    verify that the url is not starting with items in this list to display
    results, otherwise it will get ommited.

    .. :note::
        This key should always use a ``list`` of items to use.

    '''

    available  = [
            'url',
            'method',
            'response',
            'context',
            'params',
            'hooks',
    ]

    def __init__(self, config=None, writer=sys.stdout):
        '''
        :param config: A (optional) dictionary that can hold ``items`` and/or
                       ``blacklist`` keys.  
        :param writer: The stream writer to use. Can redirect output to other 
                       streams as long as the passed in stream has a ``write`` 
                       callable method.
        '''
        if not config:
            self.config = {'items' : self.available}
        else:
            self.config = config
        self.writer     = writer
        self.items      = self.config.get('items', self.available)
        self.blacklist  = self.config.get('blacklist', [])

    def after(self, state):
        responses = {
             'method'     : lambda self, state: state.request.method,
             'response'   : lambda self, state: state.response.status,
             'url'        : lambda self, state: state.request.path,
             'controller' : lambda self, state: self.get_controller(state),
             'context'    : lambda self, state: state.request.context,
             'params'     : lambda self, state: state.request.str_params.items(),
             'hooks'      : lambda self, state: self.format_hooks(state.app.hooks),
         }

        is_available = [
                i for i in self.items
                if i in self.available or hasattr(state.request, i)
        ]
        out          = []
        will_skip    = [i for i in self.blacklist if state.request.path.startswith(i)]

        if will_skip:
            return
        
        for request_info in is_available:
            try:
                value = responses.get(request_info) 
                if not value:
                    value = getattr(state.request, request_info)
                else:
                    value = value(self, state)
                out.append("%-12s - %s\n" % (request_info, value))
            except Exception, e:
                out.append("%-12s - %s\n" % (request_info, e))

        self.writer.write(''.join(out))
        self.writer.write('\n\n')

    def get_controller(self, state):
        '''
        Retrieves the actual controller name from the application
        Specific to Pecan (not available in the request object)
        '''
        path = state.request.pecan['routing_path'].split('/')[1:]
        controller, reminder = lookup_controller(state.app.root, path)
        return controller.__str__().split()[2]

    def format_hooks(self, hooks):
        '''
        Tries to format the hook objects to be more readable
        Specific to Pecan (not available in the request object)
        '''
        try:
            str_hooks = [str(i).split()[0].strip('<') for i in hooks]
            f_hooks = [i.split('.')[-1] for i in str_hooks if '.' in i]
        except:
            f_hooks = hooks 

        return f_hooks