\chapter{Python API\label{pythonapi}}

\section{Multiple Interpreters\label{pyapi-interps}}

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. This feature is not

available from within Python itself and can only be accessed through

the \citetitle[http://www.python.org/doc/current/api/api.html]{C

language API}.

Python C API provides the ability to create \dfn{subinterpreters}. A

more detailed description of a subinterpreter is given in the

documentation for the

\citetitle[http://www.python.org/doc/current/api/initialization.html]{\cfunction{Py_NewInterpreter()}}

function. For this discussion, it will suffice to say that each

subinterpreter has its own separate namespace, not accessible from

other subinterpreters. Subinterpreters are very useful to make sure

that separate programs running under the same Apache server do not

interfere with one another.

At server start-up or mod_python initialization time, mod_python

initializes an interpreter called \dfn{main} interpreter. The main

interpreter contains a dictionary of subinterpreters. Initially, this

dictionary is empty. With every request, as needed, subinterpreters

are created, and references to them are stored in this dictionary. The

dictionary is keyed on a string, also known as \emph{interpreter

name}. This name can be any string. The main interpreter is named

\samp{main_interpreter}. The way all other interpreters are named can

be controlled by \code{PythonInterp*} directives. Default behaviour is

to name interpreters using the Apache virtual server name

(\code{ServerName} directive). This means that all scripts in the same

virtual server execute in the same subinterpreter, but scripts in

different virtual servers execute in different subinterpreters with

completely separate namespaces.

\citetitle[dir-other-ipd.html]{\code{PythonInterpPerDirectory}} and

\citetitle[dir-other-ipdv.html]{\code{PythonInterpPerDirective}}

directives alter the naming convention to use the absolute path of the

directory being accessed, or the directory in which the

\code{Python*Handler} was encountered, respectively.

\citetitle[dir-other-pi.html]{\code{PythonInterpreter}} can be used to

force the interpreter name to a specific string overriding any naming

conventions.

Once created, a subinterpreter will be reused for subsequent requests.

It is never destroyed and exists until the Apache process dies.

You can find out the name of the interpreter under which you're

running by peeking at \member{req.interpreter}.

Note that if any third party module is being used which has a C code

component that uses the simplified API for access to the Global

Interpreter Lock (GIL) for Python extension modules, then the interpreter

name must be forcibly set to be \samp{main_interpreter}. This is necessary

as such a module will only work correctly if run within the context of

the first Python interpreter created by the process. If not forced to

run under the \samp{main_interpreter}, a range of Python errors can arise,

each typically referring to code being run in \emph{restricted mode}.

\begin{seealso}

\seetitle[http://www.python.org/doc/current/api/api.html]

{Python C Language API}{Python C Language API}

\seetitle[http://www.python.org/peps/pep-0311.html]

{PEP 0311 - Simplified Global Interpreter Lock Acquisition for Extensions}{PEP 0311 - Simplified Global Interpreter Lock Acquisition for Extensions}

\end{seealso}

\section{Overview of a Request Handler\label{pyapi-handler}}

\indexii{request}{handler}

A \dfn{handler} is a function that processes a particular phase of a

request. Apache processes requests in phases - read the request,

process headers, provide content, etc. For every phase, 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 by the

user and written in Python. A handler written in Python is not any

different from a handler written in C, and follows these rules:

\index{req} \indexii{request}{object} A handler function will always

be passed a reference to a request object. (Throughout this manual,

the request object is often referred to by the \code{req} variable.)

Every handler can return:

\begin{itemize}

\constant{apache.OK}, meaning this phase of the request was handled by this

handler and no errors occurred.

\constant{apache.DECLINED}, meaning this handler has not handled this

phase of the request to completion and Apache needs to look for

another handler in subsequent modules.

\constant{apache.\emph{HTTP_ERROR}}, meaning an HTTP error occurred.

\var{HTTP_ERROR} can be any of the following:

\begin{verbatim}

\end{verbatim}

\end{itemize}

As an alternative to \emph{returning} an HTTP error code, handlers can

signal an error by \emph{raising} the \constant{apache.SERVER_RETURN}

exception, and providing an HTTP error code as the exception value,

e.g.

\begin{verbatim}

\end{verbatim}

Handlers can send content to the client using the \method{req.write()}

method.

Client data, such as POST requests, can be read by using the

\method{req.read()} function.

\begin{notice}

The directory of the Apache \code{Python*Handler}

directive in effect is prepended to the \code{sys.path}. If the

directive was specified in a server config file outside any

\code{<Directory>}, then the directory is unknown and not prepended.

\end{notice}

An example of a minimalistic handler might be:

\begin{verbatim}

\end{verbatim}

\section{Overview of a Filter Handler\label{pyapi-filter}}

\indexii{filter}{handler}

A \dfn{filter handler} is a function that can alter the input or the

output of the server. There are two kinds of filters - \dfn{input} and

\dfn{output} that apply to input from the client and output to the

client respectively.

At this time mod_python supports only request-level filters, meaning

that only the body of HTTP request or response can be filtered. Apache

provides support for connection-level filters, which will be supported

in the future.

A filter handler receives a \emph{filter} object as its argument. The

request object is available as well via \code{filter.req}, but all

writing and reading should be done via the filter's object read and

write methods.

Filters need to be closed when a read operation returns None

(indicating End-Of-Stream).

The return value of a filter is ignored. Filters cannot decline

processing like handlers, but the same effect can be achieved

by using the \method{filter.pass_on()} method.

Filters must first be registered using \code{PythonInputFilter} or

\code{PythonOutputFilter}, then added using the Apache

\code{Add/SetInputFilter} or \code{Add/SetOutputFilter} directives.

Here is an example of how to specify an output filter, it tells the

server that all .py files should processed by CAPITALIZE filter:

\begin{verbatim}

\end{verbatim}

And here is what the code for the \file{capitalize.py} might look

like:

\begin{verbatim}

\end{verbatim}

When writing filters, keep in mind that a filter will be called any

time anything upstream requests an IO operation, and the filter has no

control over the amount of data passed through it and no notion of

where in the request processing it is called. For example, within a

single request, a filter may be called once or five times, and there

is no way for the filter to know beforehand that the request is over

and which of calls is last or first for this request, thought

encounter of an EOS (None returned from a read operation) is a fairly

strong indication of an end of a request.

Also note that filters may end up being called recursively in

subrequests. To avoid the data being altered more than once, always

make sure you are not in a subrequest by examining the \code{req.main}

value.

For more information on filters, see

\citetitle[http://httpd.apache.org/docs-2.0/developer/filters.html]{http://httpd.apache.org/docs-2.0/developer/filters.html}.

\section{Overview of a Connection Handler\label{pyapi-conn}}

\indexii{connection}{handler}

A \dfn{connection handler} handles the connection, starting almost

immediately from the point the TCP connection to the server was

made.

Unlike HTTP handlers, connection handlers receive a \emph{connection}

object as an argument.

Connection handlers can be used to implement protocols. Here is an

example of a simple echo server:

Apache configuration:

\begin{verbatim}

\end{verbatim}

Contents of \filenq{echo.py} file:

\begin{verbatim}

\end{verbatim}

\section{\module{apache} -- Access to Apache Internals.}

\declaremodule[apache]{extension}{apache}

\modulesynopsis{Access to Apache Internals}

\moduleauthor{Gregory Trubetskoy}{[email protected]}

The Python interface to Apache internals is contained in a module

appropriately named \module{apache}, located inside the

\module{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 request object also provides an

interface to Apache internals, it is covered in its own section of

this manual.)

\indexii{_apache}{module} The \module{apache} module can only be

imported by a script running under mod_python. This is because it

depends on a built-in module \module{_apache} provided by

mod_python.

It is best imported like this:

\begin{verbatim}

\end{verbatim}

\module{mod_python.apache} module defines the following functions and

objects. For a more in-depth look at Apache internals, see the

\citetitle[http://httpd.apache.org/dev/]{Apache Developer page}

\subsection{Functions\label{pyapi-apmeth}}

\begin{funcdesc}{log_error}{message\optional{, level, server}}

An interface to the Apache \code{ap_log_error()}

function. \var{message} is a string with the error message,

\var{level} is one of the following flags constants:

\begin{verbatim}

\end{verbatim}

\var{server} is a reference to a \member{req.server} object. If

\var{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. When \var{server} is not specified,

the setting of LogLevel does not apply, the LogLevel is dictated by

an httpd compile-time default, usually \code{warn}.

If you have a reference to a request object available, consider using

\method{req.log_error} instead, it will prepend request-specific

information such as the source IP of the request to the log entry.

\end{funcdesc}

\begin{funcdesc}{import_module}{module_name\optional{, autoreload=None, log=None, path=None}}

This function can be used to import modules.

\begin{notice}

This function and the module importer were completely reimplemented in

mod_python 3.3. If you are using an older version of mod_python do not

rely on this documentation and instead refer to the documentation for

the specific version you are using as the new importer does not behave

exactly the same and has additional features.

If you are trying to port code from an older version of mod_python to

mod_python 3.3 and can't work out why the new importer is not working

for you, you can enable the old module importer for specific Python

interpreter instances by using:

\begin{verbatim}

\end{verbatim}

where 'name' is the name of the interpreter instance or '*' for it to

be applied to all interpreter instances. This option should be placed

at global context within the main Apache configuration files.

\end{notice}

When using the \code{apache.import_module()} function, the

\var{module_name} should be a string containing either the module name,

or a path to the actual code file for the module; where a module is a

candidate for automatic module reloading, \var{autoreload} indicates

whether the module should be reloaded if it has changed since the last

import; when \var{log} is true, a message will be written to the logs

when a module is reloaded; \var{path} can be a list specifying additional

directories to be searched for modules.

With the introduction of mod_python 3.3, the default arguments for the

\var{autoreload} and \var{log} arguments have been changed to

\code{None}, with the arguments effectively now being unnecessary except

in special circumstances. When the arguments are left as the default of

\code{None}, the Apache configuration in scope at the time of the call

will always be consulted automatically for any settings for the

\code{PythonAutoReload} and \code{PythonDebug} directives respectively.

Example:

\begin{verbatim}

\end{verbatim}

The \code{apache.import_module()} function is not just a wrapper for the

standard Python module import mechanism. The purpose of the function and

the mod_python module importer in general, is to provide a means of being

able to import modules based on their exact location, with modules being

distinguished based on their location rather than just the name of the

module. Distinguishing modules in this way, rather than by name alone,

means that the same module name can be used for handlers and other code

in multiple directories and they will not interfere with each other.

A secondary feature of the module importer is to implement a means of

having modules automatically reloaded when the corresponding code file

has been changed on disk. Having modules be able to be reloaded in this

way means that it is possible to change the code for a web application

without having to restart the whole Apache web server. Although this was

always the intent of the module importer, prior to mod_python 3.3, its

effectiveness was limited. With mod_python 3.3 however, the module

reloading feature is much more robust and will correctly reload parent

modules even when it was only a child module what was changed.

When the \code{apache.import_module()} function is called with just the

name of the module, as opposed to a path to the actual code file for the

module, a search has to be made for the module. The first set of

directories that will be checked are those specified by the \var{path}

argument if supplied.

Where the function is called from another module which had previously

been imported by the mod_python importer, the next directory which will

be checked will be the same directory as the parent module is located.

Where that same parent module contains a global data variable called

\code{__mp_path__} containing a list of directories, those directories

will also be searched.

Finally, the mod_python module importer will search directories

specified by the \code{PythonOption} called \code{mod_python.importer.path}.

For example:

\begin{verbatim}

\end{verbatim}

The argument to the option must be in the form of a Python list. The

enclosing quotes are to ensure that Apache interprets the argument as a

single value. The list must be self contained and cannot reference any

prior value of the option. The list MUST NOT reference \code{sys.path}

nor should any directory which also appears in \code{sys.path} be

listed in the mod_python module importer search path.

When searching for the module, a check is made for any code file with the

name specified and having a '.py' extension. Because only modules

implemented as a single file will be found, packages will not be found

nor modules contained within a package.

In any case where a module cannot be found, control is handed off to the

standard Python module importer which will attempt to find the module or

package by searching \code{sys.path}.

Note that only modules found by the mod_python module importer are

candidates for automatic module reloading. That is, where the mod_python

module importer could not find a module and handed the search off to the

standard Python module importer, those modules or packages will not be

able to be reloaded.

Although true Python packages are not candidates for reloading and must

be located in a directory listed in \code{sys.path}, another form of

packaging up modules such that they can be maintained within their own

namespace is supported. When this mechanism is used, these modules will

be candidates for reloading when found by the mod_python module importer.

In this scheme for maintaining a pseudo package, individual modules are

still placed into a directory, but the \code{__init__.py} file in the

directory has no special meaning and will not be automatically imported

as is the case with true Python packages. Instead, any module within the

directory must always be explicitly identified when performing an import.

To import a named module contained within these pseudo packages, rather

than using a '.' to distinguish a sub module from the parent, a '/' is

used instead. For example:

\begin{verbatim}

\end{verbatim}

If an \code{__init__.py} file is present and it was necessary to import

it to achieve the same result as importing the root of a true Python

package, then \code{__init__} can be used as the module name. For example:

\begin{verbatim}

\end{verbatim}

As a true Python package is not being used, if a module in the directory

needs to refer to another module in the same directory, it should use

just its name, it should not use any form of dotted path name via the

root of the package as would be the case for true Python packages.

Modules in subdirectories can be imported by using a '/' separated path

where the first part of the path is the name of the subdirectory.

As a new feature in mod_python 3.3, when using the standard Python

'import' statement to import a module, if the import is being done from a

module which was previously imported by the mod_python module importer,

it is equivalent to having called \code{apache.import_module()} directly.

For example:

\begin{verbatim}

\end{verbatim}

is equivalent to:

\begin{verbatim}

\end{verbatim}

It is also possible to use constructs such as:

\begin{verbatim}

\end{verbatim}

and:

\begin{verbatim}

\end{verbatim}

Although the 'import' statement is used, that it maps through to the

\code{apache.import_module()} function ensures that parent/child

relationships are maintained correctly and reloading of a parent will

still work when only the child has been changed. It also ensures that one

will not end up with modules which were separately imported by the

mod_python module importer and the standard Python module importer.

With the reimplementation of the module importer in mod_python 3.3, the

\var{module_name} argument may also now be an absolute path name of an

actual Python module contained in a single file. On Windows, a drive

letter can be supplied if necessary. For example:

\begin{verbatim}

\end{verbatim}

or:

\begin{verbatim}

\end{verbatim}

Where the file has an extension, that extension must be supplied. Although

it is recommended that code files still make use of the '.py' extension,

it is not actually a requirement and an alternate extension can be used.

For example:

\begin{verbatim}

\end{verbatim}

To avoid the need to use hard coded absolute path names to modules, a few

shortcuts are provided. The first of these allow for the use of relative

path names with respect to the directory the module performing the

import is located within.

For example:

\begin{verbatim}

\end{verbatim}

Forward slashes must always be used for the prefixes './' and '../', even

on Windows hosts where native pathname use a backslash. This convention

of using forward slashes is used as that is what Apache normalizes all

paths to internally. If you are using Windows and have been using

backward slashes with \code{Directory} directives etc, you are using

Apache contrary to what is the accepted norm.

A further shortcut allows paths to be declared relative to what is

regarded as the handler root directory. The handler root directory is the

directory context in which the active \code{Python*Handler} directive was

specified. If the directive was specified within a \code{Location} or

\code{VirtualHost} directive, or at global server scope, the handler root

will be the relevant document root for the server.

To express paths relative to the handler root, the '\textasciitilde/' prefix

should be used. A forward slash must again always be used, even on Windows.

For example:

\begin{verbatim}

\end{verbatim}

In all cases where a path to the actual code file for a module is given,

the \var{path} argument is redundant as there is no need to search

through a list of directories to find the module. In these situations,

the \var{path} is instead taken to be a list of directories to use as the

initial value of the \code{__mp_path__} variable contained in the

imported modules instead of an empty path.

This feature can be used to attach a more restrictive search path to a

set of modules rather than using the \code{PythonOption} to set a global

search path. To do this, the modules should always be imported through a

specific parent module. That module should then always import submodules

using paths and supply \code{__mp_path__} as the \var{path} argument to

subsequent calls to \code{apache.import_module()} within that module. For

example:

\begin{verbatim}

\end{verbatim}

with the module being imported as:

\begin{verbatim}

\end{verbatim}

The parent module may if required extend the value of \code{__mp_path__}

prior to using it. Any such directories will be added to those inherited

via the \var{path} argument. For example:

\begin{verbatim}

\end{verbatim}

In all cases where a search path is being specified which is specific

to the mod_python module importer, whether it be specified using the

\code{PythonOption} called \code{mod_python.importer.path}, using the

\var{path} argument to the \code{apache.import_module()} function or

in the \code{__mp_path__} attribute, the prefix '\textasciitilde/'

can be used in a path and that path will be taken as being relative

to handler root. For example:

\begin{verbatim}

\end{verbatim}

If wishing to refer to the handler root directory itself, then

'\textasciitilde' can be used and the trailing slash left off. For example:

\begin{verbatim}

\end{verbatim}

Note that with the new module importer, as directories associated with

\code{Python*Handler} directives are no longer being added automatically

to \code{sys.path} and they are instead used directly by the module

importer only when required, some existing code which expected to be able

to import modules in the handler root directory from a module in a

subdirectory may no longer work. In these situations it will be necessary

to set the mod_python module importer path to include '\textasciitilde'

or list '\textasciitilde' in the \code{__mp_path__} attribute of the module

performing the import.

This trick of listing '\textasciitilde' in the module importer path

will not however help in the case where Python packages were previously

being placed into the handler root directory. In this case, the Python

package should either be moved out of the document tree and the directory

where it is located listed against the \code{PythonPath} directive, or the

package converted into the pseudo packages that mod_python supports and

change the module imports used to access the package.

Only modules which could be imported by the mod_python module importer

will be candidates for automatic reloading when changes are made to the

code file on disk. Any modules or packages which were located in a

directory listed in \code{sys.path} and which were imported using the

standard Python module importer will not be candidates for reloading.

Even where modules are candidates for module reloading, unless a true

value was explicitly supplied as the \var{autoreload} option to the

\code{apache.import_module()} function they will only be reloaded if the

\code{PythonAutoReload} directive is \code{On}. The default value when

the directive is not specified will be \code{On}, so the directive need

only be used when wishing to set it to \code{Off} to disable automatic

reloading, such as in a production system.

Where possible, the \code{PythonAutoReload} directive should only be

specified in one place and in the root context for a specific Python

interpreter instance. If the \code{PythonAutoReload} directive is used in

multiple places with different values, or doesn't cover all directories

pertaining to a specific Python interpreter instance, then problems can

result. This is because requests against some URLs may result in modules

being reloaded whereas others may not, even when through each URL the

same module may be imported from a common location.

If absolute certainty is required that module reloading is disabled and

that it isn't being enabled through some subset of URLs, the

\code{PythonImport} directive should be used to import a special module

whenever an Apache child process is being created. This module should

include a call to the \code{apache.freeze_modules()} function. This

will have the effect of permanently disabling module reloading for the

complete life of that Apache child process, irrespective of what value

the \code{PythonAutoReload} directive is set to.

Using the new ability within mod_python 3.3 to have \code{PythonImport}

call a specific function within a module after it has been imported,

one could actually dispense with creating a module and instead call

the function directory out of the \code{mod_python.apache} module.

For example:

\begin{verbatim}

\end{verbatim}

Where module reloading is being undertaken, unlike the core module

importer in versions of mod_python prior to 3.3, they are not reloaded on

top of existing modules, but into a completely new module instance. This

means that any code that previously relied on state information or data

caches to be preserved across reloads will no longer work.

If it is necessary to transfer such information from an old module to the

new module, it is necessary to provide a hook function within modules to

transfer across the data that must be preserved. The name of this hook

function is \code{__mp_clone__()}. The argument given to the hook

function will be an empty module into which the new module will subsequently

be loaded.

When called, the hook function should copy any data from the old module

to the new module. In doing this, the code performing the copying should

be cognizant of the fact that within a multithreaded Apache MPM that

other request handlers could still be trying to access and update the

data to be copied. As such, the hook function should ensure that it uses

any thread locking mechanisms within the module as appropriate when

copying the data. Further, it should copy the actual data locks

themselves across to the new module to ensure a clean transition.

Because copying integral values will result in the data then being

separate, it may be necessary to always store data within a dictionary so

as to provide a level of indirection which will allow the data to be

usable from both module instances while they still exist.

For example:

\begin{verbatim}

\end{verbatim}

Because the old module is about to be discarded, the data which is

transferred should not consist of data objects which are dependent on

code within the old module. Data being copied across to the new module

should consist of standard Python data types, or be instances of classes

contained within modules which themselves are not candidates for

reloading. Otherwise, data should be migrated by transforming it into

some neutral intermediate state, with the new module transforming it back

when its code executes at the time of being imported.

If these guidelines aren't heeded and data is dependent on code objects

within the old module, it will prevent those code objects from being

unloaded and if this continues across multiple reloads, then process size

may increase over time due to old code objects being retained.

In any case, if for some reason the hook function fails and an exception

is raised then both the old and new modules will be discarded. As a last

opportunity to release any resources when this occurs, an extra hook

function called \code{__mp_purge__()} can be supplied. This function will

be called with no arguments.

\end{funcdesc}

\begin{funcdesc}{allow_methods}{\optional{*args}}

A convenience function to set values in \member{req.allowed}.

\member{req.allowed} is a bitmask that is used to construct the

\samp{Allow:} header. It should be set before returning a

\code{HTTP_NOT_IMPLEMENTED} error.

Arguments can be one or more of the following:

\begin{verbatim}

\end{verbatim}

\end{funcdesc}

\begin{funcdesc}{exists_config_define}{name}

This function returns True if the Apache server was launched

with the definition with the given \var{name}. This means

that you can test whether Apache was launched with the \code{-DFOOBAR}

parameter by calling \code{apache.exists_config_define('FOOBAR')}.

\end{funcdesc}

\begin{funcdesc}{stat}{fname, wanted}

This function returns an instance of an \code{mp_finfo} object

describing information related to the file with name \code{fname}.

The \code{wanted} argument describes the minimum attributes which

should be filled out. The resultant object can be assigned to the

\code{req.finfo} attribute.

\end{funcdesc}

\begin{funcdesc}{register_cleanup}{callable\optional{, data}}

Registers a cleanup that will be performed at child shutdown time. Equivalent

to \function{server.register_cleanup()}, except that a request object is not

required.

\emph{Warning:} do not pass directly or indirectly a request object in the

data parameter. Since the callable will be called at server shutdown time,

the request object won't exist anymore and any manipulation of it in the

handler will give undefined behaviour.

\end{funcdesc}

\begin{funcdesc}{config_tree}{}

Returns the server-level configuration tree. This tree does not

include directives from .htaccess files. This is a \emph{copy} of

the tree, modifying it has no effect on the actual configuration.

\end{funcdesc}

\begin{funcdesc}{server_root}{}

Returns the value of ServerRoot.

\end{funcdesc}

\begin{funcdesc}{make_table}{}

This function is obsolete and is an alias to \class{table} (see below).

\end{funcdesc}

\begin{funcdesc}{mpm_query}{code}

Allows querying of the MPM for various parameters such as numbers of

processes and threads. The return value is one of three constants:

\begin{verbatim}

\end{verbatim}

The \var{code} argument must be one of the following:

\begin{verbatim}

\end{verbatim}

Example:

\begin{verbatim}

\end{verbatim}

\end{funcdesc}

\subsection{Attributes\label{pyapi-apmem}}

\begin{memberdesc}[apache]{interpreter}

The name of the subinterpreter under which we're running.

\emph{(Read-Only)}

\end{memberdesc}

\begin{memberdesc}[apache]{main_server}

A \code{server} object for the main server.

\emph{(Read-Only})

\end{memberdesc}

\subsection{Table Object (mp_table)\obindex{table}\label{pyapi-mptable}}

\index{table}

\begin{classdesc}{table}{\optional{mapping-or-sequence}}

Returns a new empty object of type \code{mp_table}. See Section

\ref{pyapi-mptable} for description of the table object. The

\var{mapping-or-sequence} will be used to provide initial values for

the table.

The table object is a wrapper around the Apache APR table. The table

object behaves very much like a dictionary (including the Python 2.2

features such as support of the \code{in} operator, etc.), with the

following differences:

\begin{itemize}

\item

Both keys and values must be strings.

\item

Key lookups are case-insensitive.

\item

Duplicate keys are allowed (see \method{add()} below). When there is

more than one value for a key, a subscript operation returns a list.

\end{itemize}

Much of the information that Apache uses is stored in tables. For

example, \member{req.headers_in} and \member{req.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.

In addition to normal dictionary-like behavior, the table object also

has the following method:

\begin{methoddesc}[table]{add}{key, val}

\function{add()} allows for creating duplicate keys, which is useful

when multiple headers, such as \code{Set-Cookie:} are required.

\end{methoddesc}

\versionadded{3.0}

\end{classdesc}

\subsection{Request Object\index{request}\label{pyapi-mprequest}}

The request object is a Python mapping to the Apache

\code{request_rec} structure. When a handler is invoked, it is always

passed a single argument - the request object.

You can dynamically assign attributes to it as a way to communicate

between handlers.

\subsubsection{Request Methods\label{pyapi-mprequest-meth}}

\begin{methoddesc}[request]{add_common_vars}{}

Calls the Apache \cfunction{ap_add_common_vars()} function. After a

call to this method, \member{req.subprocess_env} will contain a

lot of CGI information.

\end{methoddesc}

\begin{methoddesc}[request]{add_handler}{htype, handler\optional{, dir}}

Allows dynamic handler registration. \var{htype} is a string

containing the name of any of the apache request (but not filter or

connection) handler directives,

e.g. \samp{PythonHandler}. \var{handler} is a string containing the

name of the module and the handler function, or the callable object

itself. Optional \var{dir} is a string containing the name of the

directory to be added to the module search path when looking for the

handler. If no directory is specified, then the directory to search

in is inherited from the handler which is making the registration,