To start generation of an XML file, use the constructor this way:
from sox import Sox ... sox = Sox(
argument may be any writeable file; the default value is
Attributes and methods of this class:
.start(name, *p, **kw)
Start a new element of the given
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
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
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
#x262e will appear as “
☮”. Additionally, in the
values of attributes, these substitutions will be
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
The arguments must be Unicode strings, or any of the
types that result in element content when passed
.start() method (they may
not be dictionaries). The content is written
immediately to the output file.
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
Forces any buffered output to be written.
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
.cleanup() method and then
closes the output file.
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.
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
is Unicode or convertible to Unicode, and may not
contain any instances of the string
.doctype(name, pubId=None, sysId=None)
name must be the XML element
name of the root element.
If neither of the optional arguments is given, the output looks like this:
pubId is given but not a
sysId is given but not a
If both the
sysId are given: