Commit | Line | Data |
---|---|---|
338bee9d FT |
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/> |