Ophelia API and predefined script and template variables

This file describes the context variables as seen by user code in Python scripts and page templates, as well as the ophelia.request and ophelia.util modules (which are the parts of the Ophelia core most likely to be used in user code) and how to use exceptions for redirecting to another URL and controlling traversal.

For the APIs of the request and input splitter objects, see their user interfaces specified in the ophelia.interfaces module: IRequestAPI and ISplitterAPI.

Script context

Scripts are successively run in a namespace freshly initialized by Ophelia with the following variables:

__file__:the absolute file system path of the input file __text__:the text of the current file’s template, as unicode __template__:the PageTemplate created from the input file’s template text __request__:the currently running Request instance

All of the above variables except for __request__ will be reset after each script is run. None of the above names should be assigned to. The template may be influenced by calling its methods; see the zope.pagetemplate documentation.

Additional context variables may be passed to the request when its traverse method (or the request itself) is called. They will be used to update the context namespace before the first script is run on it. When using the WSGI interface, a mapping that contains this additional context may be passed in the environ dictionary under the ophelia.context key.

Page template context

The context of a page template, i.e. the set of variables that can be accessed by TALES expressions, contains:

• variables from the ZPT engine

  • CONTEXTS
  • nothing
  • default
  • repeat
  • modules
  • loop

  For documentation, see <http://wiki.zope.org/ZPT/TAL>.

• variables added by Ophelia

  macros:

  namespace of compiled macros (see above), contains at this point all macros relevant to the requested path

  innerslot:

  unicode, the “magic” slot filled by evaluating the next more specific template. Example use:

  <div tal:content="structure innerslot">

  Making this slot magic avoids writing any boilerplate code at all in run-of-the-mill templates and pages.

• all variables in the script context (including those relating to the input file of the template at hand)

Script variables using the same name as a variable defined by ZPT or Ophelia will override that variable.

The ophelia.request module

To use the request or related functionality in a script or Python module:

import ophelia.request

The module defines the following items meant to be used in client code:

StopTraversal:

exception, see “controlling traversal” below

NotFound:

exception signalling that some file needed to respond to the request was not found

Redirect:

exception, see “redirection” below

Request:

an instance of this class represents the HTTP request and orchestrates the execution of scripts and assembly of the HTTP response.

Please see ophelia.interfaces.IRequestAPI and ophelia.interface.IRequestTraversal for a detailed description of the request API.

get_request:

function returning the currently running Request instance

get_file_context:  

function returning the namespace of file-related variables (__file__, __text__, __template__)

Redirection

Ophelia provides the request.Redirect exception that scripts and add-on libraries may raise to cause the HTTP server to redirect the client to another URI. The exception constructor takes a number of parameters:

uri:str, the URI to redirect to, defaults to the original request’s URI path:str, optional override value for uri’s path portion

Overriding part of the redirection target is possible purely for convenience. It saves the client some URI manipulation in the simpler use cases.

Controlling traversal

This is at the edge of Ophelia’s scope.

Raising request.StopTraversal in a script prevents more specific scripts from being executed and the current as well as more specific templates from being evaluated. The exception accepts one optional parameter:

text:unicode, template text to use instead of the input file’s text

Utilities

The ophelia.util module contains some utilities:

Namespace:

class whose instances do nothing but carry attributes

Not using pure dictionaries here makes for more aesthetic code if nothing else. Namespaces can still be accessed as dictionaries.

strftime:

like time.strftime, but handles unicode and takes into account the current locale’s character encoding.