Next / Previous / Contents / Shipman's homepage

5. Design notes

Before we discuss the specific features of the fosox package, let's discuss some of the underlying design concepts.

The Sox class used to generate XML as a stream is very efficient in its use of memory (see Section 2, “XSL-FO resources” for links to this package). However, it does impose one important constraint: you must generate the elements in document order. If the document is a simple table, that may not be a problem. In general, though, you may have to do some marshaling of the information into data structures that are amenable to sequential generation of the content.

Most of the functions provided by the fosox module require a Sox instance to start their element. All these modules will return a token (actually an instance of class sox.Elt) that you must later use to generate the closing tag by calling the token's .end() method.

5.1. Dashing from camelCase

This interface was strongly influenced by Fredrik Lundh's article An ElementTree builder. The author likes the way that the flexibility of Python calling sequences allows one to build many small XML structures in a single line of code.

One of the handy features of Lundh's package is that XML tag names and attributes that happened to be legal Python names could be used directly in the code. For example, once you have imported Lundh's magic E factory object, this code:

E.h1('Title', id='x37')

is all you need to build this XHTML element:

<h1 id='x37'>Title</h1>

However, the great majority of XSL-FO element and attribute names contain hyphens, and some attributes even contain periods (.); neither character is valid in a Python name.

Hence, the fosox module provides a number of features that allow you to substitute the equivalent name in camelCase form.

  • For each sequence aB in your name, where a is a lowercase letter and B is an uppercase letter, the package will substitute the sequence a-b.

  • For each underbar (“_”) in your name, the package will substitute “.”.

Here are some examples.

Your nameXSL-FO name
regionBeforeregion-before
simplePageMastersimple-page-master
spaceBefore_minimumspace-before.minimum

The fosox module provides a large number of functions that generate specific XSL-FO elements, but there is no point in trying to provide a specific Python interface for every one of the hundreds of element types. For the ones not covered here, you can create them directly through the Sox instance.

The package provides these two functions that you will use often.

deCamel(s)

For any string s, returns the “de-camel-cased” equivalent.

>>> deCamel('spaceBefore_minimum')
'space-before.minimum'
dash(**kw)

Given a set of keyword arguments, returns a single dictionary with the same set of values, but with each key run through the deCamel() function. The resulting dictionary is typically used to apply a set of attributes to an XSL-FO element.

>>> dash(borderCollapse='collapse', marginTop='1pc', width='6.5in',
...      fontSize='10pt', fontFamily='Palatino, serif')
{'width': '6.5in', 'margin-top': '1pc', 'font-family': 'Palatino, serif',
'font-size': '10pt', 'border-collapse': 'collapse'}