4.2 Handlers: Resource-based Extension

Aspen handlers are WSGI applications that are associated with files and directories on the filesystem according to arbitrary rules. This provides a flexible infrastructure for many different development patterns.

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 filesystem path name 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.

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

catch_all   aspen.rules:catch_all
isdir       aspen.rules:isdir
isfile      aspen.rules:isfile
fnmatch     aspen.rules:fnmatch
hashbang    aspen.rules:hashbang
mime-type   aspen.rules:mimetype


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

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

[aspen.handlers:default_or_autoindex]
  isdir                         # do smart things for directories

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