4.3.2.1 Request Methods
Keywords: modpython

###
4.3.2.1 Request Methods

`add_handler`(htype, handler[, dir])

  Allows dynamic handler registration. htype is a string containing the name of any of the apache `Python*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.

  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: There is no checking being done on the validity of the handler name. If you pass this function an invalid handler it will simply be ignored.

`add_common_vars`()
  Calls the Apache `ap_add_common_vars()` function. After a call to this method, `Request.subprocess_env` will contain a lot of CGI information.

`child_terminate`()
  Terminate a child process. This should terminate the current child process in a nice fashion.

  This method does nothing in multithreaded environments (e.g. Windows).

`get_basic_auth_pw`()
  Returns a string containing the password when Basic authentication is used.

`get_config`()
  Returns a reference to the table object containing the configuration in effect for this request. The table has directives as keys, and their values, if any, as values.

`get_dirs`()
  Returns a reference to the table object keyed by directives currently in effect and having directory names of where the particular directive was last encountered as values. For every key in the table returned by `get_config()`, there will be a key in this table. If the directive was in one of the server config files outside of any `<Directory>`, then the value will be an empty string.

`get_remote_host`(type)

  Returns the a string with the remote client's DNS name or IP or `None` on failure. 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. Fail 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.

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

`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 ommitted, 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. Absense 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.

`readline`([len])
  Like `read()` but reads until end of line.

  Note that in accordance with the HTTP specification, most clients will be terminating lines with "\r\n" rather than simply "\n".

`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.

`send_http_header`()
  Starts the output from the request by sending the HTTP headers. This function has no effect when called more than once within the same request. Any manipulation of `Request.headers_out` after this function has been called is pointless since the headers have already been sent to the client.

`write`(string)
  Writes string directly to the client, then flushes the buffer.