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. (In fact, this feature is not available from within Python itself and can only be accessed through the C language API.) Python C API provides the ability to create subinterpreters. A more detailed description of a subinterpreter 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. 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 the main interpeter. 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 interpreter name. This name can be any string. The main interpreter is named 'main_interpreter'. The way all other interpreters are named can be controlled by PythonInterp* directives. Default behavior is to name interpreters using the Apache virtual server name (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. PythonInterpPerDirectory and PythonInterpPerDirective directives alter the naming convention to use the absolute path of the directory being accessed, or the directory in which the Python*Handler was encountered, respectively. 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 ends.

You can find out the name of the interpreter under which you’re running by peeking at request.interpreter.

Note

If any 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 '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 'main_interpreter', a range of Python errors can arise, each typically referring to code being run in restricted mode.

Overview of a Request Handler¶

A 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:

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 req variable.)

Every handler can return:

apache.OK, meaning this phase of the request was handled by this handler and no errors occurred.
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.

apache.HTTP_ERROR, meaning an HTTP error occurred. HTTP_ERROR can be any of the following:

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_IM_A_TEAPOT                  = 418
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                 = 510

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() method.

Client data, such as POST requests, can be read by using the request.read() function.

An example of a minimalistic handler might be:

from mod_python import apache

def requesthandler(req):
    req.content_type = "text/plain"
    req.write("Hello World!")
    return apache.OK

Overview of a Filter Handler¶

A filter handler is a function that can alter the input or the output of the server. There are two kinds of filters - input and 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 filter object as its argument. The request object is available as well via 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 filter.pass_on() method.

Filters must first be registered using PythonInputFilter or PythonOutputFilter, then added using the Apache Add/SetInputFilter or 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:

PythonOutputFilter capitalize CAPITALIZE
AddOutputFilter CAPITALIZE .py

And here is what the code for the capitalize.py might look like:

from mod_python import apache

def outputfilter(filter):

    s = filter.read()
    while s:
        filter.write(s.upper())
        s = filter.read()

    if s is None:
        filter.close()

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 request.main value.

For more information on filters, see http://httpd.apache.org/docs-2.4/developer/filters.html.

Overview of a Connection Handler¶

A 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 connection object as an argument.

Connection handlers can be used to implement protocols. Here is an example of a simple echo server:

Apache configuration:

PythonConnectionHandler echo

Contents of echo.py file:

from mod_python import apache

def connectionhandler(conn):

    while 1:
        conn.write(conn.readline())

    return apache.OK

`apache` – Access to Apache Internals.¶

The Python 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 request object also provides an interface to Apache internals, it is covered in its own section of this manual.)

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.apache module defines the following functions and objects. For a more in-depth look at Apache internals, see the Apache Developer Page

Functions¶

apache.log_error(message[, level[, server]])¶

An interface to the Apache ap_log_error() function. message is a string with the error message, level is one of the following flags constants:
APLOG_EMERG
APLOG_ALERT
APLOG_CRIT
APLOG_ERR
APLOG_WARNING
APLOG_NOTICE
APLOG_INFO
APLOG_DEBUG
APLOG_NOERRNO // DEPRECATED

server is a reference to a request.server() object. 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. When server is not specified, the setting of LogLevel does not apply, the LogLevel is dictated by an httpd compile-time default, usually warn.

If you have a reference to a request object available, consider using request.log_error() instead, it will prepend request-specific information such as the source IP of the request to the log entry.

apache.import_module(module_name[, autoreload=1, log=0, path=None])¶

This function can be used to import modules taking advantage of mod_python’s internal mechanism which reloads modules automatically if they have changed since last import.

module_name is a string containing the module name (it can contain dots, e.g. mypackage.mymodule); autoreload indicates whether the module should be reloaded if it has changed since last import; when log is true, a message will be written to the logs when a module is reloaded; path allows restricting modules to specific paths.

Example:

from mod_python import apache
module = apache.import_module('module_name', log=1)

apache.allow_methods([*args])¶

A convenience function to set values in request.allowed(). request.allowed() is a bitmask that is used to construct the 'Allow:' header. It should be set before returning a HTTP_NOT_IMPLEMENTED error.

Arguments can be one or more of the following:

M_GET
M_PUT
M_POST
M_DELETE
M_CONNECT
M_OPTIONS
M_TRACE
M_PATCH
M_PROPFIND
M_PROPPATCH
M_MKCOL
M_COPY
M_MOVE
M_LOCK
M_UNLOCK
M_VERSION_CONTROL
M_CHECKOUT
M_UNCHECKOUT
M_CHECKIN
M_UPDATE
M_LABEL
M_REPORT
M_MKWORKSPACE
M_MKACTIVITY
M_BASELINE_CONTROL
M_MERGE
M_INVALID

apache.exists_config(name)¶: This function returns True if the Apache server was launched with the definition with the given name. This means that you can test whether Apache was launched with the -DFOOBAR parameter by calling apache.exists_config_define('FOOBAR').

apache.stat(fname, wanted)¶: This function returns an instance of an mp_finfo object describing information related to the file with name fname. The wanted argument describes the minimum attributes which should be filled out. The resultant object can be assigned to the request.finfo attribute.

apache.register_cleanup(callable[, data])¶: Registers a cleanup that will be performed at child shutdown time. Equivalent to server.register_cleanup(), except that a request object is not required. 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.

apache.config_tree()¶: Returns the server-level configuration tree. This tree does not include directives from .htaccess files. This is a copy of the tree, modifying it has no effect on the actual configuration.

apache.server_root()¶: Returns the value of ServerRoot.

apache.make_table()¶: This function is obsolete and is an alias to table (see below).

apache.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:

AP_MPMQ_NOT_SUPPORTED      = 0  # This value specifies whether
                                # an MPM is capable of
                                # threading or forking.
AP_MPMQ_STATIC             = 1  # This value specifies whether
                                # an MPM is using a static # of
                                # threads or daemons.
AP_MPMQ_DYNAMIC            = 2  # This value specifies whether
                                # an MPM is using a dynamic # of
                                # threads or daemons.

The code argument must be one of the following:

AP_MPMQ_MAX_DAEMON_USED    = 1  # Max # of daemons used so far
AP_MPMQ_IS_THREADED        = 2  # MPM can do threading
AP_MPMQ_IS_FORKED          = 3  # MPM can do forking
AP_MPMQ_HARD_LIMIT_DAEMONS = 4  # The compiled max # daemons
AP_MPMQ_HARD_LIMIT_THREADS = 5  # The compiled max # threads
AP_MPMQ_MAX_THREADS        = 6  # # of threads/child by config
AP_MPMQ_MIN_SPARE_DAEMONS  = 7  # Min # of spare daemons
AP_MPMQ_MIN_SPARE_THREADS  = 8  # Min # of spare threads
AP_MPMQ_MAX_SPARE_DAEMONS  = 9  # Max # of spare daemons
AP_MPMQ_MAX_SPARE_THREADS  = 10 # Max # of spare threads
AP_MPMQ_MAX_REQUESTS_DAEMON= 11 # Max # of requests per daemon
AP_MPMQ_MAX_DAEMONS        = 12 # Max # of daemons by config

Example:

if apache.mpm_query(apache.AP_MPMQ_IS_THREADED):
    # do something
else:
    # do something else

Attributes¶

apache.interpreter¶: String. The name of the subinterpreter under which we’re running. (Read-Only)

apache.main_server¶: A server object for the main server. (Read-Only)

apache.MODULE_MAGIC_NUMBER_MAJOR¶

Integer. An internal to Apache version number useful to determine whether certain features should be available. See MODULE_MAGIC_NUMBER_MINOR.

Major API changes that could cause compatibility problems for older modules such as structure size changes. No binary compatibility is possible across a change in the major version.

(Read-Only)

apache.MODULE_MAGIC_NUMBER_MINOR¶

Integer. An internal to Apache version number useful to determine whether certain features should be available. See MODULE_MAGIC_NUMBER_MAJOR.

Minor API changes that do not cause binary compatibility problems.

(Read-Only)

Table Object (mp_table)¶

class apache.table([mapping-or-sequence])¶

Returns a new empty object of type mp_table. See Section Table Object (mp_table) for description of the table object. The 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 in operator, etc.), with the following differences:

Both keys and values must be strings.
Key lookups are case-insensitive.
Duplicate keys are allowed (see table.add() below). When there is more than one value for a key, a subscript operation returns a list.

