ophelia.interfaces – Public interfaces used in Ophelia¶

Public interfaces used in Ophelia.

Interface: ophelia.interfaces.IRequestAPI

HTTP request API for use in scripts and TALES expressions.

Attribute: index_name

File name to access if a URI refers to a bare directory.

String, defaults to “index.html”.

Attribute: site

Absolute URI of the site root.

String, the URI which corresponds to an empty path.

Method: load_macros(name)

Process a file, only executing the script and loading the macros.

Only the macros defined by the template in the file are used; the template itself will be thrown away.

name: str, file name to process, relative to the current dir_path

Returns nothing.

Attribute: innerslot

Unicode content to put in the template’s inner slot.

None during traversal, assigned to after each template on the stack has been rendered, starting with the innermost one. Thus, this value can’t be directly used by scripts but may be used by functions placed in the context.

Method: render_template(name)

Process a file, rendering its template.

The script contained in the file given will be executed, the macros defined by the template will be loaded, and the template will be rendered in the TALES context as it is at the moment this method is called.

name: str, file name to process, relative to the current dir_path

Returns unicode, the rendered template contained in the file.

Attribute: content

Encoded HTTP response after the response body is complete.

None during traversal and template rendering. After that, consists of an XML declaration and the encoded current innerslot value.

Attribute: template_root

Absolute file system path to the templates’ root directory.

Method: insert_template(name)

Process a file, pushing the template onto the stack.

The script contained in the file given will be executed, the macros defined by the template will be loaded, and the template will be stacked on top of the one from the file whose script called this method.

name: str, file name to process, relative to the current dir_path

Returns nothing.

Attribute: current

URI traversed so far, starting with the site root URI.

String, ends with ‘/’ if a directory’s __init__ is currently being processed.

Attribute: macros

Namespace of compiled macros.

Attribute: tail

List of path segments yet to traverse.

List of strings, the last one being empty if the requested URI refers to a directory.

Attribute: env

Compound environment namespace.

• site configuration options (PythonOption setting if running mod_python,

application configuration if using WSGI) - the CGI or WSGI environment variables passed by the server - if running mod_python, the Apache request object as apache_request - must contain the wsgi.input variable - may contain the ophelia.response_headers namespace of response headers already set by the server environment

Attribute: input

File-like object from which to read the request body.

Attribute: response_headers

Mapping of header names to TALES expressions.

Expressions will be evaluated in the usual TALES context after all templates have been rendered.

Multiple values for the same header must be sent in a single header line with a comma-separated value, see RfC 2068, section 4.2.

If response headers have been set earlier by the server environment, they may be passed to the request through the environment to pre-fill the response_headers namespace.

Attribute: redirect_index

Whether to redirect requests for index pages to directory URIs.

Bool, defaults to False. A request for an index page is one that maps to a file named like the index_name.

Attribute: path

URI path portion to traverse from the site root.

String with path segments separated by ‘/’, doesn’t start with ‘/’ if the requested URI was canonical.

Attribute: stack

Stack of file contexts to process when rendering the response body.

List of namespaces holding the file path, template text, and page template for any input file processed so far (during traversal) or to be rendered yet (when building the response). The outermost template is at the bottom of the stack (i.e. at index 0).

Attribute: splitter

Splits input files into scripts and templates.

Implements ophelia.interfaces.ISplitter.

Attribute: headers

Namespace of request headers with leading HTTP_ removed.

Multiple headers are mapped to a comma-separated single header according to RfC 2068, section 4.2.

Attribute: context

Namespace for executing scripts and evaluating TALES expressions.

Attribute: dir_path

Absolute file system path to the current directory.

String. The current directory is the one which directly contains the file currently being processed.

Attribute: response_encoding

Name of the character encoding used for the HTTP response.

String, defaults to “utf-8”.

Interface: ophelia.interfaces.IRequestTraversal

Methods used in traversing from site root to requested resource.

Method: traverse_next()

Traverse the next path segment, possibly process an input file.

Returns nothing.

Raises NotFound if no matching file system resource could be found.

Method: tales_namespace(file_context={})

Constructs the namespace in which to evaluate a template.

file_context: namespace, predefined variables specific to input file

Returns the TALES namespace.

Method: traverse_dir()

Handle the current resource if it is a file system directory.

This method assumes that a file system directory corresponds directly to a resource with directory semantics and performs trailing slash canonicalization based on that assumption.

Returns nothing.

May raise Redirect due to URI canonicalization.

Method: traverse(**context)

Traverse the path, read input, and prepare the template context.

context: name-value pairs to initialize the context with

Returns nothing.

Raises RuntimeError if the template root is not a file system directory.

Attribute: immediate_result

Whether to return the result of template evaluation immediately.

Bool, defaults to False. By default, the page content is encoded and prefixed with an XML declaration. Setting this option to True prevents that processing step.

Method: traverse_file(file_path)

Handle a file system resource that is a file.

If the file’s Python script emitted a signal to stop traversal, this step removes any further path segments from the queue.

file_path: str, absolute file system path to the file.

Returns nothing.

Method: build_content()

Build the response body by rendering templates from the stack.

Returns nothing.

Method: get_next()

Get the next path segment from the tail sequence.

This step canonicalizes of “//”, “/./”, and “/../” path portions as well as paths specifying a directory index explicitly.

Returns str, the next path portion.

May raise Redirect due to URI canonicalization.

Method: build()

Build the complete response after the template context is prepared.

Returns (namespace of compiled response headers, unicode response body).

Method: build_headers()

Compile the response header TALES expressions.

Returns nothing.

Method: __call__(**context)

Process the request, return response headers and body.

context: name-value pairs to initialize the context with

Returns (dict, unicode), response headers and page content.

Method: process_file(file_path, insert=False)

Process an input file that may consist of script and template.

file_path: str, absolute file system path to the file.

Returns (file context namespace, StopTraversal or None).

Interface: ophelia.interfaces.ISplitterAPI

Input splitter API for use in scripts and TALES expressions.

Attribute: template_encoding

Name of the character encoding for reading TAL templates.

String, defaults to “ascii”.

Attribute: script_encoding

Name of the character encoding for reading Python scripts.

String, defaults to “ascii”.