KNOWN ISSUES

- Jarek Zgoda reports that Python's HTMLParser module expands the following entity references where they appear in tag attributes values: &amp; &lt; &gt; &quot; - this is probably a bug. When defining HTML templates, use the equivalent character references - &#38; &#60; &#62; &#34; - within attribute values as these are not affected. Note that entity references appearing within HTML elements' content are not affected by this problem, nor are values inserted during template rendering (which are already subject to their own escaping rules). [2004-06-16] Stephen D Evans points out that &apos; is also decoded, and that this is partial decoding of attribute values is clearly deliberate as there's a unit test to cover it. (Note: HTMLParser's treatment of tag attribute values is very strange, as this partial decoding makes it impossible to safely decode other entities later on - e.g. consider how something like <foo bar="&amp;copy;"/> should/would be treated.) UPDATE: HTMLTemplate now overrides the undocumented HTMLParser method responsible for this partial decoding of attribute values so that the original values are preserved; this is a bit of a kludge, but the HTMLParser class's implementation is unlikely to change so should not present any problems.

- Python's HTMLParser module automatically lowercases all tag and attribute names. This shouldn't present any problems for templating HTML (which is case-insensitive by nature) nor for templating XHTML (which is all-lowercase anyway), but will cause problems for any ad-hoc XML templating where tags and attributes contain both lower and uppercase characters.

- HTMLTemplate's current API isn't well suited to event-driven use or introspection. Modified designs are being explored to address these limitations; input is welcome.

- A built-in convenience option for loading HTML templates from disk, e.g. Template(fn, file='foo.html'), may be worth adding if there's sufficient demand for it. Somewhat reluctant to do this as this isn't core functionality and file-based template management would be better done by a separate dedicated module, but pragmatism may be better choice - we'll see. As regards implementing a separate templatemanager module (the preferred solution), a simple implementation might define a class, each instance of which represents a directory where templates are kept, allowing templates to be loaded by filename, e.g.:

f = templatemanager.Folder('/path/to/templates/folder/')
foo = HTMLTemplate.Template(render_foo, f.template('foo.htm'))
bar = HTMLTemplate.Template(render_bar, f.template('bar.htm'))

A more sophisticated system could wrap HTMLTemplate completely to e.g. automatically associate on-disk Controller script and HTML template files with one another (e.g. name-based association would automatically pair 'FooTemplate.html' with 'FooController.py'), serve up compiled templates by name upon request and provide nifty stuff like automatic updates so that when a template's html or controller script is updated it automatically recompiles the template object, which'd be useful in long-running systems. Code coupling should be minimised and localised to allow the templatemanager module to be reused with other templating systems with minimal effort.