Much of the information that Apache uses is stored in tables. For example, request.headers_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.

In addition to normal dictionary-like behavior, the table object also has the following method:

add(key, val)¶: Allows for creating duplicate keys, which is useful when multiple headers, such as Set-Cookie: are required.

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. For brevity, we often refer to it here and throughout the code as req.

You can dynamically assign attributes to it as a way to communicate between handlers.

Request Methods¶

request.add_cgi_vars()¶: Calls Apache function ap_add_common_vars() followed some code very similar to Apache ap_add_cgi_vars() with the exception of calculating PATH_TRANSLATED value, thereby avoiding sub-requests and filesystem access used in the ap_add_cgi_vars() implementation.

request.add_common_vars()¶

Use of this method is discouraged, use request.add_cgi_vars() instead.

Calls the Apache ap_add_common_vars() function. After a call to this method, request.subprocess_env will contain some CGI information.

request.add_handler(htype, handler[, dir])¶

Allows dynamic handler registration. htype is a string containing the name of any of the apache request (but not filter or connection) handler directives, e.g. 'PythonHandler'. handler is a string containing the name of the module and the handler function. Optional dir is a string containing the name of the directory to be added to the pythonpath. If no directory is specified, then, if there is already a handler of the same type specified, its directory is inherited, otherwise the directory of the presently executing handler is used. If there is a 'PythonPath' directive in effect, then sys.path will be set exactly according to it (no directories added, the dir argument is ignored).

A handler added this way only persists throughout the life of the request. It is possible to register more handlers while inside the handler of the same type. One has to be careful as to not to create an infinite loop this way.

Dynamic handler registration is a useful technique that allows the code to dynamically decide what will happen next. A typical example might be a PythonAuthenHandler that will assign different PythonHandlers based on the authorization level, something like:

if manager:
   req.add_handler("PythonHandler", "menu::admin")
else:
   req.add_handler("PythonHandler", "menu::basic")

Note

If you pass this function an invalid handler, an exception will be generated at the time an attempt is made to find the handler.

request.add_input_filter(filter_name)¶: Adds the named filter into the input filter chain for the current request. The filter should be added before the first attempt to read any data from the request.

request.add_output_filter(filter_name)¶

Adds the named filter into the output filter chain for the current request. The filter should be added before the first attempt to write any data for the response.

Provided that all data written is being buffered and not flushed, this could be used to add the “CONTENT_LENGTH” filter into the chain of output filters. The purpose of the “CONTENT_LENGTH” filter is to add a Content-Length: header to the response.:

req.add_output_filter("CONTENT_LENGTH")
req.write("content",0)

request.allow_methods(methods[, reset])¶

Adds methods to the request.allowed_methods() list. This list will be passed in Allowed: header if HTTP_METHOD_NOT_ALLOWED or HTTP_NOT_IMPLEMENTED is returned to the client. Note that Apache doesn’t do anything to restrict the methods, this list is only used to construct the header. The actual method-restricting logic has to be provided in the handler code.

methods is a sequence of strings. If reset is 1, then the list of methods is first cleared.

request.auth_name()¶: Returns AuthName setting.

request.auth_type()¶: Returns AuthType setting.

request.construct_url(uri)¶

This function returns a fully qualified URI string from the path specified by uri, using the information stored in the request to determine the scheme, server name and port. The port number is not included in the string if it is the same as the default port 80.

For example, imagine that the current request is directed to the virtual server www.modpython.org at port 80. Then supplying '/index.html' will yield the string 'http://www.modpython.org/index.html'.

request.discard_request_body()¶: Tests for and reads any message body in the request, simply discarding whatever it receives.

request.document_root()¶: Returns DocumentRoot setting.

request.get_basic_auth_pw()¶

Returns a string containing the password when Basic authentication is used.

On Python 3 the string will be decoded to Unicode using Latin1.

