Apache Configuration Directives



PythonDebug

Syntax: PythonDebug {On, Off}
Default: PythonDebug Off
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

Normally, the traceback output resulting from uncaught Python errors is sent to the error log. With PythonDebug On directive specified, the output will be sent to the client (as well as the log), except when the error is IOError while writing, in which case it will go to the error log.

This directive is very useful during the development process. It is recommended that you do not use it production environment as it may reveal to the client unintended, possibly sensitive security information.


PythonImport

Syntax: PythonImport module ...
Context: directory
Module: mod_python.c

Tells the server to import the Python module module at process startup. This is useful for initialization tasks that could be time consuming and should not be done at the request processing time, e.g. initializing a database connection.

The import takes place at child process initialization, so the module will actually be imported once for every child process spawned.

Note that at the time when the import takes place, the configuration is not completely read yet, so all other directives, including PythonInterpreter have no effect on the behaviour of modules imported by this directive. Because of this limitation, the use of this directive should be limited to situations where it is absolutely necessary, and the recommended approach to one-time initializations should be to use the Python import mechanism.

The module will be imported within the subinterpreter according with the directory name specified by the <Directory> directive. For all other subinterpreters, the module will not appear imported.


PythonInterpreter

Syntax: PythonInterpreter name
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

Forces the subinterpreter name to be name, instead of the name assigned by mod_python. Mod_python names subinterpreters by using full path of a directory thereby guaranteeing uniqueness per directory. By using this directive, scripts located in different directories and that would by default be executed in different subinterpreters, can be forced to execute in the same subinterpreter.


PythonInterpPerDirectory

Syntax: PythonInterpPerDirectory {On, Off}
Default: PythonInterpPerDirectory Off
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

Instructs mod_python to name subinterpreters using the directory of the file in the request (request_rec->filename) rather than the directory in which the Python*Handler directive currently in effect was encountered. This means that scripts in different directories will execute in different subinterpreters as opposed to the default policy where scripts effected by the same Handler directive execute in the same subinterpreter, even if they are in different directories.

For example, assume there is a /directory/subdirectory. /directory has an .htaccess file with a PythonHandler directive. /directory/subdirectory doesn't have an .htacess. By default, scripts in /directory and /directory/subdirectory would execute in the same interpreter based on the directory where PythonHandler was encountered (/directory). With PythonInterpPerDirectory, there would be two different interpreters, one for each directory.


PythonNoReload

Syntax: PythonNoReload {On, Off}
Default: PythonNoReload Off
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

Instructs mod_python not to check the modification date of the module file. By default, mod_python checks the time-stamp of the file and reloads the module if the module's file modification date is later than the last import or reload.

This options is useful in production environment where the modules do not change, it will save some processing time and give a small performance gain.


PythonOption

Syntax: PythonOption key value
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

Assigns a key value pair to a table that can be later retrieved by the request.get_options() function. This is useful to pass information between the apache configuration files (httpd.conf, .htaccess, etc) and the Python programs.


PythonPath

Syntax: PythonPath path
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

PythonPath directive sets the PythonPath. The path must be specified in Python list notation, e.g.

 PythonPath "['/usr/local/lib/python1.5', '/usr/local/lib/site_python', '/some/other/place']"
The path specified in this directive will replace the path, not add to it. However, because the value of the directive is evaled, to append a directory to the path, one can specify something like
 PythonPath "sys.path+['/mydir']"
Mod_python tries to minimize the number of evals associated with the PythonPath directive because evals are slow and can negatively impact performance, especially when the directive is specified in an .htaccess file which gets parse at every hit. Mod_python will remember the arguments to the PythonPath directive in the un-evaled form, and before evaling the value it will compare it to the remembered value. If the value is the same, no action is taken. Because of this, you should not rely on the directive as a way to restore the pythonpath to some value if your code changes it.

Note that this directive should not be used as a security measure since the Python path is easily manipulated from within the scripts.


Handlers


Python*Handler Directive Syntax

All Python*Handler directives have the following syntax:
Python*Handler handler [handler] ...
Where handler is a callable object (e.g. a function) that accepts a single argument - request object. Multiple handlers can be specified, in which case they will be called sequentially, from left to right.

A handler has the following syntax:

module[::object] [module::[object]] ...
Where module can be a full module name (package dot notation is accepted), and the optional object is the name of an object inside the module.

Object can also contain dots, in which case it will be resolved from left to right. During resolution, if mod_python encounters an object of type <class>, it will try instantiate it passing it a single argument, a request object.

If no object is specified, then it will default to the directive of the handler, all lower case, with the word "Python" removed. E.g. the default object for PythonAuthenHandler would be authenhandler.

Example:

PythonAuthzHandler mypackage.mymodule::checkallowed

Side note: The "::" was chosen for performance reasons. In order for Python to use objects inside modules, the modules first need to be imported. However, if the separator were simply a ".", it would involve a much more complex process of sequentially evaluating every word to determine whether it is a package, module, class etc. Using the (admittedly un-Python-like) "::" takes the time consuming work of figuring out where the module ends and the object inside of it begins away from mod_python resulting in a modest performance gain..


PythonPostReadRequestHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called after the request has been read but before any other phases have been processed. This is useful to make decisions based upon the input header fields.


PythonTransHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine gives allows for an opportunity to translate the URI into an actual filename, before the server's default rules (Alias directives and the like) are followed.


PythonHeaderParserHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This handler is called to give the module a chance to look at the request headers and take any appropriate specific actions early in the processing sequence.


PythonAccessHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to check for any module-specific restrictions placed upon the requested resource.

For example, this can be used to restrict access by IP number. To do so, you would return HTTP_FORBIDDEN or some such to indicate that access is not allowed.


PythonAuthenHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to check the authentication information sent with the request (such as looking up the user in a database and verifying that the [encrypted] password sent matches the one in the database).

To obtain the username, use req.connection.user. To obtain the password entered by the user, use the req.get_basic_auth_pw() function.

A return of apache.OK means the authentication succeeded. A return of apache.HTTP_UNAUTHORIZED with most browser will bring up the password dialog box again. A return of apache.HTTP_FORBIDDEN will usually show the error on the browser and not bring up the password dialog again. HTTP_FORBIDDEN should be used when authentication succeeded, but the user is not permitted to access a particular URL.

An example authentication handler might look like this:

    def authenhandler(req):

        user = req.connection.user     
        pw = req.get_basic_auth_pw()
        if user == "spam" and pw == "eggs":
            return apache.OK
        else:
            return apache.HTTP_UNAUTHORIZED
    

PythonAuthzHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to check to see if the resource being requested requires authorization.


PythonTypeHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to determine and/or set the various document type information bits, like Content-type (via r->content_type), language, et cetera.


PythonFixupHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to perform any module-specific fixing of header fields, et cetera. It is invoked just before any content-handler.


PythonHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This is the main request handler. 99.99% of your applications will only provide this one handler.


PythonLogHandler

Syntax: Python*Handler syntax
Default: None
Context: server config, virtual host, directory, htaccess
Override: not None
Module: mod_python.c

This routine is called to perform any module-specific logging activities over and above the normal server things.


Last modified: Tue Jul 4 13:14:39 EDT 2000