From fc2aa563ea22418e23abe89285c7a87c1ee90c5b Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Thu, 14 Apr 2011 12:18:46 +0200 Subject: [PATCH] python: Documented the ashd.wsgidir module. --- python/ashd/wsgidir.py | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/python/ashd/wsgidir.py b/python/ashd/wsgidir.py index 83d96a0..6080d91 100644 --- 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('=') -- 2.11.0