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.5a2. 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.
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.
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.
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:
px:doctype
attribute, this is guessed as either ‘xml’ or ‘xhtml’.
px:doctype attribute,
None if not specified
px_mark PI, pxtl.write(..., 'mark')
commands and px:import with an XML media type.
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 bytecodebase 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
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.
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’.
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.
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.