libSBML Python API  5.18.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)
 Creates a new XMLOutputStream that wraps the given 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 getLibraryName ()
 
def getLibraryVersion ()
 
def getSBMLNamespaces (self)
 Returns the SBMLNamespaces object attached to this output stream. More...
 
def getWriteComment ()
 
def getWriteTimestamp ()
 
def setAutoIndent (self, indent)
 Turns automatic indentation on or off for this XMLOutputStream. More...
 
def setLibraryName (libraryName)
 sets the name of the library writing the XML More...
 
def setLibraryVersion (libraryVersion)
 sets the name of the library writing the output More...
 
def setSBMLNamespaces (self, sbmlns)
 Sets the SBMLNamespaces object associated with this output stream. More...
 
def setWriteComment (writeComment)
 
def setWriteTimestamp (writeTimestamp)
 
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, writeTimestamp=True)
 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...
 

Constructor & Destructor Documentation

def libsbml.XMLOutputStream.__init__ (   self,
  args 
)

Creates a new XMLOutputStream that wraps the given stream.

__init__(ostream stream, string encoding, bool writeXMLDecl, string programName, string programVersion)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl, string programName)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl)   XMLOutputStream
__init__(ostream stream, string encoding)   XMLOutputStream
__init__(ostream stream)   XMLOutputStream

The functionality associated with the programName and programVersion arguments concerns an optional comment that libSBML can write at the beginning of the output stream. The comment is intended for human readers of the XML file, and has the following form:

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

This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.

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.

Parameters
streamthe input stream to wrap.
encodingthe XML encoding to declare in the output. This value should be "UTF-8" for SBML documents. The default value is "UTF-8" if no value is supplied for this parameter.
writeXMLDeclwhether to write a standard XML declaration at the beginning of the content written on stream. The default is true.
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.
Documentation note:
The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

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, bool text)
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.)
Note
Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

Method variant with the following signature:
endElement(XMLTriple triple, bool text = false)

Writes the given element to the stream.

Parameters
triplethe XML element to write.
textthe text to put
Note
Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.
def libsbml.XMLOutputStream.getLibraryName ( )
getLibraryName()   string
 
Returns
the name of the library to be used in comments ('libSBML' by default).
def libsbml.XMLOutputStream.getLibraryVersion ( )
getLibraryVersion()   string
 
Returns
a string representing the version of the library writing the output. This is the value of getLibSBMLDottedVersion() by default.
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.getWriteComment ( )
getWriteComment()   bool
 
Returns
a boolean, whether the output stream will write an XML comment at the top of the file. (Enabled by default.)
def libsbml.XMLOutputStream.getWriteTimestamp ( )
getWriteTimestamp()   bool
 
Returns
a boolean, whether the output stream will write an XML comment with a timestamp at the top of the file. (Enabled by default.)
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.setLibraryName (   libraryName)

sets the name of the library writing the XML

Parameters
libraryNamethe name of the library to be used in comments.
setLibraryName(string libraryName)
 
def libsbml.XMLOutputStream.setLibraryVersion (   libraryVersion)

sets the name of the library writing the output

Parameters
libraryVersionthe version information as string.
setLibraryVersion(string libraryVersion)
 
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.setWriteComment (   writeComment)
setWriteComment(bool writeComment)
sets a flag, whether the output stream will write an XML
comment at the top of the file. (Enabled by default.)
Parameters
writeCommentthe flag.
def libsbml.XMLOutputStream.setWriteTimestamp (   writeTimestamp)
setWriteTimestamp(bool writeTimestamp)
sets a flag, whether the output stream will write an XML
comment with a timestamp at the top of the file. (Enabled by default.)
Parameters
writeTimestampthe flag.
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(XMLTriple triple)

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

Parameters
triplethe start element to write.

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.)
Note
Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.
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(XMLTriple triple)

Writes the given start element to this output stream.

Parameters
triplethe XML element to write.

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.)
Note
Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.
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, long  value)
writeAttribute(string name, string prefix, long  value)
writeAttribute(XMLTriple triple, long  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, bool  value)
writeAttribute(string name, string prefix, bool  value)
writeAttribute(XMLTriple triple, bool  value)
writeAttribute(string name, bool  value)
writeAttribute(string name, string prefix, bool  value)
writeAttribute(XMLTriple triple, bool  value)
writeAttribute(string name, string prefix, unsigned bool  value)

Each variant is described separately below.


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, 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, 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(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(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, 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(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(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 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, 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 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(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, 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, 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, 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, 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, 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, string prefix, 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.
def libsbml.XMLOutputStream.writeComment (   self,
  programName,
  programVersion,
  writeTimestamp = True 
)

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

writeComment(string programName, string programVersion, bool writeTimestamp)
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.
writeTimestampan optional flag indicating that a timestamp should be written.
Note
Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.
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.