zope.tal

Latest release Supported Python versions https://travis-ci.org/zopefoundation/zope.tal.svg?branch=master https://coveralls.io/repos/github/zopefoundation/zope.tal/badge.svg?branch=master Documentation Status

The Zope3 Template Attribute Languate (TAL) specifies the custom namespace and attributes which are used by the Zope Page Templates renderer to inject dynamic markup into a page. It also includes the Macro Expansion for TAL (METAL) macro language used in page assembly.

The dynamic values themselves are specified using a companion language, TALES (see the zope.tales package for more).

The reference documentation for the TAL language is available at https://docs.zope.org/zope2/zope2book/AppendixC.html

Detailed documentation for this implementation and its API is available at https://zopetal.readthedocs.io/

Using zope.tal requires three steps: choosing an expression engine (usually zope.tales), creating a generator and parser, and then interpreting the compiled program:

from io import StringIO
from zope.tal.talgenerator import TALGenerator
from zope.tal.htmltalparser import HTMLTALParser
from zope.tal.talinterpreter import TALInterpreter

compiler = None # Will use a compiler for a dummy language
source_file = '<string>'
source_text = '<html><body><p>Hi</p></body></html>'
gen = TALGenerator(compiler, source_file=source_file)
parser = TALParser(gen)
parser.parseString(source_text)
program, macros = parser.getCode()

output = StringIO()
context = None # Usually will create a zope.tales context
interpreter = TALInterpreter(self.program, macros, context, stream=output)
interpreter()
result = output.getvalue()

These aspects are all brought together in zope.pagetemplate.

API Documentation:

Interfaces

Interface that a TAL expression implementation provides to the METAL/TAL implementation.

This package does not provide an implementation of ITALExpressionCompiler, ITALExpressionEngine or ITALIterator. An external package must provide those. The most commonly used are zope.tales.tales.ExpressionEngine, zope.tales.tales.Context, and zope.tales.tales.Iterator, respectively.

interface zope.tal.interfaces.ITALExpressionCompiler[source]

Compile-time interface provided by a TAL expression implementation.

The TAL compiler needs an instance of this interface to support compilation of TAL expressions embedded in documents containing TAL and METAL constructs.

getCompilerError()

Return the exception class raised for compilation errors.

compile(expression)

Return a compiled form of expression for later evaluation.

expression is the source text of the expression.

The return value may be passed to the various evaluate*() methods of the ITALExpressionEngine interface. No compatibility is required for the values of the compiled expression between different ITALExpressionEngine implementations.

getContext(namespace)

Create an expression execution context

The given namespace provides the initial top-level names.

interface zope.tal.interfaces.ITALExpressionEngine[source]

Render-time interface provided by a TAL expression implementation.

The TAL interpreter uses this interface to TAL expression to support evaluation of the compiled expressions returned by ITALExpressionCompiler.compile().

getDefault()

Return the value of the default TAL expression.

Checking a value for a match with default should be done using the is operator in Python.

setPosition(position)

Inform the engine of the current position in the source file.

position is a tuple (lineno, offset).

This is used to allow the evaluation engine to report execution errors so that site developers can more easily locate the offending expression.

setSourceFile(filename)

Inform the engine of the name of the current source file.

This is used to allow the evaluation engine to report execution errors so that site developers can more easily locate the offending expression.

beginScope()

Push a new scope onto the stack of open scopes.

endScope()

Pop one scope from the stack of open scopes.

evaluate(compiled_expression)

Evaluate an arbitrary expression.

No constraints are imposed on the return value.

evaluateBoolean(compiled_expression)

Evaluate an expression that must return a Boolean value.

evaluateMacro(compiled_expression)

Evaluate an expression that must return a macro program.

evaluateStructure(compiled_expression)

Evaluate an expression that must return a structured document fragment.

The result of evaluating compiled_expression must be a string containing a parsable HTML or XML fragment. Any TAL markup contained in the result string will be interpreted.

evaluateText(compiled_expression)

Evaluate an expression that must return text.

The returned text should be suitable for direct inclusion in the output: any HTML or XML escaping or quoting is the responsibility of the expression itself.

If the expression evaluates to None, then that is returned. It represents nothing in TALES. If the expression evaluates to what getDefault() returns, by comparison using is, then that is returned. It represents default in TALES.

evaluateValue(compiled_expression)

Evaluate an arbitrary expression.

No constraints are imposed on the return value.

createErrorInfo(exception, position)

Returns an ITALExpressionErrorInfo object.

position is a tuple (lineno, offset).

The returned object is used to provide information about the error condition for the on-error handler.

