Python API

Multiple Interpreters

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.

Internal Callback Object

The Apache server interfaces with the Python interpreter via a callback object obCallBack. When a subinterpreter is created, an instance of obCallBack is created in this subinterpreter. Interestingly, obCallBack is not written in C, it is written in Python and the code for it is in the apache module. Mod_python only uses the C API to import apache and then instantiate obCallBack, 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 method Dispatch, 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 a request object.

Overview of a handler

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

As 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_FORBIDDEN

Handlers can send content to the client using the request.write() function. Before sending the body of the response, headers must be sent using the request.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

apache module

The Python Application Programmer interface to Apache internals is contained in a module appropriately named apache, located inside the mod_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 apache
Mod_python's apache 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 Apache ap_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_NOERRNO
server is a reference to a server 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 empty table object.

Table Object

The table object is a Python mapping to the Apache table . The table 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 and request.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

The request object is a Python mapping to the Apache request_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 the request 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 of request.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 the table 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 the table object containing the options set by the PythonOption directives.

get_dirs()
Returns a reference to the table 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 underlying request_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
A table 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 the request.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
A table representing the subprocess environment. See also request.add_common_vars().

Connection Object

The connection object is a Python mapping to the Apache conn_rec structure.

Server Object

The request object is a Python mapping to the Apache request_rec structure.
Last modified: Fri May 12 22:04:45 EDT 2000