PXTL

Python XML Templating Language
Implementation package ‘pxtl’ 1.5

Contents

Introduction

This package contains two implementations of PXTL: the interpreter-based reference implementation, transforming XML as DOM trees, and the compiler-based optimised implementation, for faster output of serialised XML in performance-critical applications such as web templating.

The pxtl package requires Python 1.5.2 or later, and has so far been tested up to Python 2.4.1c1. Python 1.6 or later is required for proper treatment of Unicode in XML.

For details of the PXTL language itself, please see the accompanying language documentation.

Installation

The ‘pxtl’ directory is a pure-Python package which can be dropped into any directory on the Python path.

To get it installed and pre-compiled in one go, open a command line (shell), cd into the directory containing setup.py, and enter:

python setup.py install

Installing this way requires Python 1.6 or later (or the distutils package to be otherwise installed). Windows users for whom ‘python.exe’ is not in the command path may have to give a full pathname to python, for example C:\Python23\python.exe setup.py install.

Usage

processFile

Use the function pxtl.processFile to load a PXTL document, run its code, and output the transformed file.

import os, pxtl
path= os.path.join(templateDir, 'hello.px')
pxtl.processFile(path)

Using pxtl.processFile means you only want the final output and don’t care which implementation is used. Normally this will be the optimised implementation. If you want to specify a particular implementation (for testing, for example) you can import the ‘reference’ and ‘optimised’ sub-modules and call pxtl.reference.processFile or pxtl.optimised.processFile.

Note: when the optimised implementation is in use, the current user must have write-access to the folder containing the template, so that a compiled Python bytecode file can be stored there (just like with standard Python .pyc files, but normally with the file extension .pxc instead of .pyc). See the bytecodebase argument for ways around this. If a bytecode file cannot be stored, the template will have to be recompiled every time processFile is called, which is extremely slow.

Whichever implementation you use, the arguments are the same. The first argument path is required and holds the pathname of the template to process. There are several further optional arguments:

writer: a stream-like object to which to send the results. If this is not given, standard output (sys.stdout) is used.

globals: a dictionary to be used as ‘global scope’ for Python code in the template. Any values in the dictionary can be accessed by template code as a variable with the same name as the dictionary item’s key; any globals written by template code will be stored in the directory and may be read by the caller after the template has run. If this argument is not given, a new, empty scope is created.

pxtl.processFile('~/pxtl/film.px', globals= {'stars': 4})
<px:for range="stars">
  <img src="/img/star.gif" alt="*"/>
</px:for>

debug: if set to a true value, any exceptions that occur in running template code will be caught, and a debugging HTML page output instead of raising an error. This option is highly recommended for developing web pages (because it is much more descriptive than a plain traceback or web server error page), but should not be used on production servers (as showing script source and variables to users might leak security-sensitive information; also there is a marginal speed penalty).

headers: if set to a true value, the output will be prefixed with an appropriate HTTP ‘Content-Type’ header for the document. This may save CGI script authors a little effort.

pxtl.processFile('/web/pxtl/page.px', debug= True, headers= True)

dom: a DOM implementation to use for XML work. This should normally be left unspecified, to use the embedded DOM implementation ‘pxdom’, which is the only suitable native-Python DOM Level 3 Core/LS implementation at the time of writing.

bytecodebase: allows the location of bytecode cache files (.pxc) generated by the optimised implementation to be changed. If given, should be a mapping of source path keys to destination path values. Given multiple keys, the one that is the nearest ancestor to the template file is chosen. If no key is an ancestor, the path is not changed and the bytecode is stored in the same directory as the template as usual.

from os.path import join
bcb= {
  join(APPROOT, 'templates'): join(APPROOT, 'bytecode'),
  join(APPROOT, 'templates', 'tmp'): TEMPDIR,
}
path= join(APPROOT, 'templates', 'info', 'index.px')
pxtl.processFile(path, bytecodebase= bcb)

(In the above example, bytecode would be stored as bytecode/info/index.pxc inside the APPROOT.)

Typically this feature is useful when you want to run PXTL in a restricted user environment such as CGI on a web server (which on Unix-like Operating Systems typically runs as the unprivileged user ‘nobody’), and you want to allow this user to save bytecode files without giving them access to the template folder. Another possibility in this case is to precompile the bytecode files at install-time (see pxtl.optimised.compileFile).

If the bytecodebase argument is set to None, the optimised implementation will make no attempt to store bytecode files, and the pxtl.processFile function will normally prefer to use the reference implementation.

Extended ‘reference’ features

Transformer

If you want pxtl to transform DOM trees directly, rather than dealing with the serialised XML documents, you should use the pxtl.reference.Transformer class.

import pxtl.reference
t= pxtl.reference.Transformer()
transformedDocument= t.transformDocument(document)

The object passed to transformDocument must implement the Document interface from the DOM Level 2 Core standard. If the document uses <px:import> elements, it must also support DOM Level 3 Core and LS.

The document object is generally transformed in-place. However in certain cases (particularly, changing a doctype with non-pxdom implementations) a copy may be made. In this case transformDocument will return the new copy instead of the original document.

After transformation, the Transformer object has the following readable properties:

Extended ‘optimised’ features

Compiler

If you wish to control the compilation of PXTL templates manually, you can do it using the pxtl.optimised.Compiler class. This takes a DOM tree and returns the text of a Python program to run it.

import pxtl.optimised
c= pxtl.optimised.Compiler()
program= c.compileDocument(document)
codeobject= compile(program, '<template>', 'exec')