setGlobal(name, value)

Set a global variable.

The variable will be named name and have the value value.

setLocal(name, value)

Set a local variable in the current scope.

The variable will be named name and have the value value.

getValue(name, default=None)

Get a variable by name.

If the variable does not exist, return default.

setRepeat(name, compiled_expression)

Start a repetition, returning an ITALIterator.

The engine is expected to add the a value (typically the returned iterator) for the name to the variable namespace.

translate(msgid, domain=None, mapping=None, default=None)

See zope.i18n.interfaces.ITranslationDomain.translate

evaluateCode(lang, code)

Evaluates code of the given language.

Returns whatever the code outputs. This can be defined on a per-language basis. In Python this usually everything the print statement will return.

interface zope.tal.interfaces.ITALIterator[source]

A TAL iterator

Not to be confused with a Python iterator.

next()

Advance to the next value in the iteration, if possible

Return a true value if it was possible to advance and return a false value otherwise.

interface zope.tal.interfaces.ITALExpressionErrorInfo[source]

Information about an error.

type

The exception class.

value

The exception instance.

lineno

The line number the error occurred on in the source.

offset

The character offset at which the error occurred.

Common Definitions

Common definitions used by TAL and METAL compilation and transformation.

zope.tal.taldefs.TAL_VERSION = '1.6'

Version of the specification we implement.

zope.tal.taldefs.XML_NS = 'http://www.w3.org/XML/1998/namespace'

URI for XML namespace

zope.tal.taldefs.XMLNS_NS = 'http://www.w3.org/2000/xmlns/'

URI for XML NS declarations

zope.tal.taldefs.ZOPE_TAL_NS = 'http://xml.zope.org/namespaces/tal'

TAL namespace URI

zope.tal.taldefs.ZOPE_METAL_NS = 'http://xml.zope.org/namespaces/metal'

METAL namespace URI

zope.tal.taldefs.ZOPE_I18N_NS = 'http://xml.zope.org/namespaces/i18n'

I18N namespace URI

zope.tal.taldefs.KNOWN_METAL_ATTRIBUTES = frozenset(['use-macro', 'define-slot', 'extend-macro', 'define-macro', 'fill-slot'])

Known METAL attributes

zope.tal.taldefs.KNOWN_TAL_ATTRIBUTES = frozenset(['repeat', 'on-error', 'script', 'replace', 'content', 'omit-tag', 'attributes', 'tal tag', 'condition', 'define'])

Known TAL attributes

zope.tal.taldefs.KNOWN_I18N_ATTRIBUTES = frozenset(['domain', 'target', 'ignore-attributes', 'ignore', 'source', 'attributes', 'translate', 'data', 'name'])

Known I18N attributes

exception zope.tal.taldefs.TALError(msg, position=(None, None))[source]

Bases: exceptions.Exception

A base exception for errors raised by this implementation.

exception zope.tal.taldefs.METALError(msg, position=(None, None))[source]

Bases: zope.tal.taldefs.TALError

An error parsing on running METAL macros.

exception zope.tal.taldefs.TALExpressionError(msg, position=(None, None))[source]

Bases: zope.tal.taldefs.TALError

An error parsing or running a TAL expression.

exception zope.tal.taldefs.I18NError(msg, position=(None, None))[source]

Bases: zope.tal.taldefs.TALError

An error parsing a I18N expression.

class zope.tal.taldefs.ErrorInfo(err, position=(None, None))[source]

Bases: object

Default implementation of zope.tal.interfaces.ITALExpressionErrorInfo.

zope.tal.taldefs.attrEscape(s)[source]

Replace special characters ‘&<>’ by character entities, except when ‘&’ already begins a syntactically valid entity.

Generating Compiled Code

Code generator for TALInterpreter intermediate code.

class zope.tal.talgenerator.TALGenerator(expressionCompiler=None, xml=1, source_file=None)[source]

Bases: object

Generate intermediate code.

Parameters:expressionCompiler – The implementation of zope.tal.interfaces.ITALExpressionCompiler to use. If not given, we’ll use a simple, undocumented, compiler.

Parsing and Compiling HTML

Parse HTML and compile to TALInterpreter intermediate code, using a TALGenerator.

zope.tal.htmltalparser.BOOLEAN_HTML_ATTRS = frozenset(['compact', 'defer', 'checked', 'selected', 'ismap', 'disabled', 'readonly', 'noshade', 'noresize', 'multiple', 'nowrap', 'declare'])

List of Boolean attributes in HTML that may be given in minimized form (e.g. <img ismap> rather than <img ismap="">) From http://www.w3.org/TR/xhtml1/#guidelines (C.10)

