Python XML Templating Language
Implementation package ‘pxtl’ 2.0



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 a Python version between 2.2 and 2.7.

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


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

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.


process methods

The functions pxtl.processFile, pxtl.processString and pxtl.processURI provide the main interface to the package. processFile (which was the only method available prior to pxtl 1.9) is typically used, to load a PXTL document from the filesystem, run its code, and output the transformed file:

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

The process functions will use the optimised implementation by default. If you want to use a specific implementation, you can call it explicitly, using the same function names under pxtl.reference and pxtl.optimised.

Note: when the optimised implementation is in use, as it is by default, compiled bytecode will be stored in the same folder as the source template. Either the current user should have permissions to do this, or you should pre-compile your templates after changing the (eg using pxtl.optimised.compileAll) to ensure the bytecode is present, otherwise the template will have to be recompiled every time processFile is called. This is typically acceptable on a development server but undesirable in production. If you would rather store bytecode elsewhere, see the resolver argument.

Whichever implementation you use, the arguments are the same. The first argument is required and gives the iunput source: the path for processFile, the uri for processURI or the string content (bytes or unicode; however templates processed this way have no URI address so can't use relative imports). 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. Use a StringIO if you wish to capture the output in a string.

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="*"/>

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 DOMImplementation to use for XML work. This should normally be left unspecified, to use the embedded DOM implementation ‘pxdom’, which is the only sufficiently-compliant DOM Level 3 Core/LS implementation at the time of writing.

resolver: an object implementing the Resolver interface, to redirect access to template resources and compiled bytecode. If omitted, a StandardResolver object is used. In the processFile method only, for backwards compatibility, this argument may be a dictionary argument named bytecodebase, as a shortcut to a BytecodeResolver.


Resolvers allow access to template files and/or bytecode files to be redirected from the given absolute URI (as passed to processURI or read from an import element) to some other resource, either by changing the URI, or completely replacing the storage (eg to put templates in a database).

You can write your own resolvers by implementing the getResource(uri, ctype) and setResource(uri, ctype, content) methods; see the code/docstrings in pxtl.resolvers.Resolver for guidance. The pxtl.resolvers module contains some concrete resolver implementations for common cases:

StandardResolver: the normal default resolver. Fetches URIs using urllib, and writes bytecode only for filesystem URIs, under a filename changed to add a ‘c’ to the extension.

ReadonlyResolver: never stores bytecode.

BytecodeResolver: allows the location of bytecode storage to be changed. This resolver is passed a mapping of source URI keys to destination URI 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.

Optionally, if initialised with the isfilebased argument, operate on filepaths instead of URIs:

from os.path import join
resolver= pxtl.resolvers.BytecodeResolver({
  '/www/app/templates': '/www/app/bytecode',
  '/www/app/templates/tmp': '/www/app/tmpdir/bytecode',
}, isfilebased= True)
pxtl.processFile('/www/app/templates/info/index.px', resolver= resolver)

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

LookupResolver: a simple in-memory dictionary of URIs to resource content. This is good for long-lived servers with a simple set of templates which can be compiled once and left in memory. It should be initialised with a lookup dictionary argument mapping URIs to (content, ctype, mtime) tuples.

Extended ‘reference’ features


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


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:


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). Typically this happens when an XHTML template to-be-imported omits px:doctype, relying on the importing template to set the method to xhtml.

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, so there is not normally a problem, except when permissions don't allow the bytecode to be written, resulting in slow execution every time.


Compiles bytecode files recursively inside the given dir, analagous to the standard library compileall function.

Uses the optional argument resolver as in processFile, plus globals, dom, method and encoding from compileFile, and maxlevels and quiet from the standard compileall (so it defaults to 10 levels deep).


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


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.


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.


Updates from 1.9 to 2.0

Updates from 1.8 to 1.9

Updates from 1.7 to 1.8

Updates from 1.6 to 1.7

Updates from 1.5 to 1.6

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-2010, 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.