Configuring Ophelia¶
Configuration files¶
Ophelia comes with a number of clients that all exercise its request handler, but have different configuration mechanisms. The wsgiref-based HTTP server and the ophelia-dump script read their configuration from a section of an INI-style configuration file while the mod_python handler gets the same information from PythonOption variables set in the Apache configuration. Example configurations can be found below.
Two variables must always be present:
| template_root: | The file system path to the template root directory. |
|---|---|
| site: | The absolute URI of the Ophelia site’s root, i.e. that part of a page’s URI that is the same for all pages served from the template directory. |
In addition, the variables described below may be specified in order to influence the request handler’s behaviour. All of them have sensible default values. They will end up in the environment namespace stored on the request object, along with any other variables that are not recognized by Ophelia. This allows configuring Python modules and scripts that belong to your site’s content.
While the above pertains to all three clients, the wsgiref server needs additional information:
| host: | The network interface to bind to. |
|---|---|
| port: | The TCP port to listen at on that interface. |
For boolean variables such as redirect_index, the values “on”, “true”, or “yes” (case-insensitive) are taken to mean True, anything else means False.
URL canonicalization and redirection¶
If a requested URL points to a directory, Ophelia will try to find a template with a special file name and build the “index” page from that. There are two configuration options concerned with the index template:
| index_name: | The name of the index template Ophelia looks for. It defaults to “index.html”. |
|---|---|
| redirect_index: | Whether to canonicalize the URL and redirect the browser if the path portion of the URL ends with the default index page’s name. This option is turned off by default. |
Character encoding¶
Input encoding¶
By default, Ophelia expects Python scripts and TAL templates it reads from input files to be in 7-bit ASCII encoding. There are several ways to override this default.
You can declare a character encoding both for the Python script and the template, and the two encodings may differ. To specify the Python encoding, just start the script with a Python style encoding declaration like this:
# -*- coding: utf-8 -*-
The template’s encoding is determined by looking at the “<?xml?>” tag:
<?xml coding="utf-8" ?>
specifies UTF-8 encoding for the template. The tag itself will be stripped from the template and will not appear in the rendered page.
You may also specify a default encoding for any scripts and templates to be read later during traversal. In a Python script, just do something like
__request__.splitter.script_encoding = "utf-8"
__request__.splitter.template_encoding = "utf-8"
A site-wide default can be set through options:
| script_encoding: | |
|---|---|
| Encoding of Python scripts found in input files, defaults to “ascii”. | |
| template_encoding: | |
| Encoding of TAL templates found in input files, defaults to “ascii”. | |
Response encoding¶
Ophelia uses unicode internally, but an HTTP response consists of one-byte characters, so some encoding has to be applied in the end. This encoding is automatically declared in the page’s XML declaration as well as the response headers. By default, Ophelia encodes responses using UTF-8.
To set the response encoding to, say, latin-1 for a particular resource, do
__request__.response_encoding = "latin-1"
in a script. To affect the response encoding site-wide, set an option:
| response_encoding: | |
|---|---|
| Encoding of the HTTP response body, default to “utf-8”. | |
Processing of the result¶
By default, the page body is encoded with the response encoding and prefixed with an XML declaration before being returned by Request.build(). This can be prevented by an option if the returned value is going to be processed further instead of being sent directly to the client:
| immediate_result: | |
|---|---|
| Whether to use the unprocessed result of template evaluation as the response content. | |
Example configuration for an Apache/mod_python installation¶
Assume that the root of your site is published at <http://www.example.com/foo/bar/>.
Assume further that your site uses the following file system locations on a Unix system:
| /var/example/templates/: | |
|---|---|
| for the tree of Ophelia templates | |
| /var/example/python/: | |
| for the Python packages | |
| /var/example/static/: | |
| for the static stuff | |
To publish this site, add the following to your host’s config:
Alias /foo/bar /var/example/static
<Location "/foo/bar">
PythonInterpreter main_interpreter
PythonPath "['/var/example/python'] + sys.path"
PythonOption template_root /var/example/templates
PythonOption site http://www.example.com/foo/bar/
PythonFixupHandler ophelia.modpython
</Location>
This instructs Apache to let Ophelia handle any URI under /foo/bar/. Ophelia will build pages from templates where they exist, and Apache will serve files from your static content otherwise.
It is possible to set the Ophelia handler only for directories or HTML documents by applying some path name heuristics and matching the location against a regular expression.
Due to an interaction between Python’s restricted mode and how mod_python creates multiple Python interpreters, Ophelia must run in mod_python’s main Python interpreter. This means that if more than one Ophelia site is hosted by the same Apache process, they cannot be isolated from each other.
Example configuration for the included WSGI server¶
Create a configuration file, say, opheliasite.cfg:
[DEFAULT]
host = 127.0.0.1
port = 8080
template_root = /var/example/opheliasite
site = http://localhost:8080/
and run the ophelia-wsgiref script on that file:
ophelia-wsgiref -c opheliasite.cfg
You may want to wrap this call in a run-control script.
The same configuration can be used with the ophelia-dump script, except that it doesn’t require the host and port to be set.
