Dolda2000 GitWeb / ashd.git / blame
| 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/> |