Next / Previous / Contents / Shipman's homepage

4.2. The Sox class

To start generation of an XML file, use the constructor this way:

from sox import Sox
  ...
sox = Sox(outFile=None)

The outFile argument may be any writeable file; the default value is sys.stdout.

Attributes and methods of this class:

.start(name, *p, **kw)

Start a new element of the given name. Additional positional arguments of type unicode will be added as text content after the start tag. Arguments of type str will be converted to Unicode using the UTF-8 encoding. Arguments of type int, or bool will be converted to Unicode and then added as text content.

Arguments of type dict will be translated into attributes in the start tag. Each keyword argument will be translated into a single attribute.

The method returns an instance of class Elt (see Section 4.3, “The Elt class: An element in progress”) that must be used to terminate the element later on. That same instance is also pushed on the Sox instance's internal stack.

If the element name or any attribute names are not valid according to the XML rules, this method will raise a SoxError. For the rules governing names, see Section 4.4, “Name validation”.

Non-ASCII characters in attribute values will be replaced by XML character references. For example, code point #x262e will appear as “☮”. Additionally, in the values of attributes, these substitutions will be performed:

<&lt;
&&amp;
"&quot;
.end(elt)

If the elt argument matches the one at the top of the Sox instance's internal stack, the method writes an end tag for this element to the output file and pops that element off the stack.

If there is no match, the method raises a SoxError.

.write(*p)

The arguments must be Unicode strings, or any of the types that result in element content when passed to the .start() method (they may not be dictionaries). The content is written immediately to the output file.

.leaf(*p, **kw)

This method is for generating a “leaf” of the XML tree, that is, an element with no element children. The arguments are interpreted in the same way as arguments to the .start() method. If none of the arguments produced any textual content inside the element, you will get an empty tag; otherwise the result will place start and end tags around the content.

.flush()

Forces any buffered output to be written.

.cleanup()

If you want to be certain that all your elements have been closed, call this method. It checks that the internal stack is empty. If not, it raises a SoxError.

.close()

Calls the .cleanup() method and then closes the output file.

.comment(text)

Emits an XML comment to the output. The text argument is Unicode or a string that can be converted to Unicode via the UTF-8 encoding.

The comment text may not include two consecutive hyphen (--) characters. It may not start or end with a hyphen. The method will raise a SoxError if these rules are violated.

.pi(target, args)

Emits an XML processing instruction to the output. The target argument must be Unicode or convertible to Unicode via UTF-8, and also conform to the rules for XML names. The args text is Unicode or convertible to Unicode, and may not contain any instances of the string "?>".

.doctype(name, pubId=None, sysId=None)

Writes a DOCTYPE declaration.

  • The name must be the XML element name of the root element.

  • If neither of the optional arguments is given, the output looks like this:

    <!DOCTYPE name>
    

    If a pubId is given but not a sysId:

    <!DOCTYPE name PUBLIC "pubId">
    

    If a sysId is given but not a pubId:

    <!DOCTYPE name SYSTEM "sysId">
    

    If both the pubId and sysId are given:

    <!DOCTYPE name PUBLIC "pubId" "sysId">