When working with mod_python, it is important to be aware of a feature of Python that is normally not used when using the language for writing scripts to be run from command line.Python C API provides the ability to create subinterpreters. A more detailed description of a subintepreter is given in the documentation for the Py_NewInterpreter function. For this discussion, it will suffice to say that each subinterpreter has its own separate namespace, not accessible from other subinterpreters.
At server start-up or mod_python initialization time, mod_python initializes the global interpreter. The global interpreter contains a dictionary of subinterpreters. Initially, this dictionary is empty. With every hit, as needed, subinterpreters are created, and references to them are stored in this dictionary. The key, also known as interpreter name, is a string representing the path where the Handler directive was encountered, or where the the actual file is (this depends on whether the
PythonInterpPerDirectory
directive is in effect).Once created, a subinterpreter will be reused for subsequent requests, but it is never destroyed until the Apache child process dies.
The Apache server interfaces with the Python interpreter via a callback objectobCallBack
. When a subinterpreter is created, an instance ofobCallBack
is created in this subinterpreter. Interestingly,obCallBack
is not written in C, it is written in Python and the code for it is in theapache
module. Mod_python only uses the C API to importapache
and then instantiateobCallBack
, storing a reference to the instance in the interpreter dictionary described above. Thus, the values in the interpreter dictionary are callback object instances.When a request handler is invoked by Apache, mod_python uses the
obCallBack
reference to call its methodDispatch
, passing it the name of the handler being invoked as a string.The
Dispatch
method then does the rest of the work of importing the user module, resolving the callable object in it and calling it passing it arequest
object.
A handler is a function that processes a particular stage of a request. Apache processes requests in stages - read the request, process headers, provide content, etc. For every stage, it will call handlers, provided by either the Apache core or one of its modules, such as mod_python, which passes control to functions provided b the user and written in Python. A handler written in Python is not any different than a handler written in C, and follows these rules:A handler function will always be passed a reference to a
request
object.Every handler can return
apache.OK
, meaning this stage of the request was handled by this handler and no errors occurred.apache.DECLINED
, meaning this handler refused to handle this stage of the request and Apache needs to look for another handler.apache.HTTP_ERROR
, meaning an HTTP error occurred.HTTP_ERROR
can be:HTTP_CONTINUE = 100 HTTP_SWITCHING_PROTOCOLS = 101 HTTP_PROCESSING = 102 HTTP_OK = 200 HTTP_CREATED = 201 HTTP_ACCEPTED = 202 HTTP_NON_AUTHORITATIVE = 203 HTTP_NO_CONTENT = 204 HTTP_RESET_CONTENT = 205 HTTP_PARTIAL_CONTENT = 206 HTTP_MULTI_STATUS = 207 HTTP_MULTIPLE_CHOICES = 300 HTTP_MOVED_PERMANENTLY = 301 HTTP_MOVED_TEMPORARILY = 302 HTTP_SEE_OTHER = 303 HTTP_NOT_MODIFIED = 304 HTTP_USE_PROXY = 305 HTTP_TEMPORARY_REDIRECT = 307 HTTP_BAD_REQUEST = 400 HTTP_UNAUTHORIZED = 401 HTTP_PAYMENT_REQUIRED = 402 HTTP_FORBIDDEN = 403 HTTP_NOT_FOUND = 404 HTTP_METHOD_NOT_ALLOWED = 405 HTTP_NOT_ACCEPTABLE = 406 HTTP_PROXY_AUTHENTICATION_REQUIRED= 407 HTTP_REQUEST_TIME_OUT = 408 HTTP_CONFLICT = 409 HTTP_GONE = 410 HTTP_LENGTH_REQUIRED = 411 HTTP_PRECONDITION_FAILED = 412 HTTP_REQUEST_ENTITY_TOO_LARGE = 413 HTTP_REQUEST_URI_TOO_LARGE = 414 HTTP_UNSUPPORTED_MEDIA_TYPE = 415 HTTP_RANGE_NOT_SATISFIABLE = 416 HTTP_EXPECTATION_FAILED = 417 HTTP_UNPROCESSABLE_ENTITY = 422 HTTP_LOCKED = 423 HTTP_FAILED_DEPENDENCY = 424 HTTP_INTERNAL_SERVER_ERROR = 500 HTTP_NOT_IMPLEMENTED = 501 HTTP_BAD_GATEWAY = 502 HTTP_SERVICE_UNAVAILABLE = 503 HTTP_GATEWAY_TIME_OUT = 504 HTTP_VERSION_NOT_SUPPORTED = 505 HTTP_VARIANT_ALSO_VARIES = 506 HTTP_INSUFFICIENT_STORAGE = 507 HTTP_NOT_EXTENDED = 510As an alternative to returning an HTTP error code, handlers can signal an error by raising the
apache.SERVER_RETURN
exception, and providing an HTTP error code as the exception value, e.g.raise apache.SERVER_RETURN, apache.HTTP_FORBIDDENHandlers can send content to the client using the
request.write()
function. Before sending the body of the response, headers must be sent using therequest.send_http_header()
function.Client data, such as POST requests, can be read by using the
req.read()
function.NOTE:The current working directory of the process in which a handler is executed is that of the Apache Python*Handler directive in effect. If the directive was specified in a server config file outside any <Directory>, then the current working directory could be anything.
An example of a minimalistic handler might be:
from mod_python import apache def requesthandler(req): req.content_type = "text/plain" req.send_http_header() req.write("Hello World!") return apache.OK
The Python Application Programmer interface to Apache internals is contained in a module appropriately namedapache
, located inside themod_python
package. This module provides some important objects that map to Apache internal structures, as well as some useful functions, all documented below.The
apache
module can only be imported by a script running under mod_python. This is because it depends on a built-in module_apache
provided by mod_python. It is best imported like this:from mod_python import apacheMod_python'sapache
module defines the following objects and functions. For a more in-depth look at Apache internals, see the Shambhala API Notes.log_error(message, [level=level], [server=server])
An interface to the Apacheap_log_error
function. message is a string with the error message, level is one of the following constants:APLOG_EMERG APLOG_ALERT APLOG_CRIT APLOG_ERR APLOG_WARNING APLOG_NOTICE APLOG_INFO APLOG_DEBUG APLOG_NOERRNOserver is a reference to aserver
object which is passed as a member of the request,request.server
. If server is not specified, then the error will be logged to the default error log, otherwise it will be written to the error log for the appropriate virtual server.make_table()
Returns a new emptytable
object.Table Object
Thetable
object is a Python mapping to the Apachetable
. Thetable
object performs just like a dictionary, with the only difference that key lookups are case insensitive.Much of the information that Apache uses is stored in tables. For example,
request.header_in
andrequest.headers_out
.All the tables that mod_python provides inside the
request
object are actual mappings to the Apache structures, so changing the Python table also changes the underlying Apache table.Request Object
Therequest
object is a Python mapping to the Apacherequest_rec
structure.When a handler is invoked, it is always passed a single argument - the
request
object. Here is an outline of the most important attributes of therequest
object:Functions
send_http_header()
Starts the output from the request by sending the HTTP headers. This function has no effect when called more than once within the same request. Any manipulation ofrequest.headers_out
after this function has been called is pointless since the headers have already been sent to the client.get_basic_auth_pw()
Returns a string containing the password when basic authentication is used.write(string)
Writes string directly to the client, then flushes the buffer.read()
Reads directly from the client, returning a string with the data read. When there is nothing more to read, None is returned.get_config()
Returns a reference to thetable
object containing the configuration in effect for this request. The table has directives as keys, and their values, if any, as values.get_options()
Returns a reference to thetable
object containing the options set by the PythonOption directives.get_dirs()
Returns a reference to thetable
object keyed by directives currently in effect and having directory names of where the particular directive was last encountered as values. For every key in the table returned by get_config(), there will be a key in this table. If the directive was in one of the server config files outside of any <Directory>, then the value will be an empty string.add_common_vars()
Calls the Apache ap_add_common_vars function. After a call to this function,request.subprocess_env
will contain a lot of CGI information.Other Members
The request object contains most of the members of the underlyingrequest_rec
. Only the most important or frequently used ones are mentioned here.status
An integer, whose value will be used in building the status line of the HTTP reply headers. Normally, there is no reason to change this. The correct way to provide status is to return the status code from the handler.content_type
A string, representing the response content type.headers_in
Atable
object containing the headers send by the client.headers_out A
table
object representing the headers to be sent to the client. Note that manipulating this table after therequest.send_http_headers()
has been called is meaningless, since the headers have already gone out to the client.connection A
connection
object associated with this request.subprocess_env
Atable
representing the subprocess environment. See alsorequest.add_common_vars()
.
Connection Object
Theconnection
object is a Python mapping to the Apacheconn_rec
structure.Server Object
Therequest
object is a Python mapping to the Apacherequest_rec
structure.