Writing handlers

Gramex handlers must inherit from gramex.handlers.BaseHandler. Here’s a simple custom handler saved in handlerutil.py:

from gramex.handlers import BaseHandler

class CustomHandler(BaseHandler):
    def get(self):
        self.write('This is a custom handler')

You can use this in gramex.yaml to map it to custom:

url:
  handler/custom:
    pattern: /$YAMLURL/custom
    handler: handlerutil.CustomHandler

Extending BaseHandler automatically provides these features:

Note: when naming your Python script, avoid namespaces such as services. or handlers. – these are already used by Gramex, and will not reflect your custom handler.

Initialization

Any arguments passed to the handler are passed to the setup() and initialize() methods. setup() is a class method that is called once. initialize() is an instance method that is called every request. For example:

class SetupHandler(BaseHandler):
    @classmethod
    def setup(cls, **kwargs):                           # setup() is called
        super(SetupHandler, cls).setup(**kwargs)        # You MUST call the BaseHandler setup
        cls.name = kwargs.get('name', 'NA')             # Perform any one-time setup here
        cls.count = Counter()

    def initialize(self, **kwargs):                     # initialize() is called with the same kwargs
        super(SetupHandler, self).initialize(**kwargs)  # You MUST call the BaseHandler initialize
        self.count[self.name] += 1                      # Perform any recurring operations here

    def get(self):
        self.write('Name %s was called %d times' % (self.name, self.count[self.name]))

… can be initialized at setup as follows:

url:
  handler/setup:
    pattern: /$YAMLURL/setup
    handler: handlerutil.SetupHandler
    kwargs: # This is passed to setup() and initialize() as **kwargs
      name: ABC

BaseHandler Attributes

The following attributes are available to BaseHandler instances:

Apart from these, there are other variables that may be created based on the configuration. These are not yet intended for general use:

Tornado handler attributes

These attributes are available to all Gramex handlers via Tornado: