What is a URL file and how do I make one?

A URL file is a standard INI file for routing web content.  It is designed to route a web request to the proper WSGI application.  It is divided up into sections and each section is further subdivided into options.  An example is this section for the built-in WSGI application simple_app:


[simple_app]
regex: simple
import_path: Kamaelia.Apps.WSGI.Simple
app_object: simple_app


This demonstrates the three most important settings in the URL file:  the regex, the import_path, and the app_object.  Except in the instance of the 404 handler, the section heading (the part in brackets) is mostly irrelevant.

regex - This is the regex that is used to determine if a URL matches this application.  It is only tested against the first directory in the URI.  Therefore, this regex would match www.domain.com/simple but not www.domain.com/blah/simple.  Please note that a regex should not be entered for the 404 handler.  It is assumed to be ".*"

import_path - This is the path to import the module containing the WSGI application object.

app_object -  This is the name of the application object within the module represented by import_path.  Thus, for this example, the server would pull the function simple_app out of plugins.WsgiApps.simple_app.  If this is omitted, it is assumed to be "application".

Please also note that order is important in the URL file.  The application listed first will be the first one that is evaluated.

Every URLs file must also have a 404 handler.  It will be automatically assigned a regex of ".*".  It will be evaluated last in the URL routing no matter what position it is put in the list, but it is typically a good idea to put it last in the URL list anyway.

Any option in the URLs file will be passed to the WSGI application as an environment variable and will be prepended with "kp" to distinct them as Kamaelia Publish specific settings (although this will be present in Kamaelia WebServe).  Thus, some applications require their own custom settings.  Take for instance the built-in Paste application handler (assuming that you want to serve a paste system described by a config file config.ini):

[paste_app]
regex: paste
import_path:  Kamaelia.Apps.WSGI.PasteApp
paste_source: config:/path/to/config.ini

The custom keys 'kp.regex', 'kp.import_path', and 'kp.paste_source' will be passed to the application with the values 'paste', 'Kamaelia.Apps.WSGI.Paste', and '/path/to/config.ini', respectively.