etc: Use the send handler from dirplex.d in apache-compat.
[ashd.git] / python / doc / ashd-wsgi.doc
CommitLineData
338bee9d
FT
1ashd-wsgi(1)
2============
3
4NAME
5----
6ashd-wsgi - WSGI adapter for ashd(7)
7
8SYNOPSIS
9--------
3e11d7ed 10*ashd-wsgi* [*-hA*] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...]
338bee9d
FT
11
12DESCRIPTION
13-----------
14
15The *ashd-wsgi* handler translates *ashd*(7) requests to WSGI
16requests, and passes them to a specified Python handler module. The
17precise Python convention for doing so is described in the PROTOCOL
18section, below.
19
20*ashd-wsgi* is a persistent handler, as defined in *ashd*(7). It uses
21multithreaded dispatching in a single Python interpreter, which means
22that WSGI applications that use it need to be thread-safe, but that
23they can also share all Python data structures and global variables
24between requests.
25
26The Python module that *ashd-wsgi* comes with also contains a standard
27handler module, `ashd.wsgidir`, which serves individual WSGI
28applications directly from the files in which they reside and as such
29makes this program useful as a *dirplex*(1) handler. Please see its
30Python documentation for further details.
31
32*ashd-wsgi* requires the `ashd.proto` and `ashd.util` modules, which
33are only available for CPython. If you want to use some other Python
34implementation instead, you may want to use the *scgi-wsgi*(1) program
35instead, along with *callscgi*(1).
36
37OPTIONS
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
3e11d7ed
FT
57*-l* 'LIMIT'::
58
59 Allow at most 'LIMIT' requests to run concurrently. If a new
60 request is made when 'LIMIT' requests are executing, the new
61 request will wait up to ten seconds for one of them to
3da05ba7 62 complete; if none does, *ashd-wsgi* will assume that the
3e11d7ed
FT
63 process is foobar and *abort*(3).
64
338bee9d
FT
65PROTOCOL
66--------
67
68When starting, *ashd-wsgi* will attempt to import the module named by
69'HANDLER-MODULE', look for an object named `wmain` in that module,
70call that object passing the 'ARGS' (as Python strings) as positional
71parameters, and use the returned object as the WSGI application
72object. If the *-A* option was specified, it will look for an object
73named `application` instead of `wmain`, and use that object directly
74as the WSGI application object.
75
76When calling the WSGI application, a new thread is started for each
77request, in which the WSGI application object is called. All requests
78run in the same interpreter, so it is guaranteed that data structures
79and global variables can be shared between requests.
80
81The WSGI environment is the standard CGI environment, including the
82`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
83included in the request.
84
85EXAMPLES
86--------
87
88The following *dirplex*(1) configuration can be used for serving WSGI
89modules directly from the filesystem.
90
91--------
92child wsgidir
93 exec ashd-wsgi ashd.wsgidir
94match
95 filename *.wsgi
96 handler wsgidir
97--------
98
99Since *ashd-wsgi* is a persistent handler, it can be used directly as
100a root handler for *htparser*(1). For instance, if the directory
101`/srv/www/foo` contains a `wsgi.py` file, which declares a standard
102WSGI `application` object, it can be served with the following
103command:
104
105--------
106htparser plain:port=8080 -- ashd-wsgi -Ap /srv/www/foo wsgi
107--------
108
109AUTHOR
110------
111Fredrik Tolf <fredrik@dolda2000.com>
112
113SEE ALSO
114--------
115*scgi-wsgi*(1), *ashd*(7), <http://wsgi.org/>