python/doc/ashd-wsgi.doc

   1 ashd-wsgi(1)
   2 ============
   3
   4 NAME
   5 ----
   6 ashd-wsgi - WSGI adapter for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *ashd-wsgi* [*-hA*] [*-p* 'MODPATH'] 'HANDLER-MODULE' ['ARGS'...]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *ashd-wsgi* handler translates *ashd*(7) requests to WSGI
  16 requests, and passes them to a specified Python handler module. The
  17 precise Python convention for doing so is described in the PROTOCOL
  18 section, below.
  19
  20 *ashd-wsgi* is a persistent handler, as defined in *ashd*(7). It uses
  21 multithreaded dispatching in a single Python interpreter, which means
  22 that WSGI applications that use it need to be thread-safe, but that
  23 they can also share all Python data structures and global variables
  24 between requests.
  25
  26 The Python module that *ashd-wsgi* comes with also contains a standard
  27 handler module, `ashd.wsgidir`, which serves individual WSGI
  28 applications directly from the files in which they reside and as such
  29 makes this program useful as a *dirplex*(1) handler. Please see its
  30 Python documentation for further details.
  31
  32 *ashd-wsgi* requires the `ashd.proto` and `ashd.util` modules, which
  33 are only available for CPython. If you want to use some other Python
  34 implementation instead, you may want to use the *scgi-wsgi*(1) program
  35 instead, along with *callscgi*(1).
  36
  37 OPTIONS
  38 -------
  39
  40 *-h*::
  41
  42         Print a brief help message to standard output and exit.
  43
  44 *-A*::
  45
  46         Use the convention used by Apache's mod_wsgi module to find
  47         the WSGI application object. See the PROTOCOL section, below,
  48         for details.
  49
  50 *-p* 'MODPATH'::
  51
  52         Prepend 'MODPATH' to Python's `sys.path`; can be given multiple
  53         times. Note that the working directory of *ashd-wsgi* is not
  54         on Python's module path by default, so if you want to use a
  55         module in that directory, you will need to specify "`-p .`".
  56
  57 PROTOCOL
  58 --------
  59
  60 When starting, *ashd-wsgi* will attempt to import the module named by
  61 'HANDLER-MODULE', look for an object named `wmain` in that module,
  62 call that object passing the 'ARGS' (as Python strings) as positional
  63 parameters, and use the returned object as the WSGI application
  64 object. If the *-A* option was specified, it will look for an object
  65 named `application` instead of `wmain`, and use that object directly
  66 as the WSGI application object.
  67
  68 When calling the WSGI application, a new thread is started for each
  69 request, in which the WSGI application object is called. All requests
  70 run in the same interpreter, so it is guaranteed that data structures
  71 and global variables can be shared between requests.
  72
  73 The WSGI environment is the standard CGI environment, including the
  74 `SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
  75 included in the request.
  76
  77 EXAMPLES
  78 --------
  79
  80 The following *dirplex*(1) configuration can be used for serving WSGI
  81 modules directly from the filesystem.
  82
  83 --------
  84 child wsgidir
  85   exec ashd-wsgi ashd.wsgidir
  86 match
  87   filename *.wsgi
  88   handler wsgidir
  89 --------
  90
  91 Since *ashd-wsgi* is a persistent handler, it can be used directly as
  92 a root handler for *htparser*(1). For instance, if the directory
  93 `/srv/www/foo` contains a `wsgi.py` file, which declares a standard
  94 WSGI `application` object, it can be served with the following
  95 command:
  96
  97 --------
  98 htparser plain:port=8080 -- ashd-wsgi -Ap /srv/www/foo wsgi
  99 --------
 100
 101 AUTHOR
 102 ------
 103 Fredrik Tolf <fredrik@dolda2000.com>
 104
 105 SEE ALSO
 106 --------
 107 *scgi-wsgi*(1), *ashd*(7), <http://wsgi.org/>