4.2 Handlers: Resource-based Extension

Aspen handlers are WSGI applications that are associated with files on the filesystem according to arbitrary rules. This enables ASP/PHP-style web development, where URLs map literally to the filesystem, and the response is generated by somehow processing a filesystem resource.

The __/etc/handlers.conf file begins with an anonymous "rules" section, which is a newline-separated list of white-space-separated rule name/object name pairs. Rule names can be any string without whitespace. Each object name (in colon notation) specifies a rule, a callable taking a Python file object and an arbitrary predicate string, and returning True or False.

Following the rule specification are sections specifying handlers, which as mentioned above are WSGI callables. When called, handlers receive the following additional objects in environ:

key	value
`aspen.fp`	the filesystem resource as a `file` object, positioned at zero
`aspen.website`	the `Website` instance

The name of each section specifies a handler (a WSGI callable) in colon notation. The body of each section is a newline-separated list of conditions under which this handler is to be called. Fundamentally, these conditions are made up of a rule name as defined at the beginning of the file, and an arbitrary predicate string (which can include whitespace) that is meaningful to the matching rule callable. If no predicate is given, then the rule callable will receive None for its predicate argument. Rules must be explicitly specified at the beginning of the file before being available within handler sections. After the first condition in a handler section, additional condition lines must begin with one of AND, OR, or NOT. These case-insensitive tokens specify how conditions are to be combined in evaluating whether to use this handler.

On each request, handlers are considered in the order given, and the first matching handler is used. Only one handler is used for any given request.

Note that if the file __/etc/handlers.conf exists at all, the defaults (see the example below) disappear, and you must respecify any of the default rules in your own file if you want them.

4.2.1 Example handlers.conf

fnmatch     aspen.rules:fnmatch
hashbang    aspen.rules:hashbang
mime-type   aspen.rules:mimetype


[aspen.handlers:HTTP404]
fnmatch *.py[cod]           # hide any compiled Python scripts


[aspen.handlers:pyscript]
    fnmatch     *.py        # exec python scripts ...
OR  hashbang                # ... and anything starting with #!


[aspen.handlers:Simplate]
mime-type text/html         # run html files through the Simplates engine


[aspen.handlers:static]
fnmatch *                   # anything else, serve it statically