From 338bee9d3d0ad8f236a17d9d1b8e7433e1d17c21 Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Thu, 14 Apr 2011 13:00:15 +0200 Subject: [PATCH] python: Added (unused) documentation for ashd-wsgi and scgi-wsgi. Unfortunately, I know not yet how to make distutils compile and install them. --- python/doc/.gitignore | 3 ++ python/doc/ashd-wsgi.doc | 107 +++++++++++++++++++++++++++++++++++++++++++++++ python/doc/scgi-wsgi.doc | 63 ++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+) create mode 100644 python/doc/.gitignore create mode 100644 python/doc/ashd-wsgi.doc create mode 100644 python/doc/scgi-wsgi.doc diff --git a/python/doc/.gitignore b/python/doc/.gitignore new file mode 100644 index 0000000..494c1f8 --- /dev/null +++ b/python/doc/.gitignore @@ -0,0 +1,3 @@ +/*.1 +/*.html +/*.css diff --git a/python/doc/ashd-wsgi.doc b/python/doc/ashd-wsgi.doc new file mode 100644 index 0000000..25531ff --- /dev/null +++ b/python/doc/ashd-wsgi.doc @@ -0,0 +1,107 @@ +ashd-wsgi(1) +============ + +NAME +---- +ashd-wsgi - WSGI adapter for ashd(7) + +SYNOPSIS +-------- +*ashd-wsgi* [*-hA*] [*-p* 'MODPATH'] 'HANDLER-MODULE' ['ARGS'...] + +DESCRIPTION +----------- + +The *ashd-wsgi* handler translates *ashd*(7) requests to WSGI +requests, and passes them to a specified Python handler module. The +precise Python convention for doing so is described in the PROTOCOL +section, below. + +*ashd-wsgi* is a persistent handler, as defined in *ashd*(7). It uses +multithreaded dispatching in a single Python interpreter, which means +that WSGI applications that use it need to be thread-safe, but that +they can also share all Python data structures and global variables +between requests. + +The Python module that *ashd-wsgi* comes with also contains a standard +handler module, `ashd.wsgidir`, which serves individual WSGI +applications directly from the files in which they reside and as such +makes this program useful as a *dirplex*(1) handler. Please see its +Python documentation for further details. + +*ashd-wsgi* requires the `ashd.proto` and `ashd.util` modules, which +are only available for CPython. If you want to use some other Python +implementation instead, you may want to use the *scgi-wsgi*(1) program +instead, along with *callscgi*(1). + +OPTIONS +------- + +*-h*:: + + Print a brief help message to standard output and exit. + +*-A*:: + + Use the convention used by Apache's mod_wsgi module to find + the WSGI application object. See the PROTOCOL section, below, + for details. + +*-p* 'MODPATH':: + + Prepend 'MODPATH' to Python's `sys.path`; can be given multiple + times. Note that the working directory of *ashd-wsgi* is not + on Python's module path by default, so if you want to use a + module in that directory, you will need to specify "`-p .`". + +PROTOCOL +-------- + +When starting, *ashd-wsgi* will attempt to import the module named by +'HANDLER-MODULE', look for an object named `wmain` in that module, +call that object passing the 'ARGS' (as Python strings) as positional +parameters, and use the returned object as the WSGI application +object. If the *-A* option was specified, it will look for an object +named `application` instead of `wmain`, and use that object directly +as the WSGI application object. + +When calling the WSGI application, a new thread is started for each +request, in which the WSGI application object is called. All requests +run in the same interpreter, so it is guaranteed that data structures +and global variables can be shared between requests. + +The WSGI environment is the standard CGI environment, including the +`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was +included in the request. + +EXAMPLES +-------- + +The following *dirplex*(1) configuration can be used for serving WSGI +modules directly from the filesystem. + +-------- +child wsgidir + exec ashd-wsgi ashd.wsgidir +match + filename *.wsgi + handler wsgidir +-------- + +Since *ashd-wsgi* is a persistent handler, it can be used directly as +a root handler for *htparser*(1). For instance, if the directory +`/srv/www/foo` contains a `wsgi.py` file, which declares a standard +WSGI `application` object, it can be served with the following +command: + +-------- +htparser plain:port=8080 -- ashd-wsgi -Ap /srv/www/foo wsgi +-------- + +AUTHOR +------ +Fredrik Tolf + +SEE ALSO +-------- +*scgi-wsgi*(1), *ashd*(7), diff --git a/python/doc/scgi-wsgi.doc b/python/doc/scgi-wsgi.doc new file mode 100644 index 0000000..1aab621 --- /dev/null +++ b/python/doc/scgi-wsgi.doc @@ -0,0 +1,63 @@ +scgi-wsgi(1) +============ + +NAME +---- +scgi-wsgi - WSGI adapter for SCGI + +SYNOPSIS +-------- +*scgi-wsgi* [*-hA*] [*-p* 'MODPATH'] [*-T* \[HOST:]'PORT'] 'HANDLER-MODULE' ['ARGS'...] + +DESCRIPTION +----------- + +The *scgi-wsgi* program translates SCGI requests to WSGI requests, and +passes them to a specified Python module. It is mainly written to +emulate the behavior of *ashd-wsgi*(1), but over SCGI instead of the +native *ashd*(7) protocol, so please see its documentation for details +of Python interoperation. Unlike *ashd-wsgi* which requires CPython, +however, *scgi-wsgi* is written in pure Python using only the standard +library, and so should be usable by any Python implementation. If +using it under *ashd*(7), please see the documentation for +*callscgi*(1) as well. + +Following *callscgi*(1) conventions, *scgi-wsgi* will, by default, +accept connections on a socket passed on its standard input (a +behavior which is, obviously, not available on all Python +implementations). Use the *-T* option to listen to a TCP address +instead. + +OPTIONS +------- + +*-h*:: + + Print a brief help message to standard output and exit. + +*-A*:: + + Use the convention used by Apache's mod_wsgi module to find + the WSGI application object. See the PROTOCOL section of + *ashd-wsgi*(1) for details. + +*-p* 'MODPATH':: + + Prepend 'MODPATH' to Python's `sys.path`; can be given multiple + times. + +*-T* \[HOST:]'PORT':: + + Instead of using a listening socket passed on standard input + to accept SCGI connections, bind a TCP socket to the 'HOST' + address listening for connections on 'PORT' instead. If 'HOST' + is not given, `localhost` is used by default. + +AUTHOR +------ +Fredrik Tolf + +SEE ALSO +-------- +*ashd-wsgi*(1), *callscgi*(1), , + -- 2.11.0