zope.tal.htmltalparser.EMPTY_HTML_TAGS = frozenset(['isindex', 'img', 'area', 'hr', 'frame', 'meta', 'param', 'basefont', 'base', 'link', 'br', 'input', 'col'])

List of HTML tags with an empty content model; these are rendered in minimized form, e.g. <img />. From http://www.w3.org/TR/xhtml1/#dtds

zope.tal.htmltalparser.PARA_LEVEL_HTML_TAGS = frozenset(['h2', 'h3', 'h1', 'h6', 'h4', 'h5', 'p'])

List of HTML elements that close open paragraph-level elements and are themselves paragraph-level.

zope.tal.htmltalparser.BLOCK_CLOSING_TAG_MAP = {'dd': frozenset(['dd', 'dt']), 'tr': frozenset(['td', 'tr', 'th']), 'li': frozenset(['li']), 'th': frozenset(['td', 'th']), 'dt': frozenset(['dd', 'dt']), 'td': frozenset(['td', 'th'])}

Tags that automatically close other tags.

zope.tal.htmltalparser.BLOCK_LEVEL_HTML_TAGS = frozenset(['dl', 'blockquote', 'dd', 'noframe', 'tr', 'tbody', 'li', 'ul', 'ol', 'tfoot', 'th', 'table', 'td', 'div', 'dt', 'thead'])

List of HTML tags that denote larger sections than paragraphs.

zope.tal.htmltalparser.SECTION_LEVEL_HTML_TAGS = frozenset(['dl', 'blockquote', 'th', 'h2', 'h3', 'dd', 'h1', 'h6', 'h4', 'h5', 'table', 'dt', 'div', 'ol', 'ul', 'tr', 'tbody', 'li', 'p', 'tfoot', 'noframe', 'td', 'thead'])

Section level HTML tags

exception zope.tal.htmltalparser.NestingError(tagstack, endtag, position=(None, None))[source]

Bases: HTMLParser.HTMLParseError

Exception raised when elements aren’t properly nested.

exception zope.tal.htmltalparser.EmptyTagError(tag, position=(None, None))[source]

Bases: zope.tal.htmltalparser.NestingError

Exception raised when empty elements have an end tag.

exception zope.tal.htmltalparser.OpenTagError(tagstack, tag, position=(None, None))[source]

Bases: zope.tal.htmltalparser.NestingError

Exception raised when a tag is not allowed in another tag.

class zope.tal.htmltalparser.HTMLTALParser(gen=None)[source]

Bases: HTMLParser.HTMLParser

Parser for HTML.

After you call either parseFile() and parseString() you can retrieve the compiled program using getCode().

Parameters:gen (TALGenerator) – The configured (with an expression compiler) code generator to use. If one is not given, a default will be used.
parseFile(file)[source]

Parse data in the given file.

parseString(data)[source]

Parse data in the given string.

getCode()[source]

After parsing, this returns (program, macros).

Parsing and Compiling XML

Parse XML and compile to TALInterpreter intermediate code, using a TALGenerator.

class zope.tal.talparser.TALParser(gen=None, encoding=None)[source]

Bases: zope.tal.xmlparser.XMLParser

Parser for XML.

After parsing with parseFile(), parseString(), parseURL() or parseStream(), you can call getCode() to retrieve the parsed program and macros.

Parameters:gen (TALGenerator) – The configured (with an expression compiler) code generator to use. If one is not given, a default will be used.
getCode()[source]

Return the compiled program and macros after parsing.

class zope.tal.xmlparser.XMLParser(encoding=None)[source]

Bases: object

Parse XML using xml.parsers.expat.

parseFile(filename)[source]

Parse from the given filename.

parseString(s)[source]

Parse the given string.

parseURL(url)[source]

Parse the given URL.

parseStream(stream)[source]

Parse the given stream (open file).

Interpreting Compiled Code

Interpreter for a pre-compiled TAL program.

class zope.tal.talinterpreter.MacroStackItem[source]

Bases: list

Stack entry for the TALInterpreter.macroStack.

This offers convenience attributes for more readable access.

class zope.tal.talinterpreter.TALInterpreter(program, macros, engine, stream=None, debug=0, wrap=1023, metal=1, tal=1, showtal=-1, strictinsert=1, stackLimit=100, i18nInterpolate=1, sourceAnnotations=0)[source]

Bases: object

TAL interpreter.

Some notes on source annotations. They are HTML/XML comments added to the output whenever sourceFile is changed by a setSourceFile bytecode. Source annotations are disabled by default, but you can turn them on by passing a sourceAnnotations argument to the constructor. You can change the format of the annotations by overriding formatSourceAnnotation in a subclass.

