.. _pythonapi: ********** Python API ********** .. _pyapi-interps: 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 :dfn:`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. .. index:: single: main_interpreter 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. :ref:`dir-other-ipd` and :ref:`dir-other-ipdv` 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. :ref:`dir-other-pi` 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 :attr:`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*. .. seealso:: ``_ Python C Language API ``_ PEP 0311 - Simplified Global Interpreter Lock Acquisition for Extensions .. _pyapi-handler: Overview of a Request Handler ============================= .. index:: pair: request; handler A :dfn:`handler` is a function that processes a particular phase of a request. Apache processes requests in phases - read the request, process headers, provide content, etc. For every phase, it will call handlers, provided by either the Apache core or one of its modules, such as mod_python which passes control to functions provided by the user and written in Python. A handler written in Python is not any different from a handler written in C, and follows these rules: .. index:: single: req pair: request; object A handler function will always be passed a reference to a request object. (Throughout this manual, the request object is often referred to by the ``req`` variable.) Every handler can return: * :const:`apache.OK`, meaning this phase of the request was handled by this handler and no errors occurred. * :const:`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. * :const:`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_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 :const:`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 :meth:`request.write()` method. Client data, such as POST requests, can be read by using the :meth:`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 .. _pyapi-filter: Overview of a Filter Handler ============================ .. index:: pair: filter; handler A :dfn:`filter handler` is a function that can alter the input or the output of the server. There are two kinds of filters - :dfn:`input` and :dfn:`output` that apply to input from the client and output to the client respectively. At this time mod_python supports only request-level filters, meaning that only the body of HTTP request or response can be filtered. Apache provides support for connection-level filters, which will be supported in the future. A filter handler receives a *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 :meth:`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 :file:`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 :attr:`request.main` value. For more information on filters, see ``_. .. _pyapi-conn: Overview of a Connection Handler ================================ .. index:: pair: connection; handler A :dfn:`connection handler` handles the connection, starting almost immediately from the point the TCP connection to the server was made. Unlike HTTP handlers, connection handlers receive a *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 :file:`echo.py` file:: from mod_python import apache def connectionhandler(conn): while 1: conn.write(conn.readline()) return apache.OK :mod:`apache` -- Access to Apache Internals. =============================================== .. module:: apache :synopsis: Access to Apache Internals. .. moduleauthor:: Gregory Trubetskoy grisha@modpython.org The Python interface to Apache internals is contained in a module appropriately named :mod:`apache`, located inside the :mod:`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.) .. index:: pair: _apache; module The :mod:`apache` module can only be imported by a script running under mod_python. This is because it depends on a built-in module :mod:`_apache` provided by mod_python. It is best imported like this:: from mod_python import apache :mod:`mod_python.apache` module defines the following functions and objects. For a more in-depth look at Apache internals, see the `Apache Developer Page `_ .. _pyapi-apmeth: Functions --------- .. function:: 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 :meth:`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 :meth:`request.log_error` instead, it will prepend request-specific information such as the source IP of the request to the log entry. .. function:: 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) .. function:: allow_methods([*args]) A convenience function to set values in :meth:`request.allowed`. :meth:`request.allowed` is a bitmask that is used to construct the ``'Allow:'`` header. It should be set before returning a :const:`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 .. function:: 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')``. .. function:: 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 :attr:`request.finfo` attribute. .. function:: register_cleanup(callable[, data]) Registers a cleanup that will be performed at child shutdown time. Equivalent to :func:`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. .. function:: 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. .. function:: server_root() Returns the value of ServerRoot. .. function:: make_table() This function is obsolete and is an alias to :class:`table` (see below). .. function:: 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 .. _pyapi-apmem: Attributes ---------- .. attribute:: interpreter String. The name of the subinterpreter under which we're running. *(Read-Only)* .. attribute:: main_server A ``server`` object for the main server. *(Read-Only)* .. attribute:: MODULE_MAGIC_NUMBER_MAJOR Integer. An internal to Apache version number useful to determine whether certain features should be available. See :attr:`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)* .. attribute:: MODULE_MAGIC_NUMBER_MINOR Integer. An internal to Apache version number useful to determine whether certain features should be available. See :attr:`MODULE_MAGIC_NUMBER_MAJOR`. Minor API changes that do not cause binary compatibility problems. *(Read-Only)* .. _pyapi-mptable: Table Object (mp_table) ----------------------- .. index:: singe: table .. class:: table([mapping-or-sequence]) Returns a new empty object of type ``mp_table``. See Section :ref:`pyapi-mptable` 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 :meth:`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, :meth:`request.headers_in` and :meth:`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: .. method:: add(key, val) Allows for creating duplicate keys, which is useful when multiple headers, such as `Set-Cookie:` are required. .. _pyapi-mprequest: Request Object -------------- .. index:: single: req single: request single: request_rec 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. .. _pyapi-mprequest-meth: Request Methods ^^^^^^^^^^^^^^^ .. method:: 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. .. method:: request.add_common_vars() Use of this method is discouraged, use :meth:`request.add_cgi_vars()` instead. Calls the Apache ``ap_add_common_vars()`` function. After a call to this method, :attr:`request.subprocess_env` will contain *some* CGI information. .. method:: 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. .. method:: 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. .. method:: 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) .. method:: request.allow_methods(methods[, reset]) Adds methods to the :meth:`request.allowed_methods` list. This list will be passed in `Allowed:` header if :const:`HTTP_METHOD_NOT_ALLOWED` or :const:`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. .. method:: request.auth_name() Returns AuthName setting. .. method:: request.auth_type() Returns AuthType setting. .. method:: 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'``. .. method:: request.discard_request_body() Tests for and reads any message body in the request, simply discarding whatever it receives. .. method:: request.document_root() Returns DocumentRoot setting. .. method:: request.get_basic_auth_pw() Returns a string containing the password when Basic authentication is used. .. method:: 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 :meth:`request.get_options()`. The table has directives as keys, and their values, if any, as values. .. method:: 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: * :const:`apache.REMOTE_HOST` Look up the DNS name. Return None if Apache directive ``HostNameLookups`` is ``Off`` or the hostname cannot be determined. * :const:`apache.REMOTE_NAME` *(Default)* Return the DNS name if possible, or the IP (as a string in dotted decimal notation) otherwise. * :const:`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. * :const:`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. .. method:: request.get_options() Returns a reference to the table object containing the options set by the ``PythonOption`` directives. .. method:: 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, :meth:`request.prev` will contain a reference to a request object from which it was redirected. .. method:: 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 :attr:`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. .. method:: 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 :func:`apache.log_error` function. .. method:: request.meets_conditions() Calls the Apache ``ap_meets_conditions()`` function which returns a status code. If *status* is :const:`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 :meth:`request.status` if the status differs from :const:`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 ... .. method:: 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 :meth:`request.requires()` would return ``('user joe', 'valid-user')``. .. method:: 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 :exc:`IOError` raised if the :exc:`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. .. method:: request.readline([len]) Like :meth:`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'``. .. method:: request.readlines([sizehint]) Reads all lines using :meth:`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. .. method:: 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. .. method:: 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. .. method:: 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 :meth:`request.add_output_filter()` would be used. .. method:: 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. .. method:: request.set_etag() Sets the outgoing ``'ETag'`` header. .. method:: request.set_last_modified() Sets the outgoing ``Last-Modified`` header based on value of ``mtime`` attribute. .. method:: 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 :attr:`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. .. method:: request.update_mtime(dependency_mtime) If *ependency_mtime* is later than the value in the ``mtime`` attribute, sets the attribute to the new value. .. method:: request.write(string[, flush=1]) Writes *string* directly to the client, then flushes the buffer, unless flush is 0. .. method:: request.flush() Flushes the output buffer. .. method:: request.set_content_length(len) Sets the value of :attr:`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 :meth:`request.write`), calling the method is meaningless. .. _pyapi-mprequest-mem: Request Members ^^^^^^^^^^^^^^^ .. attribute:: request.connection A ``connection`` object associated with this request. See :ref:`pyapi-mpconn` Object for more details. *(Read-Only)* .. attribute:: request.server A server object associated with this request. See :ref:`pyapi-mpserver` for more details. *(Read-Only)* .. attribute:: request.next If this is an internal redirect, the request object we redirect to. *(Read-Only)* .. attribute:: request.prev If this is an internal redirect, the request object we redirect from. *(Read-Only)* .. attribute:: request.main If this is a sub-request, pointer to the main request. *(Read-Only)* .. attribute:: request.the_request String containing the first line of the request. *(Read-Only)* .. attribute:: 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. .. attribute:: request.proxyreq A proxy request: one of :const:`apache.PROXYREQ_*` values. .. attribute:: request.header_only A boolean value indicating HEAD request, as opposed to GET. *(Read-Only)* .. attribute:: request.protocol Protocol, as given by the client, or ``'HTTP/0.9'``. Same as CGI :envvar:`SERVER_PROTOCOL`. *(Read-Only)* .. attribute:: request.proto_num Integer. Number version of protocol; 1.1 = 1001 *(Read-Only)* .. attribute:: request.hostname String. Host, as set by full URI or Host: header. *(Read-Only)* .. attribute:: request.request_time A long integer. When request started. *(Read-Only)* .. attribute:: request.status_line Status line. E.g. ``'200 OK'``. *(Read-Only)* .. attribute:: request.status Status. One of :const:`apache.HTTP_*` values. .. attribute:: request.method A string containing the method - ``'GET'``, ``'HEAD'``, ``'POST'``, etc. Same as CGI :envvar:`REQUEST_METHOD`. *(Read-Only)* .. attribute:: request.method_number Integer containing the method number. *(Read-Only)* .. attribute:: request.allowed Integer. A bitvector of the allowed methods. Used to construct the Allowed: header when responding with :const:`HTTP_METHOD_NOT_ALLOWED` or :const:`HTTP_NOT_IMPLEMENTED`. This field is for Apache's internal use, to set the ``Allowed:`` methods use :meth:`request.allow_methods` method, described in section :ref:`pyapi-mprequest-meth`. *(Read-Only)* .. attribute:: request.allowed_xmethods Tuple. Allowed extension methods. *(Read-Only)* .. attribute:: request.allowed_methods Tuple. List of allowed methods. Used in relation with :const:`METHOD_NOT_ALLOWED`. This member can be modified via :meth:`request.allow_methods` described in section :ref:`pyapi-mprequest-meth`. *(Read-Only)* .. attribute:: request.sent_bodyct Integer. Byte count in stream is for body. (?) *(Read-Only)* .. attribute:: request.bytes_sent Long integer. Number of bytes sent. *(Read-Only)* .. attribute:: request.mtime Long integer. Time the resource was last modified. *(Read-Only)* .. attribute:: request.chunked Boolean value indicating when sending chunked transfer-coding. *(Read-Only)* .. attribute:: request.range String. The ``Range:`` header. *(Read-Only)* .. attribute:: request.clength Long integer. The "real" content length. *(Read-Only)* .. attribute:: request.remaining Long integer. Bytes left to read. (Only makes sense inside a read operation.) *(Read-Only)* .. attribute:: request.read_length Long integer. Number of bytes read. *(Read-Only)* .. attribute:: request.read_body Integer. How the request body should be read. *(Read-Only)* .. attribute:: request.read_chunked Boolean. Read chunked transfer coding. *(Read-Only)* .. attribute:: request.expecting_100 Boolean. Is client waiting for a 100 (:const:`HTTP_CONTINUE`) response. *(Read-Only)* .. attribute:: request.headers_in A :class:`table` object containing headers sent by the client. .. attribute:: request.headers_out A :class:`table` object representing the headers to be sent to the client. .. attribute:: request.err_headers_out These headers get send with the error response, instead of headers_out. .. attribute:: request.subprocess_env A :class:`table` object containing environment information typically usable for CGI. You may have to call :meth:`request.add_common_vars` and :meth:`request.add_cgi_vars` first to fill in the information you need. .. attribute:: request.notes A :class:`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 :attr:`request.notes`. .. attribute:: request.phase The phase currently being being processed, e.g. ``'PythonHandler'``. *(Read-Only)* .. attribute:: request.interpreter The name of the subinterpreter under which we're running. *(Read-Only)* .. attribute:: request.content_type String. The content type. Mod_python maintains an internal flag (:attr:`request._content_type_set`) to keep track of whether :attr:`request.content_type` was set manually from within Python. The publisher handler uses this flag in the following way: when :attr:`request.content_type` isn't explicitly set, it attempts to guess the content type by examining the first few bytes of the output. .. attribute:: request.content_languages Tuple. List of strings representing the content languages. .. attribute:: 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 :meth:`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 .. attribute:: request.content_encoding String. Content encoding. *(Read-Only)* .. attribute:: request.vlist_validator Integer. Variant list validator (if negotiated). *(Read-Only)* .. attribute:: request.user If an authentication check is made, this will hold the user name. Same as CGI :envvar:`REMOTE_USER`. .. note:: :meth:`request.get_basic_auth_pw` must be called prior to using this value. .. attribute:: request.ap_auth_type Authentication type. Same as CGI :envvar:`AUTH_TYPE`. .. attribute:: request.no_cache Boolean. This response cannot be cached. .. attribute:: request.no_local_copy Boolean. No local copy exists. .. attribute:: request.unparsed_uri The URI without any parsing performed. *(Read-Only)* .. attribute:: request.uri The path portion of the URI. .. attribute:: request.filename String. File name being requested. .. attribute:: request.canonical_filename String. The true filename (:attr:`request.filename` is canonicalized if they don't match). .. attribute:: request.path_info String. What follows after the file name, but is before query args, if anything. Same as CGI :envvar:`PATH_INFO`. .. attribute:: request.args String. Same as CGI :envvar:`QUERY_ARGS`. .. attribute:: 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 :func:`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 :const:`FINFO_*` constants that should be used to access elements of this tuple.:: user = req.finfo[apache.FINFO_USER] .. attribute:: request.parsed_uri Tuple. The URI broken down into pieces. ``(scheme, hostinfo, user, password, hostname, port, path, query, fragment)``. The :mod:`apache` module defines a set of :const:`URI_*` constants that should be used to access elements of this tuple. Example:: fname = req.parsed_uri[apache.URI_PATH] *(Read-Only)* .. attribute:: request.used_path_info Flag to accept or reject path_info on current request. .. attribute:: request.eos_sent Boolean. EOS bucket sent. *(Read-Only)* .. attribute:: 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 :attr:`connection.client_addr`. *(Read-Only)* .. attribute:: request.useragent_ip *Apache 2.4 only* String with the IP of the user agent. Same as CGI :envvar:`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 :attr:`connection.client_ip`. *(Read-Only)* .. _pyapi-mpconn: Connection Object (mp_conn) --------------------------- .. index:: singe: mp_conn The connection object is a Python mapping to the Apache :c:type:`conn_rec` structure. .. _pyapi-mpconn-meth: Connection Methods ^^^^^^^^^^^^^^^^^^ .. method:: 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. .. method:: 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. .. method:: connection.readline([length]) Reads a line from the connection or up to *length* bytes. This method should only be used inside *Connection Handlers*. .. method:: connection.write(string) Writes *string* to the client. This method should only be used inside *Connection Handlers*. .. _pyapi-mpconn-mem: Connection Members ^^^^^^^^^^^^^^^^^^ .. attribute:: connection.base_server A ``server`` object for the physical vhost that this connection came in through. *(Read-Only)* .. attribute:: connection.local_addr The (address, port) tuple for the server. *(Read-Only)* .. attribute:: 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)* .. attribute:: 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 :attr:`request.useragent_addr`. *(Read-Only)* .. attribute:: 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 :envvar:`REMOTE_ADDR`. *(Read-Only)* .. attribute:: 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 :attr:`request.useragent_ip`. *(Read-Only)* .. attribute:: 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 :envvar:`REMOTE_HOST`. *(Read-Only)* .. attribute:: connection.remote_logname Remote name if using :rfc:`1413` (ident). Same as CGI :envvar:`REMOTE_IDENT`. *(Read-Only)* .. attribute:: connection.aborted Boolean. True is the connection is aborted. *(Read-Only)* .. attribute:: connection.keepalive Integer. 1 means the connection will be kept for the next request, 0 means "undecided", -1 means "fatal error". *(Read-Only)* .. attribute:: 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)* .. attribute:: connection.keepalives The number of times this connection has been used. (?) *(Read-Only)* .. attribute:: connection.local_ip String with the IP of the server. *(Read-Only)* .. attribute:: connection.local_host DNS name of the server. *(Read-Only)* .. attribute:: connection.id Long. A unique connection id. *(Read-Only)* .. attribute:: connection.notes A :class:`table` object containing miscellaneous general purpose info that lives for as long as the connection lives. .. _pyapi-mpfilt: Filter Object (mp_filter) ------------------------- .. index:: singe: 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. .. _pyapi-mpfilt-meth: Filter Methods ^^^^^^^^^^^^^^ .. method:: filter.pass_on() Passes all data through the filter without any processing. .. method:: 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. .. method:: filter.readline([length]) Reads a line from the next filter or up to *length* bytes. .. method:: filter.write(string) Writes *string* to the next filter. .. method:: filte.flush() Flushes the output by sending a FLUSH bucket. .. method:: filter.close() Closes the filter and sends an EOS bucket. Any further IO operations on this filter will throw an exception. .. method:: 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. .. _pyapi-mpfilt-mem: Filter Members ^^^^^^^^^^^^^^ .. attribute:: filter.closed A boolean value indicating whether a filter is closed. *(Read-Only)* .. attribute:: filter.name String. The name under which this filter is registered. *(Read-Only)* .. attribute:: filter.req A reference to the request object. *(Read-Only)* .. attribute:: filter.is_input Boolean. True if this is an input filter. *(Read-Only)* .. attribute:: filter.handler String. The name of the Python handler for this filter as specified in the configuration. *(Read-Only)* .. _pyapi-mpserver: Server Object (mp_server) ^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: single: 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. .. _pyapi-mpsrv-meth: Server Methods ^^^^^^^^^^^^^^ .. method:: server.get_config() Similar to :meth:`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. .. method:: server.get_options() Similar to :meth:`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. .. method:: 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 :func:`apache.log_error` function. .. method:: server.register_cleanup(request, callable[, data]) Registers a cleanup. Very similar to :meth:`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 :func:`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. .. _pyapi-mpsrv-mem: Server Members ^^^^^^^^^^^^^^ .. attribute:: server.defn_name String. The name of the configuration file where the server definition was found. *(Read-Only)* .. attribute:: server.defn_line_number Integer. Line number in the config file where the server definition is found. *(Read-Only)* .. attribute:: server.server_admin Value of the ``ServerAdmin`` directive. *(Read-Only)* .. attribute:: server.server_hostname Value of the ``ServerName`` directive. Same as CGI :envvar:`SERVER_NAME`. *(Read-Only)* .. attribute:: 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)* .. attribute:: server.wild_names Tuple. List of wildcarded server names specified in the ``ServerAlias`` directive. *(Read-Only)* .. attribute:: server.port Integer. TCP/IP port number. Same as CGI :envvar:`SERVER_PORT`. *This member appears to be 0 on Apache 2.0, look at req.connection.local_addr instead* *(Read-Only)* .. attribute:: server.error_fname The name of the error log file for this server, if any. *(Read-Only)* .. attribute:: server.loglevel Integer. Logging level. *(Read-Only)* .. attribute:: server.is_virtual Boolean. True if this is a virtual server. *(Read-Only)* .. attribute:: server.timeout Integer. Value of the ``Timeout`` directive. *(Read-Only)* .. attribute:: server.keep_alive_timeout Integer. Keepalive timeout. *(Read-Only)* .. attribute:: server.keep_alive_max Maximum number of requests per keepalive. *(Read-Only)* .. attribute:: server.keep_alive Use persistent connections? *(Read-Only)* .. attribute:: server.path String. Path for ``ServerPath`` *(Read-Only)* .. attribute:: server.pathlen Integer. Path length. *(Read-Only)* .. attribute:: server.limit_req_line Integer. Limit on size of the HTTP request line. *(Read-Only)* .. attribute:: server.limit_req_fieldsize Integer. Limit on size of any request header field. *(Read-Only)* .. attribute:: server.limit_req_fields Integer. Limit on number of request header fields. *(Read-Only)* .. _pyapi-util: :mod:`util` -- Miscellaneous Utilities ====================================== .. module:: util :synopsis: Miscellaneous Utilities. .. moduleauthor:: Gregory Trubetskoy grisha@modpython.org The :mod:`util` module provides a number of utilities handy to a web application developer similar to those in the standard library :mod:`cgi` module. The implementations in the :mod:`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 .. seealso:: :rfc:`3875` for detailed information on the CGI specification .. _pyapi-util-fstor: FieldStorage class ------------------ Access to form data is provided via the :class:`FieldStorage` class. This class is similar to the standard library module ``cgi.FieldStorage`` .. class:: 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 :class:`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 :ref:`pyapi-util-fstor-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, :class:`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 :class:`FieldStorage` class instantiated per single request, nor should you make any attempts to read client data before or after instantiating a :class:`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 :class:`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 :class:`FieldStorage` class instance is created, the data read from the client is then parsed into separate fields and packaged in :class:`Field` objects, one per field. For HTML form inputs of type ``file``, a temporary file is created that can later be accessed via the :attr:`Field.file` attribute of a :class:`Field` object. The :class:`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 :class:`StringField`, containing the form input value. This is only when there is a single value corresponding to the input name. :class:`StringField` is a subclass of :class:`str` which provides the additional :attr:`StringField.value` attribute for compatibility with standard library :mod:`cgi` module. * An instance of a :class:`Field` class, if the input is a file upload. * A list of :class:`StringField` and/or :class:`Field` objects. This is when multiple values exist, such as for a ``