===================== Kid 0.6 Release Notes ===================== There has been significant change in version 0.6. This includes enhancements and modifications to the template language and python interface. .. contents:: Contents Language and API Changes ======================== The following changes are likely to impact existing code and templates. Where possible, we have tried to maintain backward compatibility but that wasn't possible in all cases. The `Upgrade Script`_ can be used to bring 0.5 templates up to 0.6 syntax. Kid Namespace Change -------------------- The Kid namespace has changed from ``http://naeblis.cx/ns/kid#`` to ``http://purl.org/kid/ns#``. The naeblis.cx domain is privately owned and could expire some time in the future. purl.org is a system for establishing and maintaining "persistent" URIs. A temporary hack has been put in place to substitute references to the old namespace URI with the new namespace URI. A warning is output when this occurs. This will be removed in a couple of months so it is recommended that templates be upgraded as soon as possible. ``py:omit`` is now ``py:strip`` ------------------------------- Due to initial confusion many experienced with the name ``py:omit``, it has been renamed ``py:strip``. The term "omit" was often read as "omit the element and all descendants". The new term "strip" seems to better indicate the semantic: "strip the start and end tag but process descendants." Python Expression Substitution Syntax ------------------------------------- The syntax of brace expansions has been modified match more closely with existing Python substitution syntax. In 0.5 python expressions enclosed in curly braces ({}) were evaluated and their results substituted. In 0.6, the rules have changed as follows: 1. ``$$`` is an escape; it is replaced with a single $. 2. ``$name`` substitutes a variable value. 3. ``${expr}`` substitutes the result of evaluating any python expression. See `Python Expression Substitution`__ in the Language Reference. .. __: language.html#python-expression-substitution-expr .. warning: The expression substitution **is not** backward compatible. If you use the old-style brace-expansion, you will need to upgrade your templates for Kid 0.6. Enhancements ============ cElementTree Support -------------------- Kid now uses cElementTree if it is available. Preliminary tests show moderate performance increases. In most cases, we're seeing template parse and execution time increase by about 15%. The poor increase (relative to other cET/ET numbers) is due to the fact that we're not using cElementTree's native parser as it doesn't support comments or processing instructions. The plan is to lobby the effbot organization to add these features (hint, hint: send patches) so that we can get the huge increases people are seeing elsewhere. Kid automatically determines whether cElementTree is available and uses it if so. If cElementTree is not available, Kid falls back on Python ElementTree. If you want to turn off use of cElementTree, you can set the environment variable ``KID_NOCET`` to 1. Death of Comment Wart --------------------- In versions of Kid prior to 0.6, the first line of an embedded Python code block had to be a Python comment (#). This was due to Python's whitespace semantics. Christoph determined a process for establishing the correct indent levels without requiring a comment as the first line. Starting in Kid 0.6, a comment is no longer required to be the first line in a ```` processing instruction. It is also possible to have single line code blocks:: Improved Template API --------------------- The Python interfaces have been reworked significantly and now are very similar to Cheetah's. There are two preferred methods for accessing a template. The ``Template`` Class ~~~~~~~~~~~~~~~~~~~~~~ The first method existed in 0.5 but was not documented well. If you have enabled the kid import hooks, then you can import a template and create an instance of the template by accessing the ``Template`` class exposed by the module:: import kid ; kid.enable_import() import mytemplate template = mytemplate.Template(foo='bar', bling=1) print template.serialize() The primary difference from 0.5 is that template variables are passed to the ``Template`` constructor instead of to the individual execution methods (``serialize``, ``generate``, ``write``, ``pull``). It is also possible to set template variables after the template instance is created by simply assigning to template object instance:: template = mytemplate.Template() template.foo = 'bar' template.bling = 1 print str(template) Here we see another small addition: template instances implement ``__str__`` and ``__unicode__`` built-ins. These methods are equivalent to calling ``serialize(encoding='utf-8')`` and ``serialize(encoding='utf-16')``, respectively. The ``kid.Template`` function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``kid.Template`` function works much like ``Template`` class constructors but takes an additional parameter that allows the template to be loaded from a file, string, or module name. It is sometimes easier to manage templates as files on disk rather than as python modules. Example:: from kid import Template # create a template from file template = Template(file='mytemplate.kid', foo='bar', bling=1) # create a template from string template = Template(source="

${foo}

", foo='bar') # create a template from a python module name template = Template(name='templates.mytemplate', foo='bar') This last form is sometimes useful because it doesn't require the kid import hook to be enabled and it also allows template names to be specified at run-time. See `kid.Template function`__ in the User's Guide for more info. .. __: guide.html#template-function Match Templates / Filters ------------------------- Match Templates are a cross between XSLT's match templates and JSP tag libraries. They allow a set of filters to be put in place that matches infoset items generated by a template so that output can be modified. While match templates provide a general purpose mechanism for transforming XML content, it is especially useful in a couple of situations which have driven the design: 1. Creating tag libraries that inject new tags into an XML vocabulary. 2. Applying headers/footers without inserting place-holders into the source document/template. See `Match Templates`__ in the Language Reference for more information. .. __: language.html#match-templates Template Inheritance -------------------- Templates now support multiple inheritance of template functions (``py:def``) and match templates (``py:match``). A template indicates that it extends one or more other templates by setting the ``py:extends`` attribute on the root element::