The output of the annotation is delayed until some actual text is output for two reasons:

  1. setPosition bytecode follows setSourceFile, and we need position information to output the line number.
  2. Comments are not allowed in XML documents before the <?xml?> declaration.

For performance reasons (TODO: premature optimization?) instead of checking the value of _pending_source_annotation on every write to the output stream, the _stream_write attribute is changed to point to _annotated_stream_write method whenever _pending_source_annotation is set to True, and to _stream.write when it is False. The following invariant always holds:

if self._pending_source_annotation:
    assert self._stream_write is self._annotated_stream_write
else:
    assert self._stream_write is self.stream.write

Create a TAL interpreter.

Parameters:

Optional arguments:

Parameters:
  • stream – output stream (defaults to sys.stdout).
  • debug (bool) – enable debugging output to sys.stderr (off by default).
  • wrap (int) – try to wrap attributes on opening tags to this number of column (default: 1023).
  • metal (bool) – enable METAL macro processing (on by default).
  • tal (bool) – enable TAL processing (on by default).
  • showtal (int) – do not strip away TAL directives. A special value of -1 (which is the default setting) enables showtal when TAL processing is disabled, and disables showtal when TAL processing is enabled. Note that you must use 0, 1, or -1; true boolean values are not supported (for historical reasons).
  • strictinsert (bool) – enable TAL processing and stricter HTML/XML checking on text produced by structure inserts (on by default). Note that Zope turns this value off by default.
  • stackLimit (int) – set macro nesting limit (default: 100).
  • i18nInterpolate (bool) – enable i18n translations (default: on).
  • sourceAnnotations (bool) – enable source annotations with HTML comments (default: off).

Changes

4.3.1 (unreleased)

4.3.0 (2017-08-08)

  • Drop support for Python 3.3.
  • Add support for Python 3.6.

4.2.0 (2016-04-12)

  • Drop support for Python 2.6 and 3.2.
  • Accept and ignore i18n:ignore and i18n:ignore-attributes attributes. For compatibility with other tools (such as i18ndude).
  • Add support for Python 3.5.

4.1.1 (2015-06-05)

  • Suppress deprecation under Python 3.4 for default convert_charrefs argument (passed to HTMLParser). Also ensures that upcoming change to the default in Python 3.5 will not affect us.
  • Add support for Python 3.2 and PyPy3.

4.1.0 (2014-12-19)

Note

Support for PyPy3 is pending release of a fix for: https://bitbucket.org/pypy/pypy/issue/1946

  • Add support for Python 3.4.
  • Add support for testing on Travis.

4.0.0 (2014-01-13)

  • Fix possible UnicodeDecodeError in warning when msgid already exists.

4.0.0a1 (2013-02-15)

  • Replace deprecated zope.interface.implements usage with equivalent zope.interface.implementer decorator.
  • Add support for Python 3.3 and PyPy.
  • Drop support for Python 2.4 and 2.5.
  • Output attributes generate via tal:attributes and i18n:attributes directives in alphabetical order.

3.6.1 (2012-03-09)

3.6.0 (2011-08-20)

  • Update talinterpreter.FasterStringIO to faster list-based implementation.
  • Increase the default value of the wrap argument from 60 to 1023 characters, to avoid extra whitespace and line breaks.
  • Fix printing of error messages for msgid conflict with non-ASCII texts.

3.5.2 (2009-10-31)

  • In talgettext.POEngine.translate, print a warning if a msgid already exists in the domain with a different default.

3.5.1 (2009-03-08)

  • Update tests of “bad” entities for compatibility with the stricter HTMLParser module shipped with Python 2.6.x.

3.5.0 (2008-06-06)

3.4.1 (2007-11-16)

  • Remove unnecessary dummyengine dependency on zope.i18n to simplify distribution. The dummyengine.DummyTranslationDomain class no longer implements zope.i18n.interfaces.ITranslationDomain as a result. Installing zope.tal with easy_install or buildout no longer pulls in many unrelated distributions.
  • Support running tests using setup.py test.
  • Stop pinning (no longer required) zope.traversing and zope.app.publisher versions in buildout.cfg.

3.4.0 (2007-10-03)

  • Update package meta-data.

3.4.0b1

  • Update dependency on zope.i18n to a verions requiring the correct version of zope.security, avoiding a hidden dependency issue in zope.security.

Note

Changes before 3.4.0b1 where not tracked as an individual package and have been documented in the Zope 3 changelog.

Indices and tables