4.5.4.1 Request Methods

###
4.5.4.1 Request Methods

`add_common_vars`( | )

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

`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, or the callable object itself. Optional dir is a string containing the name of the directory to be added to the module search path when looking for the handler. If no directory is specified, then the directory to search in is inherited from the handler which is making the registration,

  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.

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

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

`allow_methods`( | methods[, reset])

  Adds methods to the `req.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.

`auth_name`( | )

  Returns AuthName setting.

`auth_type`( | )

  Returns AuthType setting.

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

`discard_request_body`( | )

  Tests for and reads any message body in the request, simply discarding whatever it receives.

`document_root`( | )

  Returns DocumentRoot setting.

`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 mod_python configuration in effect for this request except for `Python*Handler` and `PythonOption` (The latter can be obtained via `req.get_options()`. The table has directives as keys, and their values, if any, as values.

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

`get_options`( | )

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

`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, `req.prev` will contain a reference to a request object from which it was redirected.

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

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

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

`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

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

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

`readline`( | [len])

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

`readlines`( | [sizehint])

  Reads all lines using `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.

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

`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 or the callable object itself. Optional dir is a string containing the name of the directory to be added to the module search when looking for the module.

  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 `req.add_input_filter()` would be used.

`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 or the callable object itself. Optional dir is a string containing the name of the directory to be added to the module search path when looking for the handler.

  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 `req.add_output_filter()` would be used.

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

`set_etag`( | )

  Sets the outgoing "`ETag`" header.

`set_last_modified`( | )

  Sets the outgoing "`Last-Modified`" header based on value of `mtime` attribute.

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

`update_mtime`( | dependency_mtime)

  If dependency_mtime is later than the value in the `mtime` attribute, sets the attribute to the new value.

`write`( | string[, flush=1])

  Writes string directly to the client, then flushes the buffer, unless flush is 0.

`flush`( | )

  Flushes the output buffer.

`set_content_length`( | len)

  Sets the value of `req.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 `req.write()`), calling the method is meaningless.