request.get_config()¶: Returns a reference to the table object containing the mod_python configuration in effect for this request except for Python*Handler and PythonOption (The latter can be obtained via request.get_options(). The table has directives as keys, and their values, if any, as values.

request.get_remote_host([type[, str_is_ip]])¶

This method is used to determine remote client’s DNS name or IP number. The first call to this function may entail a DNS look up, but subsequent calls will use the cached result from the first call.

The optional type argument can specify the following:

apache.REMOTE_HOST Look up the DNS name. Return None if Apache directive HostNameLookups is Off or the hostname cannot be determined.
apache.REMOTE_NAME (Default) Return the DNS name if possible, or the IP (as a string in dotted decimal notation) otherwise.
apache.REMOTE_NOLOOKUP Don’t perform a DNS lookup, return an IP. Note: if a lookup was performed prior to this call, then the cached host name is returned.
apache.REMOTE_DOUBLE_REV Force a double-reverse lookup. On failure, return None.

If str_is_ip is None or unspecified, then the return value is a string representing the DNS name or IP address.

If the optional str_is_ip argument is not None, then the return value is an (address, str_is_ip) tuple, where str_is_ip is non-zero if address is an IP address string.

On failure, None is returned.

request.get_options()¶: Returns a reference to the table object containing the options set by the PythonOption directives.

request.internal_redirect(new_uri)¶

Internally redirects the request to the new_uri. new_uri must be a string.

The httpd server handles internal redirection by creating a new request object and processing all request phases. Within an internal redirect, request.prev() will contain a reference to a request object from which it was redirected.

request.is_https()¶

Returns non-zero if the connection is using SSL/TLS. Will always return zero if the mod_ssl Apache module is not loaded.

You can use this method during any request phase, unlike looking for the HTTPS variable in the request.subprocess_env member dictionary. This makes it possible to write an authentication or access handler that makes decisions based upon whether SSL is being used.

Note that this method will not determine the quality of the encryption being used. For that you should call the ssl_var_lookup method to get one of the SSL_CIPHER* variables.

request.log_error(message[, level])¶

An interface to the Apache ap_log_rerror function. message is a string with the error message, level is one of the following flags constants:

APLOG_EMERG
APLOG_ALERT
APLOG_CRIT
APLOG_ERR
APLOG_WARNING
APLOG_NOTICE
APLOG_INFO
APLOG_DEBUG
APLOG_NOERRNO

If you need to write to log and do not have a reference to a request object, use the apache.log_error() function.

request.meets_conditions()¶

Calls the Apache ap_meets_conditions() function which returns a status code. If status is apache.OK, generate the content of the response normally. If not, simply return status. Note that mtime (and possibly the ETag header) should be set as appropriate prior to calling this function. The same goes for request.status() if the status differs from apache.OK.

Example:

# ...
r.headers_out['ETag'] = '"1130794f-3774-4584-a4ea-0ab19e684268"'
r.headers_out['Expires'] = 'Mon, 18 Apr 2005 17:30:00 GMT'
r.update_mtime(1000000000)
r.set_last_modified()

status = r.meets_conditions()
if status != apache.OK:
   return status

# ... do expensive generation of the response content ...

request.requires()¶

Returns a tuple of strings of arguments to require directive.

For example, with the following apache configuration:

AuthType Basic
require user joe
require valid-user

request.requires() would return ('user joe', 'valid-user').

request.read([len])¶

Reads at most len bytes directly from the client, returning a string with the data read. If the len argument is negative or omitted, reads all data given by the client.

This function is affected by the Timeout Apache configuration directive. The read will be aborted and an IOError raised if the Timeout is reached while reading client data.

This function relies on the client providing the Content-length header. Absence of the Content-length header will be treated as if Content-length: 0 was supplied.

Incorrect Content-length may cause the function to try to read more data than available, which will make the function block until a Timeout is reached.

On Python 3 the output is always bytes.

request.readline([len])¶: Like request.read() but reads until end of line.

Note

In accordance with the HTTP specification, most clients will be terminating lines with '\r\n' rather than simply '\n'.

request.readlines([sizehint])¶: Reads all lines using request.readline() and returns a list of the lines read. If the optional sizehint parameter is given in, the method will read at least sizehint bytes of data, up to the completion of the line in which the sizehint bytes limit is reached.

request.register_cleanup(callable[, data])¶

Registers a cleanup. Argument callable can be any callable object, the optional argument data can be any object (default is None). At the very end of the request, just before the actual request record is destroyed by Apache, callable will be called with one argument, data.

It is OK to pass the request object as data, but keep in mind that when the cleanup is executed, the request processing is already complete, so doing things like writing to the client is completely pointless.

If errors are encountered during cleanup processing, they should be in error log, but otherwise will not affect request processing in any way, which makes cleanup bugs sometimes hard to spot.

If the server is shut down before the cleanup had a chance to run, it’s possible that it will not be executed.

request.register_input_filter(filter_name, filter[, dir])¶

Allows dynamic registration of mod_python input filters. filter_name is a string which would then subsequently be used to identify the filter. filter is a string containing the name of the module and the filter function. Optional dir is a string containing the name of the directory to be added to the pythonpath. If there is a PythonPath directive in effect, then sys.path will be set exactly according to it (no directories added, the dir argument is ignored).

The registration of the filter this way only persists for the life of the request. To actually add the filter into the chain of input filters for the current request request.add_input_filter() would be used.

request.register_output_filter(filter_name, filter[, dir])¶

Allows dynamic registration of mod_python output filters. filter_name is a string which would then subsequently be used to identify the filter. filter is a string containing the name of the module and the filter function. Optional dir is a string containing the name of the directory to be added to the pythonpath. If there is a PythonPath directive in effect, then sys.path will be set exactly according to it (no directories added, the dir argument is ignored).

The registration of the filter this way only persists for the life of the request. To actually add the filter into the chain of output filters for the current request request.add_output_filter() would be used.

request.sendfile(path[, offset, len])¶

Sends len bytes of file path directly to the client, starting at offset offset using the server’s internal API. offset defaults to 0, and len defaults to -1 (send the entire file).

Returns the number of bytes sent, or raises an IOError exception on failure.

This function provides the most efficient way to send a file to the client.

request.set_etag()¶: Sets the outgoing 'ETag' header.

request.set_last_modified()¶: Sets the outgoing Last-Modified header based on value of mtime attribute.

request.ssl_var_lookup(var_name)¶

Looks up the value of the named SSL variable. This method queries the mod_ssl Apache module directly, and may therefore be used in early request phases (unlike using the request.subprocess_env member.

If the mod_ssl Apache module is not loaded or the variable is not found then None is returned.

If you just want to know if a SSL or TLS connection is being used, you may consider calling the is_https method instead.

It is unfortunately not possible to get a list of all available variables with the current mod_ssl implementation, so you must know the name of the variable you want. Some of the potentially useful ssl variables are listed below. For a complete list of variables and a description of their values see the mod_ssl documentation.:

SSL_CIPHER
SSL_CLIENT_CERT
SSL_CLIENT_VERIFY
SSL_PROTOCOL
SSL_SESSION_ID

Note

Not all SSL variables are defined or have useful values in every request phase. Also use caution when relying on these values for security purposes, as SSL or TLS protocol parameters can often be renegotiated at any time during a request.

request.update_mtime(dependency_mtime)¶: If ependency_mtime is later than the value in the mtime attribute, sets the attribute to the new value.

request.write(string[, flush=1])¶: Writes string directly to the client, then flushes the buffer, unless flush is 0. Unicode strings are encoded using utf-8 encoding.

request.flush()¶: Flushes the output buffer.

request.set_content_length(len)¶: Sets the value of request.clength and the 'Content-Length' header to len. Note that after the headers have been sent out (which happens just before the first byte of the body is written, i.e. first call to request.write()), calling the method is meaningless.

Request Members¶

request.connection¶: A connection object associated with this request. See Connection Object (mp_conn) Object for more details. (Read-Only)

request.server¶: A server object associated with this request. See Server Object (mp_server) for more details. (Read-Only)

request.next¶: If this is an internal redirect, the request object we redirect to. (Read-Only)

request.prev¶: If this is an internal redirect, the request object we redirect from. (Read-Only)

request.main¶: If this is a sub-request, pointer to the main request. (Read-Only)

request.the_request¶: String containing the first line of the request. (Read-Only)

request.assbackwards¶: Indicates an HTTP/0.9 “simple” request. This means that the response will contain no headers, only the body. Although this exists for backwards compatibility with obsolescent browsers, some people have figured out that setting assbackwards to 1 can be a useful technique when including part of the response from an internal redirect to avoid headers being sent.

request.proxyreq¶: A proxy request: one of apache.PROXYREQ_* values.

request.header_only¶: A boolean value indicating HEAD request, as opposed to GET. (Read-Only)

request.protocol¶: Protocol, as given by the client, or 'HTTP/0.9'. Same as CGI SERVER_PROTOCOL. (Read-Only)

request.proto_num¶: Integer. Number version of protocol; 1.1 = 1001 (Read-Only)

request.hostname¶: String. Host, as set by full URI or Host: header. (Read-Only)

request.request_time¶: A long integer. When request started. (Read-Only)

request.status_line¶: Status line. E.g. '200 OK'. (Read-Only)

request.status¶: Status. One of apache.HTTP_* values.

request.method¶: A string containing the method - 'GET', 'HEAD', 'POST', etc. Same as CGI REQUEST_METHOD. (Read-Only)

request.method_number¶: Integer containing the method number. (Read-Only)

request.allowed¶: Integer. A bitvector of the allowed methods. Used to construct the Allowed: header when responding with HTTP_METHOD_NOT_ALLOWED or HTTP_NOT_IMPLEMENTED. This field is for Apache’s internal use, to set the Allowed: methods use request.allow_methods() method, described in section Request Methods. (Read-Only)

request.allowed_xmethods¶: Tuple. Allowed extension methods. (Read-Only)

request.allowed_methods¶: Tuple. List of allowed methods. Used in relation with METHOD_NOT_ALLOWED. This member can be modified via request.allow_methods() described in section Request Methods. (Read-Only)

request.sent_bodyct¶: Integer. Byte count in stream is for body. (?) (Read-Only)

request.bytes_sent¶: Long integer. Number of bytes sent. (Read-Only)

request.mtime¶: Long integer. Time the resource was last modified. (Read-Only)

request.chunked¶: Boolean value indicating when sending chunked transfer-coding. (Read-Only)

request.range¶: String. The Range: header. (Read-Only)

request.clength¶: Long integer. The “real” content length. (Read-Only)

request.remaining¶: Long integer. Bytes left to read. (Only makes sense inside a read operation.) (Read-Only)

request.read_length¶: Long integer. Number of bytes read. (Read-Only)

request.read_body¶: Integer. How the request body should be read. (Read-Only)

request.read_chunked¶: Boolean. Read chunked transfer coding. (Read-Only)

request.expecting_100¶: Boolean. Is client waiting for a 100 (HTTP_CONTINUE) response. (Read-Only)

request.headers_in¶: A table object containing headers sent by the client.

request.headers_out¶: A table object representing the headers to be sent to the client.

request.err_headers_out¶: These headers get send with the error response, instead of headers_out.

request.subprocess_env¶: A table object containing environment information typically usable for CGI. You may have to call request.add_common_vars() and request.add_cgi_vars() first to fill in the information you need.

request.notes¶: A table object that could be used to store miscellaneous general purpose info that lives for as long as the request lives. If you need to pass data between handlers, it’s better to simply add members to the request object than to use request.notes.

request.phase¶: The phase currently being being processed, e.g. 'PythonHandler'. (Read-Only)

request.interpreter¶: The name of the subinterpreter under which we’re running. (Read-Only)

request.content_type¶: String. The content type. Mod_python maintains an internal flag (request._content_type_set) to keep track of whether request.content_type was set manually from within Python. The publisher handler uses this flag in the following way: when request.content_type isn’t explicitly set, it attempts to guess the content type by examining the first few bytes of the output.

request.content_languages¶: Tuple. List of strings representing the content languages.

request.handler¶

The symbolic name of the content handler (as in module, not mod_python handler) that will service the request during the response phase. When the SetHandler/AddHandler directives are used to trigger mod_python, this will be set to 'mod_python' by mod_mime. A mod_python handler executing prior to the response phase may also set this to 'mod_python' along with calling request.add_handler() to register a mod_python handler for the response phase:

def typehandler(req):
   if os.path.splitext(req.filename)[1] == ".py":
      req.handler = "mod_python"
     req.add_handler("PythonHandler", "mod_python.publisher")
     return apache.OK
   return apache.DECLINED

request.content_encoding¶: String. Content encoding. (Read-Only)

request.vlist_validator¶: Integer. Variant list validator (if negotiated). (Read-Only)

request.user¶

If an authentication check is made, this will hold the user name. Same as CGI REMOTE_USER.

On Python 3 the string is decoded using Latin1. (Different browsers use different encodings for non-Latin1 characters for the basic authentication string making a solution that fits all impossible, you can always decode the header manually.)

Note

request.get_basic_auth_pw() must be called prior to using this value.

request.ap_auth_type¶: Authentication type. Same as CGI AUTH_TYPE.

request.no_cache¶: Boolean. This response cannot be cached.

request.no_local_copy¶: Boolean. No local copy exists.

request.unparsed_uri¶: The URI without any parsing performed. (Read-Only)

request.uri¶: The path portion of the URI.

request.filename¶: String. File name being requested.

request.canonical_filename¶: String. The true filename (request.filename is canonicalized if they don’t match).

request.path_info¶: String. What follows after the file name, but is before query args, if anything. Same as CGI PATH_INFO.

request.args¶: String. Same as CGI QUERY_ARGS.

request.finfo¶

A file information object with type mp_finfo, analogous to the result of the POSIX stat function, describing the file pointed to by the URI. The object provides the attributes fname, filetype, valid, protection, user, group, size, inode, device, nlink, atime, mtime, ctime and name.

The attribute may be assigned to using the result of apache.stat(). For example:

if req.finfo.filetype == apache.APR_DIR:
  req.filename = posixpath.join(req.filename, 'index.html')
  req.finfo = apache.stat(req.filename, apache.APR_FINFO_MIN)

For backward compatibility, the object can also be accessed as if it were a tuple. The apache module defines a set of FINFO_* constants that should be used to access elements of this tuple.:

user = req.finfo[apache.FINFO_USER]

request.parsed_uri¶

Tuple. The URI broken down into pieces. (scheme, hostinfo, user, password, hostname, port, path, query, fragment). The apache module defines a set of URI_* constants that should be used to access elements of this tuple. Example:

fname = req.parsed_uri[apache.URI_PATH]

(Read-Only)

request.used_path_info¶: Flag to accept or reject path_info on current request.

request.eos_sent¶: Boolean. EOS bucket sent. (Read-Only)

request.useragent_addr¶

Apache 2.4 only

The (address, port) tuple for the user agent.

This attribute should reflect the address of the user agent and not necessarily the other end of the TCP connection, for which there is connection.client_addr. (Read-Only)

request.useragent_ip¶

Apache 2.4 only

String with the IP of the user agent. Same as CGI REMOTE_ADDR.

This attribute should reflect the address of the user agent and not necessarily the other end of the TCP connection, for which there is connection.client_ip. (Read-Only)

Connection Object (mp_conn)¶

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

Connection Methods¶

connection.log_error(message[, level])¶

An interface to the Apache ap_log_cerror function. message is a string with the error message, level is one of the following flags constants:

  APLOG_EMERG
  APLOG_ALERT
  APLOG_CRIT
  APLOG_ERR
  APLOG_WARNING
  APLOG_NOTICE
  APLOG_INFO
  APLOG_DEBUG
  APLOG_NOERRNO

If you need to write to log and do not have a reference to a connection or
request object, use the :func:`apache.log_error` function.

connection.read([length])¶

Reads at most length bytes from the client. The read blocks indefinitely until there is at least one byte to read. If length is -1, keep reading until the socket is closed from the other end (This is known as EXHAUSTIVE mode in the http server code).

This method should only be used inside Connection Handlers.

Note

The behavior of this method has changed since version 3.0.3. In 3.0.3 and prior, this method would block until length bytes was read.

connection.readline([length])¶

Reads a line from the connection or up to length bytes.

This method should only be used inside Connection Handlers.

connection.write(string)¶

Writes string to the client.

This method should only be used inside Connection Handlers.

Connection Members¶

connection.base_server¶: A server object for the physical vhost that this connection came in through. (Read-Only)

connection.local_addr¶: The (address, port) tuple for the server. (Read-Only)

connection.remote_addr¶

Deprecated in Apache 2.4, use client_addr. (Aliased to client_addr for backward compatibility)

The (address, port) tuple for the client. (Read-Only)

connection.client_addr¶

Apache 2.4 only

The (address, port) tuple for the client.

This attribute reflects the other end of the TCP connection, which may not always be the address of the user agent. A more accurate source of the user agent address is request.useragent_addr. (Read-Only)

connection.remote_ip¶

Deprecated in Apache 2.4, use client_ip. (Aliased to client_ip for backward compatibility)

String with the IP of the client. In Apache 2.2 same as CGI REMOTE_ADDR. (Read-Only)

connection.client_ip¶

Apache 2.4 only

String with the IP of the client.

This attribute reflects the other end of the TCP connection, which may not always be the address of the user agent. A more accurate source of the user agent address is request.useragent_ip.

(Read-Only)

connection.remote_host¶: String. The DNS name of the remote client. None if DNS has not been checked, '' (empty string) if no name found. Same as CGI REMOTE_HOST. (Read-Only)

connection.remote_logname¶: Remote name if using RFC 1413 (ident). Same as CGI REMOTE_IDENT. (Read-Only)

connection.aborted¶: Boolean. True is the connection is aborted. (Read-Only)

connection.keepalive¶: Integer. 1 means the connection will be kept for the next request, 0 means “undecided”, -1 means “fatal error”. (Read-Only)

connection.double_reverse¶: Integer. 1 means double reverse DNS lookup has been performed, 0 means not yet, -1 means yes and it failed. (Read-Only)

connection.keepalives¶: The number of times this connection has been used. (?) (Read-Only)

connection.local_ip¶: String with the IP of the server. (Read-Only)

connection.local_host¶: DNS name of the server. (Read-Only)

connection.id¶: Long. A unique connection id. (Read-Only)

connection.notes¶: A table object containing miscellaneous general purpose info that lives for as long as the connection lives.

Filter Object (mp_filter)¶

A filter object is passed to mod_python input and output filters. It is used to obtain filter information, as well as get and pass information to adjacent filters in the filter stack.

Filter Methods¶

filter.pass_on()¶: Passes all data through the filter without any processing.

filter.read([length])¶

Reads at most len bytes from the next filter, returning a string with the data read or None if End Of Stream (EOS) has been reached. A filter must be closed once the EOS has been encountered.

If the length argument is negative or omitted, reads all data currently available.

filter.readline([length])¶: Reads a line from the next filter or up to length bytes.

filter.write(string)¶: Writes string to the next filter.

filte.flush()¶: Flushes the output by sending a FLUSH bucket.

filter.close()¶: Closes the filter and sends an EOS bucket. Any further IO operations on this filter will throw an exception.

filter.disable()¶: Tells mod_python to ignore the provided handler and just pass the data on. Used internally by mod_python to print traceback from exceptions encountered in filter handlers to avoid an infinite loop.

Filter Members¶

filter.closed¶: A boolean value indicating whether a filter is closed. (Read-Only)

filter.name¶: String. The name under which this filter is registered. (Read-Only)

filter.req¶: A reference to the request object. (Read-Only)

filter.is_input¶: Boolean. True if this is an input filter. (Read-Only)

filter.handler¶: String. The name of the Python handler for this filter as specified in the configuration. (Read-Only)

Server Object (mp_server)¶

The request object is a Python mapping to the Apache request_rec structure. The server structure describes the server (possibly virtual server) serving the request.

Server Methods¶

server.get_config()¶: Similar to request.get_config(), but returns a table object holding only the mod_python configuration defined at global scope within the Apache configuration. That is, outside of the context of any VirtualHost, Location, Directory or Files directives.

server.get_options()¶: Similar to request.get_options(), but returns a table object holding only the mod_python options defined at global scope within the Apache configuration. That is, outside of the context of any VirtualHost, Location, Directory or Files directives.

server.log_error(message[level])¶

An interface to the Apache ap_log_error function. message is a string with the error message, level is one of the following flags constants:

APLOG_EMERG
APLOG_ALERT
APLOG_CRIT
APLOG_ERR
APLOG_WARNING
APLOG_NOTICE
APLOG_INFO
APLOG_DEBUG
APLOG_NOERRNO

If you need to write to log and do not have a reference to a server or request object, use the apache.log_error() function.

server.register_cleanup(request, callable[, data])¶: Registers a cleanup. Very similar to req.register_cleanup(), except this cleanup will be executed at child termination time. This function requires the request object be supplied to infer the interpreter name. If you don’t have any request object at hand, then you must use the apache.register_cleanup() variant.

Note

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 callable will give undefined behaviour.

Server Members¶

server.defn_name¶: String. The name of the configuration file where the server definition was found. (Read-Only)

server.defn_line_number¶: Integer. Line number in the config file where the server definition is found. (Read-Only)

server.server_admin¶: Value of the ServerAdmin directive. (Read-Only)

server.server_hostname¶: Value of the ServerName directive. Same as CGI SERVER_NAME. (Read-Only)

server.names¶: Tuple. List of normal server names specified in the ServerAlias directive. This list does not include wildcarded names, which are listed separately in wild_names. (Read-Only)

server.wild_names¶: Tuple. List of wildcarded server names specified in the ServerAlias directive. (Read-Only)

server.port¶: Integer. TCP/IP port number. Same as CGI SERVER_PORT. This member appears to be 0 on Apache 2.0, look at req.connection.local_addr instead (Read-Only)

server.error_fname¶: The name of the error log file for this server, if any. (Read-Only)

server.loglevel¶: Integer. Logging level. (Read-Only)

server.is_virtual¶: Boolean. True if this is a virtual server. (Read-Only)

server.timeout¶: Integer. Value of the Timeout directive. (Read-Only)

server.keep_alive_timeout¶: Integer. Keepalive timeout. (Read-Only)

server.keep_alive_max¶: Maximum number of requests per keepalive. (Read-Only)

server.keep_alive¶: Use persistent connections? (Read-Only)

server.path¶: String. Path for ServerPath (Read-Only)

server.pathlen¶: Integer. Path length. (Read-Only)

server.limit_req_line¶: Integer. Limit on size of the HTTP request line. (Read-Only)

server.limit_req_fieldsize¶: Integer. Limit on size of any request header field. (Read-Only)

server.limit_req_fields¶: Integer. Limit on number of request header fields. (Read-Only)

`util` – Miscellaneous Utilities¶

The util module provides a number of utilities handy to a web application developer similar to those in the standard library cgi module. The implementations in the util module are much more efficient because they call directly into Apache API’s as opposed to using CGI which relies on the environment to pass information.

The recommended way of using this module is:

from mod_python import util

FieldStorage class¶

Access to form data is provided via the FieldStorage class. This class is similar to the standard library module cgi.FieldStorage

class util.FieldStorage(req[, keep_blank_values[, strict_parsing[, file_callback[, field_callback]]]])¶

This class provides uniform access to HTML form data submitted by the client. req is an instance of the mod_python request object.

The optional argument keep_blank_values is a flag indicating whether blank values in URL encoded form data should be treated as blank strings. The default is false, which means that blank values are ignored as if they were not included.

The optional argument strict_parsing is not yet implemented.

The optional argument file_callback allows the application to override both file creation/deletion semantics and location. See FieldStorage Examples for additional information. New in version 3.2

The optional argument field_callback allows the application to override both the creation/deletion semantics and behavior. New in version 3.2

During initialization, FieldStorage class reads all of the data provided by the client. Since all data provided by the client is consumed at this point, there should be no more than one FieldStorage class instantiated per single request, nor should you make any attempts to read client data before or after instantiating a FieldStorage. A suggested strategy for dealing with this is that any handler should first check for the existence of a form attribute within the request object. If this exists, it should be taken to be an existing instance of the FieldStorage class and that should be used. If the attribute does not exist and needs to be created, it should be cached as the form attribute of the request object so later handler code can use it.

When the FieldStorage class instance is created, the data read from the client is then parsed into separate fields and packaged in Field objects, one per field. For HTML form inputs of type file, a temporary file is created that can later be accessed via the Field.file attribute of a Field object.

The FieldStorage class has a mapping object interface, i.e. it can be treated like a dictionary in most instances, but is not strictly compatible as is it missing some methods provided by dictionaries and some methods don’t behave entirely like their counterparts, especially when there is more than one value associated with a form field. When used as a mapping, the keys are form input names, and the returned dictionary value can be:

An instance of StringField, containing the form input value. This is only when there is a single value corresponding to the input name. StringField is a subclass of str which provides the additional StringField.value attribute for compatibility with standard library cgi module.
An instance of a Field class, if the input is a file upload.
A list of StringField and/or Field objects. This is when multiple values exist, such as for a <select> HTML form element.

Note

Unlike the standard library cgi module FieldStorage class, a Field object is returned only when it is a file upload. In all other cases the return is an instance of StringField. This means that you do not need to use the StringFile.value attribute to access values of fields in most cases.

In addition to standard mapping object methods, FieldStorage objects have the following attributes:

list¶: This is a list of Field objects, one for each input. Multiple inputs with the same name will have multiple elements in this list.

`FieldStorage` methods¶

util.add_field(name, value)¶

Adds an additional form field with name and value. If a form field already exists with name, the value will be added to the list of existing values for the form field. This method should be used for adding additional fields in preference to adding new fields direct to the list of fields.

If the value associated with a field should be replaced when it already exists, rather than an additional value being associated with the field, the dictionary like subscript operator should be used to set the value, or the existing field deleted altogether first using the del operator.

util.clear()¶

Removes all form fields. Individual form fields can be deleted using the del operator.

util.get(name, default)¶

If there is only one value associated with form field name, that single value will be returned. If there are multiple values, a list is returned holding all values. If no such form field or value exists then the method returns the value specified by the parameter default. A subscript operator is also available which yields the same result except that an exception will be raised where the form field name does not exist.

util.getfirst(name[, default])¶

Always returns only one value associated with form field name. If no such form field or value exists then the method returns the value specified by the optional parameter default. This parameter defaults to None if not specified.

util.getlist(name)¶

This method always returns a list of values associated with form field name. The method returns an empty list if no such form field or value exists for name. It returns a list consisting of one item if only one such value exists.

util.has_key(name)¶

Returns True if name is a valid form field. The in operator is also supported and will call this method.

util.items()¶

Returns a list consisting of tuples for each combination of form field name and value.

util.keys()¶

This method returns the names of the form fields. The len operator is also supported and will return the number of names which would be returned by this method.

FieldStorage Examples¶

The following examples demonstrate how to use the file_callback parameter of the FieldStorage constructor to control file object creation. The Storage classes created in both examples derive from FileType, thereby providing extended file functionality.

These examples are provided for demonstration purposes only. The issue of temporary file location and security must be considered when providing such overrides with mod_python in production use.

Simple file control using class constructor¶

This example uses the FieldStorage class constructor to create the file object, allowing simple control. It is not advisable to add class variables to this if serving multiple sites from apache. In that case use the factory method instead:

class Storage(file):

   def __init__(self, advisory_filename):
       self.advisory_filename = advisory_filename
       self.delete_on_close = True
       self.already_deleted = False
       self.real_filename = '/someTempDir/thingy-unique-thingy'
       super(Storage, self).__init__(self.real_filename, 'w+b')

   def close(self):
       if self.already_deleted:
           return
       super(Storage, self).close()
       if self.delete_on_close:
           self.already_deleted = True
           os.remove(self.real_filename)

   request_data = util.FieldStorage(request, keep_blank_values=True, file_callback=Storage)

Advanced file control using object factory¶

Using a object factory can provide greater control over the constructor parameters:

import os

class Storage(file):

    def __init__(self, directory, advisory_filename):
        self.advisory_filename = advisory_filename
        self.delete_on_close = True
        self.already_deleted = False
        self.real_filename = directory + '/thingy-unique-thingy'
        super(Storage, self).__init__(self.real_filename, 'w+b')

    def close(self):
        if self.already_deleted:
            return
        super(Storage, self).close()
        if self.delete_on_close:
            self.already_deleted = True
            os.remove(self.real_filename)

class StorageFactory:

    def __init__(self, directory):
        self.dir = directory

    def create(self, advisory_filename):
        return Storage(self.dir, advisory_filename)

file_factory = StorageFactory(someDirectory)
# [...sometime later...]
request_data = util.FieldStorage(request, keep_blank_values=True,
                                 file_callback=file_factory.create)

Field class¶

class util.Field¶

This class is used internally by FieldStorage and is not meant to be instantiated by the user. Each instance of a Field class represents an HTML Form input.

Field instances have the following attributes:

name¶: The input name.

value¶: The input value. This attribute can be used to read data from a file upload as well, but one has to exercise caution when dealing with large files since when accessed via value, the whole file is read into memory.

file¶

This is a file-like object. For file uploads it points to a TemporaryFile instance. (For more information see the TemporaryFile class in the standard python tempfile module.

For simple values, it is a StringIO object, so you can read simple string values via this attribute instead of using the value attribute as well.

filename¶: The name of the file as provided by the client.

type¶: The content-type for this input as provided by the client.

type_options¶: This is what follows the actual content type in the content-type header provided by the client, if anything. This is a dictionary.

disposition¶: The value of the first part of the content-disposition header.

disposition_options¶: The second part (if any) of the content-disposition header in the form of a dictionary.

Other functions¶

util.parse_qs(qs[, keep_blank_values[, strict_parsing]])¶: This function is functionally equivalent to the standard library cgi.parse_qs(), except that it is written in C and is much faster.

Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are returned as a dictionary. The dictionary keys are the unique query variable names and the values are lists of values for each name.

The optional argument keep_blank_values is a flag indicating whether blank values in URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that blank values are to be ignored and treated as if they were not included.

Note

The strict_parsing argument is not yet implemented.

util.parse_qsl(qs[, keep_blank_values[, strict_parsing]])¶: This function is functionally equivalent to the standard library cgi.parse_qsl(), except that it is written in C and is much faster.

Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are returned as a list of name, value pairs.

The optional argument keep_blank_values is a flag indicating whether blank values in URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that blank values are to be ignored and treated as if they were not included.

Note

The strict_parsing argument is not yet implemented.

util.redirect(req, location[, permanent=0[, text=None]])¶: This is a convenience function to redirect the browser to another location. When permanent is true, MOVED_PERMANENTLY status is sent to the client, otherwise it is MOVED_TEMPORARILY. A short text is sent to the browser informing that the document has moved (for those rare browsers that do not support redirection); this text can be overridden by supplying a text string.

If this function is called after the headers have already been sent, an IOError is raised.

This function raises apache.SERVER_RETURN exception with a value of apache.DONE to ensuring that any later phases or stacked handlers do not run. If you do not want this, you can wrap the call to redirect() in a try/except block catching the apache.SERVER_RETURN.

`Session` – Session Management¶

The Session module provides objects for maintaining persistent sessions across requests.

The module contains a BaseSession class, which is not meant to be used directly (it provides no means of storing a session), DbmSession class, which uses a dbm to store sessions, and FileSession class, which uses individual files to store sessions.

The BaseSession class also provides session locking, both across processes and threads. For locking it uses APR global_mutexes (a number of them is pre-created at startup) The mutex number is computed by using modulus of the session id hash(). (Therefore it’s possible that different session id’s will have the same hash, but the only implication is that those two sessions cannot be locked at the same time resulting in a slight delay.)

Classes¶

Session.Session(req[, sid[, secret[, timeout[, lock]]]])¶

Session() takes the same arguments as BaseSession.

This function returns a instance of the default session class. The session class to be used can be specified using PythonOption mod_python.session.session_type value, where value is one of DbmSession, MemorySession or FileSession. Specifying custom session classes using PythonOption session is not yet supported.

If session type option is not found, the function queries the MPM and based on that returns either a new instance of DbmSession or MemorySession. MemorySession will be used if the MPM is threaded and not forked (such is the case on Windows), or if it threaded, forked, but only one process is allowed (the worker MPM can be configured to run this way). In all other cases DbmSession is used.

Note that on Windows if you are using multiple Python interpreter instances and you need sessions to be shared between applications running within the context of the distinct Python interpreter instances, you must specifically indicate that DbmSession should be used, as MemorySession will only allow a session to be valid within the context of the same Python interpreter instance.

Also note that the option name mod_python.session.session_type only started to be used from mod_python 3.3 onwards. If you need to retain compatibility with older versions of mod_python, you should use the now obsolete session option instead.

class Session.BaseSession(req[, sid[, secret[, timeout[, lock]]]])¶

This class is meant to be used as a base class for other classes that implement a session storage mechanism. req is a required reference to a mod_python request object.

BaseSession is a subclass of dict. Data can be stored and retrieved from the session by using it as a dictionary.

sid is an optional session id; if provided, such a session must already exist, otherwise it is ignored and a new session with a new sid is created. If sid is not provided, the object will attempt to look at cookies for session id. If a sid is found in cookies, but it is not previously known or the session has expired, then a new sid is created. Whether a session is “new” can be determined by calling the is_new() method.

Cookies generated by sessions will have a path attribute which is calculated by comparing the server DocumentRoot and the directory in which the PythonHandler directive currently in effect was specified. E.g. if document root is /a/b/c and the directory PythonHandler was specified was /a/b/c/d/e, the path will be set to /d/e.

The deduction of the path in this way will only work though where the Directory directive is used and the directory is actually within the document root. If the Location directive is used or the directory is outside of the document root, the path will be set to /. You can force a specific path by setting the mod_python.session.application_path option ('PythonOption mod_python.session.application_path /my/path' in server configuration).

Note that prior to mod_python 3.3, the option was ApplicationPath. If your system needs to be compatible with older versions of mod_python, you should continue to use the now obsolete option name.

The domain of a cookie is by default not set for a session and as such the session is only valid for the host which generated it. In order to have a session which spans across common sub domains, you can specify the parent domain using the mod_python.session.application_domain option ('PythonOption mod_python.session.application_domain mod_python.org' in server configuration).

When a secret is provided, BaseSession will use SignedCookie when generating cookies thereby making the session id almost impossible to fake. The default is to use plain Cookie (though even if not signed, the session id is generated to be very difficult to guess).

A session will timeout if it has not been accessed and a save performed, within the timeout period. Upon a save occurring the time of last access is updated and the period until the session will timeout be reset. The default timeout period is 30 minutes. An attempt to load an expired session will result in a “new” session.

The lock argument (defaults to 1) indicates whether locking should be used. When locking is on, only one session object with a particular session id can be instantiated at a time.

A session is in “new” state when the session id was just generated, as opposed to being passed in via cookies or the sid argument.

is_new()¶

Returns 1 if this session is new. A session will also be “new” after an attempt to instantiate an expired or non-existent session. It is important to use this method to test whether an attempt to instantiate a session has succeeded, e.g.:

sess = Session(req)
if sess.is_new():
    # redirect to login
    util.redirect(req, 'http://www.mysite.com/login')

id()¶: Returns the session id.

created()¶: Returns the session creation time in seconds since beginning of epoch.

last_accessed()¶: Returns last access time in seconds since beginning of epoch.

timeout()¶: Returns session timeout interval in seconds.

set_timeout(secs)¶: Set timeout to secs.

invalidate()¶: This method will remove the session from the persistent store and also place a header in outgoing headers to invalidate the session id cookie.

load()¶: Load the session values from storage.

save()¶: This method writes session values to storage.

delete()¶: Remove the session from storage.

init_lock()¶: This method initializes the session lock. There is no need to ever call this method, it is intended for subclasses that wish to use an alternative locking mechanism.

lock()¶

Locks this session. If the session is already locked by another thread/process, wait until that lock is released. There is no need to call this method if locking is handled automatically (default).

This method registeres a cleanup which always unlocks the session at the end of the request processing.

unlock()¶: Unlocks this session. (Same as lock() - when locking is handled automatically (default), there is no need to call this method).

cleanup()¶: This method is for subclasses to implement session storage cleaning mechanism (i.e. deleting expired sessions, etc.). It will be called at random, the chance of it being called is controlled by CLEANUP_CHANCE Session module variable (default 1000). This means that cleanups will be ordered at random and there is 1 in 1000 chance of it happening. Subclasses implementing this method should not perform the (potentially time consuming) cleanup operation in this method, but should instead use :meth:req.register_cleanup` to register a cleanup which will be executed after the request has been processed.

class Session.DbmSession(req[, dbm[, sid[, secret[, dbmtype[, timeout[, lock]]]]]])¶

This class provides session storage using a dbm file. Generally, dbm access is very fast, and most dbm implementations memory-map files for faster access, which makes their performance nearly as fast as direct shared memory access.

dbm is the name of the dbm file (the file must be writable by the httpd process). This file is not deleted when the server process is stopped (a nice side benefit of this is that sessions can survive server restarts). By default the session information is stored in a dbmfile named mp_sess.dbm and stored in a temporary directory returned by tempfile.gettempdir() standard library function. An alternative directory can be specified using PythonOption mod_python.dbm_session.database_directory /path/to/directory. The path and filename can can be overridden by setting PythonOption mod_python.dbm_session.database_filename filename.

Note that the above names for the PythonOption settings were changed to these values in mod_python 3.3. If you need to retain compatibility with older versions of mod_python, you should continue to use the now obsolete session_directory and session_dbm options.

The implementation uses Python anydbm module, which will default to dbhash on most systems. If you need to use a specific dbm implementation (e.g. gdbm), you can pass that module as dbmtype.

Note that using this class directly is not cross-platform. For best compatibility across platforms, always use the Session() function to create sessions.

class Session.FileSession(req[, sid[, secret[, timeout[, lock[, fast_cleanup[, verify_cleanup]]]]]])¶

New in version 3.2.0.

This class provides session storage using a separate file for each session. It is a subclass of BaseSession.

Session data is stored in a separate file for each session. These files are not deleted when the server process is stopped, so sessions are persistent across server restarts. The session files are saved in a directory named mp_sess in the temporary directory returned by the tempfile.gettempdir() standard library function. An alternate path can be set using PythonOption mod_python.file_session.database_directory /path/to/directory. This directory must exist and be readable and writeable by the apache process.

Note that the above name for the PythonOption setting was changed to these values in mod_python 3.3. If you need to retain compatibility with older versions of mod_python, you should continue to use the now obsolete session_directory option.

Expired session files are periodically removed by the cleanup mechanism. The behaviour of the cleanup can be controlled using the fast_cleanup and verify_cleanup parameters, as well as PythonOption mod_python.file_session.cleanup_time_limit and PythonOption mod_python.file_session.cleanup_grace_period.

fast_cleanup

A boolean value used to turn on FileSession cleanup optimization. Default is True and will result in reduced cleanup time when there are a large number of session files.

When fast_cleanup is True, the modification time for the session file is used to determine if it is a candidate for deletion. If (current_time - file_modification_time) > (timeout + grace_period), the file will be a candidate for deletion. If verify_cleanup is False, no futher checks will be made and the file will be deleted.

If fast_cleanup is False, the session file will unpickled and it’s timeout value used to determine if the session is a candidate for deletion. fast_cleanup = False implies verify_cleanup = True.

The timeout used in the fast_cleanup calculation is same as the timeout for the session in the current request running the filesession_cleanup. If your session objects are not using the same timeout, or you are manually setting the timeout for a particular session with set_timeout(), you will need to set verify_cleanup = True.

The value of fast_cleanup can also be set using PythonOption mod_python.file_session.enable_fast_cleanup.
verify_cleanup

Boolean value used to optimize the FileSession cleanup process. Default is True.

If verify_cleanup is True, the session file which is being considered for deletion will be unpickled and its timeout value will be used to decide if the file should be deleted.

When verify_cleanup is False, the timeout value for the current session will be used in to determine if the session has expired. In this case, the session data will not be read from disk, which can lead to a substantial performance improvement when there are a large number of session files, or where each session is saving a large amount of data. However this may result in valid sessions being deleted if all the sessions are not using a the same timeout value.

The value of verify_cleanup can also be set using PythonOption mod_python.file_session.verify_session_timeout.
PythonOption mod_python.file_session.cleanup_time_limit [value]
Integer value in seconds. Default is 2 seconds.

Session cleanup could potentially take a long time and be both cpu and disk intensive, depending on the number of session files and if each file needs to be read to verify the timeout value. To avoid overloading the server, each time filesession_cleanup is called it will run for a maximum of session_cleanup_time_limit seconds. Each cleanup call will resume from where the previous call left off so all session files will eventually be checked.

Setting session_cleanup_time_limit to 0 will disable this feature and filesession_cleanup will run to completion each time it is called.
PythonOption mod_python.file_session.cleanup_grace_period [value] Integer value in seconds. Default is 240 seconds. This value is added to the session timeout in determining if a session file should be deleted.

There is a small chance that a the cleanup for a given session file may occur at the exact time that the session is being accessed by another request. It is possible under certain circumstances for that session file to be saved in the other request only to be immediately deleted by the cleanup. To avoid this race condition, a session is allowed a grace_period before it is considered for deletion by the cleanup. As long as the grace_period is longer that the time it takes to complete the request (which should normally be less than 1 second), the session will not be mistakenly deleted by the cleanup.

The default value should be sufficient for most applications.

class Session.MemorySession(req[, sid[, secret[, timeout[, lock]]]])¶

This class provides session storage using a global dictionary. This class provides by far the best performance, but cannot be used in a multi-process configuration, and also consumes memory for every active session. It also cannot be used where multiple Python interpreters are used within the one Apache process and it is necessary to share sessions between applications running in the distinct interpreters.

Note that using this class directly is not cross-platform. For best compatibility across platforms, always use the Session() function to create sessions.

Examples¶

The following example demonstrates a simple hit counter.:

from mod_python import Session

def handler(req):
    session = Session.Session(req)

    try:
        session['hits'] += 1
    except:
        session['hits'] = 1

    session.save()

    req.content_type = 'text/plain'
    req.write('Hits: %d\n' % session['hits'])
    return apache.OK

`psp` – Python Server Pager¶

The psp module provides a way to convert text documents (including, but not limited to HTML documents) containing Python code embedded in special brackets into pure Python code suitable for execution within a mod_python handler, thereby providing a versatile mechanism for delivering dynamic content in a style similar to ASP, JSP and others.

The parser used by psp is written in C (generated using flex) and is therefore very fast.

See PSP Handler for additional PSP information.

Inside the document, Python code needs to be surrounded by '<%' and '%>'. Python expressions are enclosed in '<%=' and '%>'. A directive can be enclosed in '<%@' and '%>'. A comment (which will never be part of the resulting code) can be enclosed in '<%--' and '--%>'

Here is a primitive PSP page that demonstrated use of both code and expression embedded in an HTML document:

<html>
<%
import time
%>
Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%>
</html>

Internally, the PSP parser would translate the above page into the following Python code:

req.write("""<html>
""")
import time
req.write("""
Hello world, the time is: """); req.write(str(time.strftime("%Y-%m-%d, %H:%M:%S"))); req.write("""
</html>
""")

This code, when executed inside a handler would result in a page displaying words 'Hello world, the time is: ' followed by current time.

Python code can be used to output parts of the page conditionally or in loops. Blocks are denoted from within Python code by indentation. The last indentation in Python code (even if it is a comment) will persist through the document until either end of document or more Python code.

Here is an example:

<html>
<%
for n in range(3):
    # This indent will persist
%>
<p>This paragraph will be
repeated 3 times.</p>
<%
# This line will cause the block to end
%>
This line will only be shown once.<br>
</html>

The above will be internally translated to the following Python code:

req.write("""<html>
""")
for n in range(3):
    # This indent will persist
    req.write("""
<p>This paragraph will be
repeated 3 times.</p>
""")
# This line will cause the block to end
req.write("""
This line will only be shown once.<br>
</html>
""")

The parser is also smart enough to figure out the indent if the last line of Python ends with ':' (colon). Considering this, and that the indent is reset when a newline is encountered inside '<% %>', the above page can be written as:

<html>
<%
for n in range(3):
%>
<p>This paragraph will be
repeated 3 times.</p>
<%
%>
This line will only be shown once.<br>
</html>

However, the above code can be confusing, thus having descriptive comments denoting blocks is highly recommended as a good practice.

The only directive supported at this time is include, here is how it can be used:

<%@ include file="/file/to/include"%>

If the parse() function was called with the dir argument, then the file can be specified as a relative path, otherwise it has to be absolute:

.. class:: PSP(req[, filename[, string[, vars]]])

This class represents a PSP object.

req is a request object; filename and string are optional keyword arguments which indicate the source of the PSP code. Only one of these can be specified. If neither is specified, req.filename is used as filename.

vars is a dictionary of global variables. Vars passed in the run() method will override vars passed in here.

This class is used internally by the PSP handler, but can also be used as a general purpose templating tool.

When a file is used as the source, the code object resulting from the specified file is stored in a memory cache keyed on file name and file modification time. The cache is global to the Python interpreter. Therefore, unless the file modification time changes, the file is parsed and resulting code is compiled only once per interpreter.

The cache is limited to 512 pages, which depending on the size of the pages could potentially occupy a significant amount of memory. If memory is of concern, then you can switch to dbm file caching. Our simple tests showed only 20% slower performance using bsd db. You will need to check which implementation anydbm defaults to on your system as some dbm libraries impose a limit on the size of the entry making them unsuitable. Dbm caching can be enabled via mod_python.psp.cache_database_filename Python option, e.g.:
PythonOption mod_python.psp.cache_database_filename "/tmp/pspcache.dbm"
Note that the dbm cache file is not deleted when the server restarts.

Unlike with files, the code objects resulting from a string are cached in memory only. There is no option to cache in a dbm file at this time.

Note that the above name for the option setting was only changed to this value in mod_python 3.3. If you need to retain backward compatibility with older versions of mod_python use the PSPDbmCache option instead.

PSP.run([vars[, flush]])¶

This method will execute the code (produced at object initialization time by parsing and compiling the PSP source). Optional argument vars is a dictionary keyed by strings that will be passed in as global variables. Optional argument flush is a boolean flag indicating whether output should be flushed. The default is not to flush output.

Additionally, the PSP code will be given global variables req, psp, session and form. A session will be created and assigned to session variable only if session is referenced in the code (the PSP handler examines co_names of the code object to make that determination). Remember that a mere mention of session will generate cookies and turn on session locking, which may or may not be what you want. Similarly, a mod_python FieldStorage object will be instantiated if form is referenced in the code.

The object passed in psp is an instance of PSPInterface.
PSP.display_code()¶
Returns an HTML-formatted string representing a side-by-side listing of the original PSP code and resulting Python code produced by the PSP parser.

Here is an example of how PSP can be used as a templating mechanism:

The template file:
<html>
  
  <h1>Hello, <%=what%>!</h1>
</html>
The handler code:
from mod_python import apache, psp

def handler(req):
    template = psp.PSP(req, filename='template.html')
    template.run({'what':'world'})
    return apache.OK

class psp.PSPInterface¶

An object of this class is passed as a global variable psp to the PSP code. Objects of this class are instantiated internally and the interface to __init__() is purposely undocumented.

set_error_page(filename)¶: Used to set a psp page to be processed when an exception occurs. If the path is absolute, it will be appended to document root, otherwise the file is assumed to exist in the same directory as the current page. The error page will receive one additional variable, exception, which is a 3-tuple returned by sys.exc_info().

apply_data(object[, **kw])¶: This method will call the callable object object, passing form data as keyword arguments, and return the result.

redirect(location[, permanent=0])¶

This method will redirect the browser to location location. If permanent is true, then MOVED_PERMANENTLY will be sent (as opposed to MOVED_TEMPORARILY).

Note

Redirection can only happen before any data is sent to the client, therefore the Python code block calling this method must be at the very beginning of the page. Otherwise an IOError exception will be raised.

Example:

<%

# note that the '<' above is the first byte of the page!
psp.redirect('http://www.modpython.org')
%>

Additionally, the psp module provides the following low level functions:

psp.parse(filename[, dir])¶

This function will open file named filename, read and parse its content and return a string of resulting Python code.

If dir is specified, then the ultimate filename to be parsed is constructed by concatenating dir and filename, and the argument to include directive can be specified as a relative path. (Note that this is a simple concatenation, no path separator will be inserted if dir does not end with one).

psp.parsestring(string)¶: This function will parse contents of string and return a string of resulting Python code.

`httpdconf` – HTTPd Configuration¶

The httpdconf module provides a simple framework for generating Apache HTTP Server configuration in Python. It was inspired by HTMLgen by Robin Friedrich. httpdconf appeared in 2002 as part of the mod_python test framework and its use has been primarily limited to mod_python tests. This latest version of mod_python includes many improvements to httpdconf and makes it part of the Python API.

The basic idea is that an Apache configuration directive can be specified as Python code, e.g.:

>>> from mod_python.httpdconf import *
>>> conf = DocumentRoot('/path/to/htdocs')

The resulting object renders itself as a valid Apache directive when converted to string:

>>> print conf
DocumentRoot /path/to/htdocs

While the __repr__ method of the object returns the string of Python code used to construct it in the first place:

>>> print `conf`
DocumentRoot('/path/to/htdocs')

Classes for Directive types¶

httpdconf separates all Apache directives into the following classes.

class httpdconf.Directive(name, value[, flipslash=1])¶: This is a simple directive. Its syntax is the directive name followed by a string value. Even though the Apache directives can be followed by multiple arguments, httpdconf views it as just a single string, e.g. CustomLog('logs/access_log combined').

class httpdconf.Container(*args[, only_if=None])¶

A Container groups directives specified as args into a single object. args can include other containers as well. The optional only_if argument is a string of Python that is evaled at directive render time. The directive is rendered only if the eval return a true value.

>>> c = Container(CustomLog('logs/access_log combined'), ErrorLog('logs/error_log'))
>>> print c
CustomLog logs/access_log combined
ErrorLog logs/error_log

>>> print `c`
Container(
    CustomLog('logs/access_log combined'),
    ErrorLog('logs/error_log'),
    only_if='True')
)

Note how elements within a Container are properly indented when rendered as Python code. A more practical example of only_if may be only_if="mod_python.version.HTTPD_VERSION[0:3] == '2.4'".

append(value)¶: Appends an object to a container. There is no difference between specifying contained object at creation time or appending elements to a container later.

ContainerTag(tag, attr, args[, flipslash=1)]: A ContainerTag is a tag that contains other tags, e.g. Directory or Location.

class httpdconf.Comment(comment)¶

A Comment renders itself as an Apache configuration comment. There is no need to include # as part of the comment string. Multi-line comments can be specified by a newline charater. Example:

>>> c = Comment("\nThis is\na comment\n")
>>> print c
#
# This is
# a comment

>>> print `c`
Comment('\n'
        'This is\n'
        'a comment\n')

httpdconf includes a basic set of Apache configuration directives (see code for which ones), but any Apache configuration directive can be trivially created by sub-classing one of the above classes:

>>> from mod_python.httpdconf import *
>>> class MyDirective(Directive):
...    def __init__(self, val):
...       Directive.__init__(self, self.__class__.__name__, val)
...
>>> c = MyDirective('foo')
>>> print c
MyDirective foo

Python API¶

Multiple Interpreters¶

Overview of a Request Handler¶

Overview of a Filter Handler¶

Overview of a Connection Handler¶

`apache` – Access to Apache Internals.¶

Functions¶

Attributes¶

Table Object (mp_table)¶

Request Object¶

Request Methods¶

Request Members¶

Connection Object (mp_conn)¶

Connection Methods¶

Connection Members¶

Filter Object (mp_filter)¶

Filter Methods¶

Filter Members¶

Server Object (mp_server)¶

Server Methods¶

Server Members¶

`util` – Miscellaneous Utilities¶

FieldStorage class¶

`FieldStorage` methods¶

FieldStorage Examples¶

Simple file control using class constructor¶

Advanced file control using object factory¶

Field class¶

Other functions¶

`Session` – Session Management¶

Classes¶

Examples¶

`psp` – Python Server Pager¶

`httpdconf` – HTTPd Configuration¶

Classes for Directive types¶

Table of Contents

Previous topic

Next topic

This Page

Python API¶

Multiple Interpreters¶

Overview of a Request Handler¶

Overview of a Filter Handler¶

Overview of a Connection Handler¶

apache – Access to Apache Internals.¶

Functions¶

Attributes¶

Table Object (mp_table)¶

Request Object¶

Request Methods¶

Request Members¶

Connection Object (mp_conn)¶

Connection Methods¶

Connection Members¶

Filter Object (mp_filter)¶

Filter Methods¶

Filter Members¶

Server Object (mp_server)¶

Server Methods¶

Server Members¶

util – Miscellaneous Utilities¶

FieldStorage class¶

FieldStorage methods¶

FieldStorage Examples¶

Simple file control using class constructor¶

Advanced file control using object factory¶

Field class¶

Other functions¶

Cookie – HTTP State Management¶

Classes¶

Functions¶

Examples¶

Session – Session Management¶

Classes¶

Examples¶

psp – Python Server Pager¶

httpdconf – HTTPd Configuration¶

Classes for Directive types¶

`apache` – Access to Apache Internals.¶

`util` – Miscellaneous Utilities¶

`FieldStorage` methods¶

`Cookie` – HTTP State Management¶

`Session` – Session Management¶

`psp` – Python Server Pager¶

`httpdconf` – HTTPd Configuration¶