python: Documented the ashd.wsgidir module.

diff --git a/python/ashd/wsgidir.py b/python/ashd/wsgidir.py
index 83d96a0..6080d91 100644 (file)
--- a/python/ashd/wsgidir.py
+++ b/python/ashd/wsgidir.py
@@ -1,7 +1,61 @@
+"""WSGI handler for serving chained WSGI modules from physical files
+
+The WSGI handler in this module examines the SCRIPT_FILENAME variable
+of the requests it handles -- that is, the physical file corresponding
+to the request, as determined by the webserver -- determining what to
+do with the request based on the extension of that file.
+
+By default, it handles files named `.wsgi' by compiling them into
+Python modules and using them, in turn, as chained WSGI handlers, but
+handlers for other extensions can be installed as well.
+
+When handling `.wsgi' files, the compiled modules are cached and
+reused until the file is modified, in which case the previous module
+is discarded and the new file contents are loaded into a new module in
+its place. When chaining such modules, an object named `wmain' is
+first looked for and called with no arguments if found. The object it
+returns is then used as the WSGI application object for that module,
+which is reused until the module is reloaded. If `wmain' is not found,
+an object named `application' is looked for instead. If found, it is
+used directly as the WSGI application object.
+
+This module itself contains both an `application' and a `wmain'
+object. If this module is used by ashd-wsgi(1) or scgi-wsgi(1) so that
+its wmain function is called, arguments can be specified to it to
+install handlers for other file extensions. Such arguments take the
+form `.EXT=MODULE.HANDLER', where EXT is the file extension to be
+handled, and the MODULE.HANDLER string is treated by splitting it
+along its last constituent dot. The part left of the dot is the name
+of a module which is imported, and the part right of the dot is the
+name of an object in that module, which should be a callable of three
+arguments. When files of the given extension are handled, that
+callable is called with the file's absolute path, the WSGI environment
+and the WSGI `start_response' function, in that order. For example,
+the argument `.fpy=my.module.foohandler' can be given to pass requests
+for `.fpy' files to the function `foohandler' in the module
+`my.module' (which must, of course, be importable). When writing such
+handler functions, you will probably want to use the getmod() function
+in this module.
+"""
+
 import os, threading, types
 import wsgiutil
 
+__all__ = ["application", "wmain", "getmod", "cachedmod"]
+
 class cachedmod(object):
+    """Cache entry for modules loaded by getmod()
+
+    Instances of this class are returned by the getmod()
+    function. They contain three data attributes:
+     * mod - The loaded module
+     * lock - A threading.Lock object, which can be used for
+       manipulating this instance in a thread-safe manner
+     * mtime - The time the file was last modified
+
+    Additional data attributes can be arbitrarily added for recording
+    any meta-data about the module.
+    """
     def __init__(self, mod, mtime):
         self.lock = threading.Lock()
         self.mod = mod
@@ -21,6 +75,18 @@ def mangle(path):
     return ret
 
 def getmod(path):
+    """Load the given file as a module, caching it appropriately
+
+    The given file is loaded and compiled into a Python module. The
+    compiled module is cached and returned upon subsequent requests
+    for the same file, unless the file has changed (as determined by
+    its mtime), in which case the cached module is discarded and the
+    new file contents are reloaded in its place.
+
+    The return value is an instance of the cachedmod class, which can
+    be used for locking purposes and for storing arbitrary meta-data
+    about the module. See its documentation for details.
+    """
     sb = os.stat(path)
     cachelock.acquire()
     try:
@@ -73,6 +139,10 @@ def addext(ext, handler):
     exts[ext] = getattr(mod, hname)
 
 def application(env, startreq):
+    """WSGI handler function
+
+    Handles WSGI requests as per the module documentation.
+    """
     if not "SCRIPT_FILENAME" in env:
         return wsgiutil.simpleerror(env, startreq, 500, "Internal Error", "The server is erroneously configured.")
     path = env["SCRIPT_FILENAME"]
@@ -86,6 +156,11 @@ def application(env, startreq):
     return(exts[ext](path, env, startreq))
 
 def wmain(*argv):
+    """Main function for ashd(7)-compatible WSGI handlers
+
+    Returns the `application' function. If any arguments are given,
+    they are parsed according to the module documentation.
+    """
     for arg in argv:
         if arg[0] == '.':
             p = arg.index('=')