libSBML Python API  5.11.0
libsbml.XMLOutputStream Class Reference
Inheritance diagram for libsbml.XMLOutputStream:
[legend]

Detailed Description

Interface to an XML output stream.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

SBML content is serialized using XML; the resulting data can be stored and read to/from a file or data stream. Low-level XML parsers such as Xerces provide facilities to read XML data. To permit the use of different XML parsers (Xerces, Expat or libxml2), libSBML implements an abstraction layer. XMLInputStream and XMLOutputStream are two parts of that abstraction layer.

XMLOutputStream provides a wrapper above output streams to facilitate writing XML. XMLOutputStream keeps track of start and end elements, indentation, XML namespace prefixes, and more. The interface provides features for converting non-text data types into appropriate textual form; this takes the form of overloaded writeAttribute(...) methods that allow users to simply use the same method with any data type. For example, suppose an element testElement has two attributes, size and id, and the attributes are variables in your code as follows:

1 size = 3.2;
2 id = 'id';

Then, the element and the attributes can be written to the standard output stream (provided as cout in the libSBML language bindings) as follows:

1 from libsbml import *
2 
3 size = 3.2;
4 id = 'id';
5 
6 # Create an XMLOutputStream object that will write to the standard
7 # output stream, which is provide in libSBML's Python language
8 # interface as the object 'libsbml.cout'. Since we imported * from
9 # the libsbml module, we can simply refer to it as 'cout' here:
10 
11 output_stream = XMLOutputStream(cout)
12 
13 # Create the start element, write the attributes, and close the
14 # element. The output is written immediately by each method.
15 
16 output_stream.startElement('testElement')
17 output_stream.writeAttribute('size', size)
18 output_stream.writeAttribute('id', id)
19 output_stream.endElement('testElement')

Other classes in SBML take XMLOutputStream objects as arguments, and use that to write elements and attributes seamlessly to the XML output stream.

It is also worth noting that unlike XMLInputStream, XMLOutputStream is actually independent of the underlying XML parsers. It does not use the XML parser libraries at all.

Note
The convenience of the XMLInputStream and XMLOutputStream abstraction may be useful for developers interested in creating parsers for other XML formats besides SBML. It can provide developers with a layer above more basic XML parsers, as well as some useful programmatic elements such as XMLToken, XMLError, etc.
See also
XMLInputStream

Public Member Functions

def __init__ (self, args)
  Interface to an XML output stream. More...
 
def downIndent (self)
 Decreases the indentation level for this XMLOutputStream. More...
 
