dirplex: Correct config resolution for base directory.
[ashd.git] / python3 / doc / ashd-wsgi3.doc
1 ashd-wsgi3(1)
2 =============
3
4 NAME
5 ----
6 ashd-wsgi3 - WSGI adapter for ashd(7)
7
8 SYNOPSIS
9 --------
10 *ashd-wsgi3* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...]
11
12 DESCRIPTION
13 -----------
14
15 The *ashd-wsgi3* 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-wsgi3* 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-wsgi3* comes with also contains a
27 standard 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-wsgi3* 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-wsgi3* 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 *-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
62         complete; if none does, *ashd-wsgi3* will assume that the
63         process is foobar and *abort*(3).
64
65 *-m* 'PDM-SPEC'::
66
67         If the PDM library is installed on the system, create a
68         listening socket for connection PDM clients according to
69         'PDM-SPEC'.
70
71 PROTOCOL
72 --------
73
74 When starting, *ashd-wsgi3* will attempt to import the module named by
75 'HANDLER-MODULE', look for an object named `wmain` in that module,
76 call that object passing the 'ARGS' (as Python strings) as positional
77 parameters, and use the returned object as the WSGI application
78 object. If the *-A* option was specified, it will look for an object
79 named `application` instead of `wmain`, and use that object directly
80 as the WSGI application object.
81
82 When calling the WSGI application, a new thread is started for each
83 request, in which the WSGI application object is called. All requests
84 run in the same interpreter, so it is guaranteed that data structures
85 and global variables can be shared between requests.
86
87 The WSGI environment is the standard CGI environment, including the
88 `SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
89 included in the request.
90
91 EXAMPLES
92 --------
93
94 The following *dirplex*(1) configuration can be used for serving WSGI
95 modules directly from the filesystem.
96
97 --------
98 child wsgidir
99   exec ashd-wsgi3 ashd.wsgidir
100 match
101   filename *.wsgi
102   handler wsgidir
103 --------
104
105 Since *ashd-wsgi3* is a persistent handler, it can be used directly as
106 a root handler for *htparser*(1). For instance, if the directory
107 `/srv/www/foo` contains a `wsgi.py` file, which declares a standard
108 WSGI `application` object, it can be served with the following
109 command:
110
111 --------
112 htparser plain:port=8080 -- ashd-wsgi3 -Ap /srv/www/foo wsgi
113 --------
114
115 AUTHOR
116 ------
117 Fredrik Tolf <fredrik@dolda2000.com>
118
119 SEE ALSO
120 --------
121 *scgi-wsgi3*(1), *ashd*(7), <http://wsgi.org/>