Link: start Link: parent Link: First page in set (first) Link: Previous page (previous) Link: Next page (next) Link: Last page in set (last) Link: A plain text version of this page (alternate) Link: The XIST source of this page (alternate) Advanced XIST ============= Converter contexts, pool chaining, namespace extensions, conversion targets, validation ======================================================================================= Home > Python software > ll.xist > Advanced topics Text · XIST Python softwarelist of projects * ll.xistAn extensible XML/HTML generator * ExamplesParsing/creating/modifying XML; Traversing XML trees * HowtoExplains parsing/generating XML files, XML transformations via XIST classes and other basic concepts. * SearchingHow to iterate through XIST trees * TransformationHow to transform XIST trees * Advanced topicsPool chaining, converter contexts, validation * MiscellaneousExplains various odds and ends of XIST * xscXIST core classes * nsPackage containing namespace modules * parseParsing XML * presentScreen output of XML trees * simsSimple schema validation * xfindTree iteration and filtering * cssCSS related functions * scriptsScripts for text conversion and creating XIST namespaces * HistoryChangeLog for XIST * InstallationHow to install and configure XIST * MigrationHow to update your code to new versions of XIST * Mailing listsHow to subscribe to the XIST mailing lists * ll.ul4cA templating language * ll.urlRFC 2396 compliant URLs * ll.makeObject oriented make replacement * ll.daemonForking daemon processes * ll.sisyphusWriting cron jobs with Python * ll.colorRGB color values and color model conversion * ll.miscMisc utility functions and classes * ll.orasqlUtilities for cx_Oracle * ll.nightshadeServe the output of Oracle functions/procedures with CherryPy * ll.scriptsScripts for UL4 template rendering and URL handling * AploraLogging Apache HTTP requests to an Oracle database * PycocoPython code coverage * DownloadLinks to Windows and Linux, source and binary distributions * Source codeAccess to the Mercurial repositories Converter contexts ================== Converter contexts can be used to pass around information in recursive calls to the convert and mapped methods. A Converter object will be passed in all calls, so this object is the place to store information. However if each element, procinst and entity class decided on its own which attributes names to use, name collisions would be inevitale. To avoid this, the following system is used. When a class wants to store information in a converter, it has to define a Context class (normally derived from the Context class of its base class). The constructor must initialize the context object to a initial state. You can get the context object for a certain class by treating the converter as a dictionary with the class (or an instance) as the key like this: from ll.xist import xsc class counter(xsc.Element): · class Context(xsc.Element.Context): · · def __init__(self): · · · xsc.Element.Context.__init__(self) · · · self.count = 0 · def convert(self, converter): · · context = converter[self] · · node = xsc.Text(context.count) · · context.count += 1 · · return node Defining and using a converter context Chaining pools and extending namespaces ======================================= When using pools it's possible to do some sort of "namespace subclassing". Registering a module in a pool not only registers the element, procinst and entity classes in the pool for parsing, but each attribute of the module (as long as it's weak referencable) is available as an attribute of the pool itself: from ll.xist import xsc from ll.xist.ns import html pool = xsc.Pool(html) print pool.img Pool attributes This outputs . It's possible to chain pools together. When an attribute isn't found in the first pool, it will be looked up in a second pool (the so called base pool): from ll.xist import xsc from ll.xist.ns import html, svg hpool = xsc.Pool(html) spool = xsc.Pool(svg, hpool) print spool.img Pool chaining Here the hpool (containing the html namespace) will be used when the attribute can't be found in spool. So this will again give the output . It's possible to get automatic pool chaining. If a module has an attribute __bases__ (which must be a sequence of modules), they will automatically be wrapped in a pool and used as the base pools for the pool created for the first module. This makes it possible to "overwrite" element classes in existing namespaces. For example to replace the a class in ll.xist.ns.html, put the following into a module html2: from ll.xist.ns import html __bases__ = [html] class a(html.a): · xmlns = html.xmlns · def convert(self, converter): · · node = html.a(self.content, self.attrs, target="_top") · · return node.convert(converter) Automatic pool chaining (html2.py) Now you can use the module in a pool: from ll.xist import xsc import html2 pool = xsc.Pool(html2) print pool.a, pool.b Using a pool chain This outputs: Note that such a chained pool can of course be used when parsing XML. The parser will recursively search for the first class that has the appropriate name when instantiating the tree nodes. Conversion targets ================== The converter argument passed to the convert method has an attribute target which is a module or pool and specifies the target namespace to which self should be converted. You can check which conversion is wanted by checking e.g. the xmlns atribute. Once this is determined you can use element classes from the target to create the required XML object tree. This makes it possible to customize the conversion by passing a chained pool to the convert method that extends an existing namespace. The following example shows how an element be converted to two different targets: from ll.xist import xsc from ll.xist.ns import html, fo class bold(xsc.Element): · def convert(self, converter): · · if converter.target.xmlns == html.xmlns: · · · node = converter.target.b(self.content) · · elif converter.target.xmlns == fo.xmlns: · · · node = converter.target.inline(self.content, font_weight="bold") · · else: · · · raise TypeError("unsupported conversion target {!r}".format(converter.target)) · · return node.convert(converter) Using conversion targets The default target for conversion is ll.xist.ns.html. Other targets can be specified via the target argument in the Converter constructor or the conv method: >>> from ll.xist.ns import html, fo >>> import foo # This is the code from above >>> print foo.bold("foo").conv().bytes() foo >>> print foo.bold("foo").conv(target=html).bytes() foo >>> print foo.bold("foo").conv(target=fo).bytes() foo Validation and content models ============================= When generating HTML you might want to make sure that your generated code doesn't contain any illegal tag nesting (i.e. something bad like

foo

). The module ll.xist.ns.html does this automatically: >>> from ll.xist.ns import html >>> node = html.p(html.p(u"foo")) >>> print node.bytes() /Users/walter/checkouts/LivingLogic.Python.xist/src/ll/xist/sims.py:222: \ WrongElementWarning: element \ may not contain element warnings.warn(WrongElementWarning(node, child, self.elements))

foo

For your own elements you can specify the content model too. This is done by setting the class attribute model inside the element class. model must be an object that provides a checkvalid method. This method will be called during parsing or publishing with the element as an argument. When invalid content is detected, the Python warning framework should be used to issue a warning. The module ll.xist.sims contains several classes that provide simple validation methods: Empty can be used to ensure that the element doesn't have any content (like br and img in HTML). Any does allow any content. NoElements will warn about elements from the same namespace (elements from other namespaces will be OK). NoElementsOrText will warn about elements from the same namespace and non-whitespace text content. Elements will only allow the elements specified in the constructor. ElementsOrText will only allow the elements specified in the constructor and text. None of these classes will check the number of child elements or their order. For more info see the sims module.