def endElement (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def getSBMLNamespaces (self)
 Returns the SBMLNamespaces object attached to this output stream. More...
 
def setAutoIndent (self, indent)
 Turns automatic indentation on or off for this XMLOutputStream. More...
 
def setSBMLNamespaces (self, sbmlns)
 Sets the SBMLNamespaces object associated with this output stream. More...
 
def startElement (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def startEndElement (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def upIndent (self)
 Increases the indentation level for this XMLOutputStream. More...
 
def writeAttribute (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def writeComment (self, programName, programVersion)
 Writes an XML comment with the name and version of this program. More...
 
def writeXMLDecl (self)
 Writes a standard XML declaration to this output stream. More...
 

Member Function Documentation

def libsbml.XMLOutputStream.downIndent (   self)

Decreases the indentation level for this XMLOutputStream.

downIndent()

LibSBML tries to produce human-readable XML output by automatically indenting the bodies of elements. Callers can manually control indentation further by using the XMLOutputStream.upIndent() and XMLOutputStream.downIndent() methods to increase and decrease, respectively, the current level of indentation in the XML output.

See also
upIndent()
def libsbml.XMLOutputStream.endElement (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

endElement(string name, string prefix)
endElement(string name)
endElement(XMLTriple triple)

Each variant is described separately below.


Method variant with the following signature:
endElement(string name, string prefix = '')

Writes the given XML end element name to this XMLOutputStream.

Parameters
namethe name of the element.
prefixan optional XML namespace prefix to write in front of the element name. (The result has the form prefix:name.)

Method variant with the following signature:
endElement(XMLTriple triple)

Writes the given element to the stream.

Parameters
triplethe XML element to write.
def libsbml.XMLOutputStream.getSBMLNamespaces (   self)

Returns the SBMLNamespaces object attached to this output stream.

getSBMLNamespaces()   SBMLNamespaces
Returns
the SBMLNamespaces object, or None if none has been set.
def libsbml.XMLOutputStream.setAutoIndent (   self,
  indent 
)

Turns automatic indentation on or off for this XMLOutputStream.

setAutoIndent(bool indent)
Parameters
indentif True, automatic indentation is turned on.
def libsbml.XMLOutputStream.setSBMLNamespaces (   self,
  sbmlns 
)

Sets the SBMLNamespaces object associated with this output stream.

setSBMLNamespaces(SBMLNamespaces sbmlns)
Parameters
sbmlnsthe namespace object.
def libsbml.XMLOutputStream.startElement (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

startElement(string name, string prefix)
startElement(string name)
startElement(XMLTriple triple)

Each variant is described separately below.


Method variant with the following signature:
startElement(string name, string prefix = '')

Writes the given XML start element name to this XMLOutputStream.

Parameters
namethe name of the element.
prefixan optional XML namespace prefix to write in front of the element name. (The result has the form prefix:name.)

Method variant with the following signature:
startElement(XMLTriple triple)

Writes the given XML start element prefix:name on this output stream.

Parameters
triplethe start element to write.
def libsbml.XMLOutputStream.startEndElement (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

startEndElement(string name, string prefix)
startEndElement(string name)
startEndElement(XMLTriple triple)

Each variant is described separately below.


Method variant with the following signature:
startEndElement(string name, string prefix = '')

Writes the given XML start and end element name to this XMLOutputStream.

Parameters
namethe name of the element.
prefixan optional XML namespace prefix to write in front of the element name. (The result has the form prefix:name.)

Method variant with the following signature:
startEndElement(XMLTriple triple)

Writes the given start element to this output stream.

Parameters
triplethe XML element to write.
def libsbml.XMLOutputStream.upIndent (   self)

Increases the indentation level for this XMLOutputStream.

upIndent()

LibSBML tries to produce human-readable XML output by automatically indenting the bodies of elements. Callers can manually control indentation further by using the XMLOutputStream.upIndent() and XMLOutputStream.downIndent() methods to increase and decrease, respectively, the current level of indentation in the XML output.

See also
downIndent()
def libsbml.XMLOutputStream.writeAttribute (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

writeAttribute(string name, string value)
writeAttribute(string name, string prefix, string value)
writeAttribute(XMLTriple triple, string value)
writeAttribute(string name, string value)
writeAttribute(string name, string prefix, string value)
writeAttribute(XMLTriple triple, string value)
writeAttribute(string name, bool value)
writeAttribute(string name, string prefix, bool value)
writeAttribute(XMLTriple triple, bool value)
writeAttribute(string name, float value)
writeAttribute(string name, string prefix, float value)
writeAttribute(XMLTriple triple, float value)
writeAttribute(string name, long value)
writeAttribute(string name, string prefix, long value)
writeAttribute(XMLTriple triple, long value)
writeAttribute(string name, int value)
writeAttribute(string name, string prefix, int value)
writeAttribute(XMLTriple triple, int value)
writeAttribute(string name, string prefix, long value)

Each variant is described separately below.


Method variant with the following signature:
writeAttribute(string name, string prefix, string value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string prefix, int& value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, long& value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string prefix, string value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, float value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, bool& value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, string value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, int& value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, string value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, long& value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string prefix, float value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, float value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, bool& value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, long& value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, long& value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(XMLTriple triple, int& value)

Writes the given attribute and value to this output stream.

Parameters
triplethe attribute, in the form of an XMLTriple.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, stringprefix, bool& value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string prefix, long& value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string prefix, long& value)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters
namethe name of the attribute.
prefixan XML namespace prefix to write in front of the element name. (The result has the form prefix:name.) See other versions of this method for a variant that does not require a prefix.
valuethe value of the attribute.

Method variant with the following signature:
writeAttribute(string name, string value)

Writes the given attribute and value to this output stream.

Parameters
namethe name of the attribute.
valuethe value of the attribute.
def libsbml.XMLOutputStream.writeComment (   self,
  programName,
  programVersion 
)

Writes an XML comment with the name and version of this program.

writeComment(string programName, string programVersion)

The XML comment has the following form:

<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->

See the class constructor for more information about this program comment.

Parameters
programNamean optional program name to write as a comment in the output stream.
programVersionan optional version identification string to write as a comment in the output stream.
def libsbml.XMLOutputStream.writeXMLDecl (   self)

Writes a standard XML declaration to this output stream.

writeXMLDecl()
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>
Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.