The document will not be altered by compileDocument. Other arguments that may be passed are globals, an optional scope for the few code parts of PXTL templates that are evaluated at compile-time, and method, which if given will override any output method given in a doctype attribute or guessed automatically.

After compilation, the Transformer object has the following readable property:

compileFile

Used to pre-compile the bytecode files used by the optimised implementation, so that they can be loaded and executed quickly in the future without having to have write access to the place where bytecode files are stored. This can be used as part of an application install procedure in the same way as the standard library function py_compile.compile (with doraise set). The files themselves are exactly the same format as standard .pyc files, so are dependent on the version of Python used as well as the version of PXTL; if either do not match the template will be recompiled at run-time.

The required arguments to pxtl.optimised.compileFile are path and pathc, giving the pathname of the template source file to load and the compiled bytecode file to save, respectively.

Further optional arguments include globals and dom, which work the same way as the processFile arguments of the same name. globals is only used as the scope for calculating the contents of the doctype attribute, the only part of a PXTL template run at compile-time, so it too is not normally needed.

Finally there’s method and encoding, which can be used to override the output method (given in the px:doctype value) and the character encoding (given in the <?xml?> declaration). These are only generally required where the imported template has a different output method or encoding to the template that imports it (because in PXTL the importing templateଁs doctype is always used in preference). Otherwise they can be omitted. If the output method and encoding are wrong when the template comes to be run, it will simply be recompiled anyway.

prepareGlobals

Having compiled a template or unmarshalled its code from a bytecode file, you can run it using the standard Python exec statement. However, it expects a few internal PXTL variables to be put in its global scope before it can run, so that it knows, for example, what stream to send the output to.

Use the prepareGlobals function to write these internal variables before calling exec code in mapping. The arguments are writer, baseuri, headers, dom and bytecodebase.

baseuri should hold the URI of the source template, and can be omitted if PXTL import elements are not used, or if they are only used with absolute-URI src attributes. The other arguments are the same as for processFile

Other functions

The pxtl module contains two other functions that applications may occasionally want to use.

encodeText(text, coding): takes a string text, encodes it and returns it. The coding argument must be a string name of one of the PXTL coding formats, as used in PIs, for example 'upar'.

decodeName(name): takes a string name as encoded by the px_name PI/pseudo-PI and returns the original, decoded string. This may be needed if such a value is submitted in a form.

PXTL ‘server pages’

Normally it is expected that a PXTL page will be invoked and processed by a CGI script or other component of a web application framework.

It is, however, also possible to have a web server call a PXTL template directly. The template can contain code to process form submissions, take actions and output a page. This is the ‘server pages’ model employed by frameworks such as PHP, ASP and JSP.

This is not always considered an ideal approach to web application architecture, but it can certainly be useful for rapid prototyping. If you want PXTL to work this way you must configure your web server to associate .px files with PXTL.

(Note: in any case, if you are putting .px files in your web root, you should either use a bytecodebase outside the web root, or configure the server to block access to .pxc files. Otherwise users may be able to see your scripts’ cached bytecode, which could be a security issue.)

Apache

To enable PXTL server pages in Apache, create a .cgi file executable by Apache (eg. in the cgi-bin directory, with read and execute permission for all), containing:

#!/usr/bin/env python
import os, pxtl
pxtl.processFile(os.environ['PATH_TRANSLATED'], headers= True)

Add the argument debug= True to the last line if you want PXTL to output a debugging page in case of errors.

Finally, add the following configuration directives to Apache‘s httpd.conf (or .htaccess):

AddHandler pxtl-template .px
Action pxtl-template /cgi-bin/pxtl.cgi

Change the Action path if your CGI script is elsewhere.

IIS

To enable PXTL server pages in IIS, open Internet Services Manager (from Administrative Tools) and get the ‘Properties’ of the web site you wish to configure. Go to the ‘Home Directory’ tab, choose ‘Configuration...’ and add an application mapping for extension ‘.px’ with the value:

"PYPATH\python.exe" -u "PXPATH\pxtl\__init__.py" "%s"

If you want to use PXTL’s debugging page if an error occurs in the template code, add a -d switch:

"PYPATH\python.exe" -u "PXPATH\pxtl\__init__.py" -d "%s"

‘PYPATH’ must be substituted with the place where your Python executable is stored, for example ‘C:\Python23’; ‘PXPATH’ must be substituted with the place where your pxtl package is stored, for example ‘C:\Python23\Lib\site-packages’.

pxtl and pxdom

The pxtl package requires standards-compliant DOM Level 3 Core and LS functionality. For this reason the it includes a complete stand-alone pure-Python DOM 3 Core and LS implementation, which it uses by default. If you want to use it in your script, for example to create a DOM tree to pass to a Transformer or Compiler, use the module pxtl.pxdom as a DOMImplementationSource:

import pxtl.pxdom
implementation= pxtl.pxdom.getDOMImplementation('')

Then use DOM 3 methods such as createLSParser. Alternatively, the pxdom module offers the same convenience methods parse and parseString which work the same as the Python standard library module xml.dom.minidom.

More information on pxdom and using it in other applications.

If you have another DOM 3 implementation you would rather pxdom used, pass its DOMImplementation module into the processFile function’s dom argument.

Changelog

Updates from 1.4 to 1.5

Updates from 1.3 to 1.4

Updates from 1.2 to 1.3

Updates from 1.1 to 1.2

Updates from 1.0 to 1.1

Updates from 0.9 to 1.0

Licence (new-BSD-style)

Copyright © 2005, Andrew Clover. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

This software is provided by the copyright holder and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.