Inheritance diagram for libsbml.XMLAttributes:

Detailed Description

A list of attributes on an XML element.

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.

In libSBML's XML interface layer, attributes on an element are stored as a list of values kept in an XMLAttributes object. XMLAttributes has methods for adding and removing individual attributes as well as performing other actions on the list of attributes. Classes in libSBML that represent nodes in an XML document (i.e., XMLNode and its parent class, XMLToken) use XMLAttributes objects to manage attributes on XML elements.

Attributes on an XML element can be written in one of two forms:

name='value'
prefix:name='value'

An attribute in XML must always have a value, and the value must always be a quoted string; i.e., it is always name='value' and not name=value. An empty value is represented simply as an empty string; i.e., name=''.

In cases when a prefix is provided with an attribute name, general XML validity rules require that the prefix is an XML namespace prefix that has been declared somewhere else (possibly as an another attribute on the same element). However, the XMLAttributes class does not test for the proper existence or declaration of XML namespaces—callers must arrange to do this themselves in some other way. This class only provides facilities for tracking and manipulating attributes and their prefix/URI/name/value components.

Note: Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: XMLTriple; XMLNode; XMLToken

Public Member Functions
def	__init__ (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	add (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	clear (self)
	Removes all attributes in this XMLAttributes object. More...

def	clone (self)
	Creates and returns a deep copy of this XMLAttributes object. More...

def	getIndex (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	getLength (self)
	Returns the number of attributes in this list of attributes. More...

def	getName (self, index)
	Returns the name of the nth attribute in this list of attributes. More...

def	getNumAttributes (self)
	Returns the number of attributes in this list of attributes. More...

def	getPrefix (self, index)
	Returns the namespace prefix of the nth attribute in this attribute set. More...

def	getPrefixedName (self, index)
	Returns the prefix name of the nth attribute in this attribute set. More...

def	getURI (self, index)
	Returns the XML namespace URI of the nth attribute in this attribute set. More...

def	getValue (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	hasAttribute (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	isEmpty (self)
	Returns `True` if this list of attributes is empty. More...

def	remove (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

Constructor & Destructor Documentation

def libsbml.XMLAttributes.__init__	(	self,
		args
	)

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

__init__()   XMLAttributes
__init__(XMLAttributes orig)   XMLAttributes

Each variant is described separately below.

Method variant with the following signature:

XMLAttributes()

Creates a new, empty XMLAttributes object.

Method variant with the following signature:

XMLAttributes(XMLAttributes orig)

Copy constructor; creates a copy of this XMLAttributes object.

orig the XMLAttributes object to copy.

Member Function Documentation

def libsbml.XMLAttributes.add	(	self,
		args
	)

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

add(string name, string value, string namespaceURI, string prefix)   int
add(string name, string value, string namespaceURI)   int
add(string name, string value)   int
add(XMLTriple triple, string value)   int

Each variant is described separately below.

Method variant with the following signature:

add(string name, string value, string namespaceURI = '', string prefix = '')

Adds an attribute to this list of attributes.

: Some explanations are in order about the behavior of XMLAttributes with respect to namespace prefixes and namespace URIs. XMLAttributes does not verify the consistency of different uses of an XML namespace and the prefix used to refer to it in a given context. It cannot, because the prefix used for a given XML namespace in an XML document may intentionally be different on different elements in the document. Consequently, callers need to manage their own prefix-to-namespace mappings, and need to ensure that the desired prefix is used in any given context.

When called with attribute names, prefixes and namespace URIs, XMLAttributes pays attention to the namespace URIs and not the prefixes: a match is established by a combination of attribute name and namespace URI, and if on different occasions a different prefix is used for the same name/namespace combination, the prefix associated with the namespace on that attribute is overwritten.

Some examples will hopefully clarify this. Here are the results of a sequence of calls to the XMLAttributes add methods with different argument combinations. First, we create the object and add one attribute:

XMLAttributes att = new XMLAttributes();

att->add('myattribute', '1', 'myuri');

The above adds an attribute named myattribute in the namespace myuri, and with the attribute value 1. No namespace prefix is associated with the attribute (but the attribute is recorded to exist in the namespace myuri). If this attribute object were written out in XML, it would look like the following (and note that, since no namespace prefix was assigned, none is written out):

myattribute='1'

Continuing with this series of examples, suppose we invoke the add method again as follows:

att->add('myattribute', '2');

The above adds a new attribute also named myattribute, but in a different XML namespace: it is placed in the namespace with no URI, which is to say, the default XML namespace. Both attributes coexist on this XMLAttributes object; both can be independently retrieved.

att->add('myattribute', '3');

The code above now replaces the value of the attribute myattribute that resides in the default namespace. The attribute in the namespace myuri remains untouched.

att->add('myattribute', '4', 'myuri');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. The attribute in the default namespace remains untouched.

att->add('myattribute', '5', 'myuri', 'foo');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also now assigns a namespace prefix, foo, to the attribute. The attribute myattribute in the default namespace remains untouched. If this XMLAttributes object were written out in XML, it would look like the following:

myattribute='3'
foo:myattribute='5'

Pressing on, now suppose we call the add method as follows:

att->add('myattribute', '6', 'myuri', 'bar');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also assigns a different prefix to the attribute. The namespace of the attribute remains myuri.

att->add('myattribute', '7', '', 'foo');

The code above replaces the value of the attribute myattribute that resides in the default namespace. It also now assigns a namespace prefix, foo, to that attribute. If this XMLAttributes object were written out in XML, it would look like the following:

bar:myattribute='6'
foo:myattribute='7'

Parameters

name	a string, the unprefixed name of the attribute.
value	a string, the value of the attribute.
namespaceURI	a string, the namespace URI of the attribute.
prefix	a string, a prefix for the XML namespace.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_OBJECT – this value is returned if any of the arguments are None. To set an empty prefix and/or name value, use an empty string rather than None.

Note: If an attribute with the same name and XML namespace URI already exists in the list of attributes held by this XMLAttributes object, then the previous value of that attribute will be replaced with the new value provided to this method.

See also: add(); getIndex(); getIndex(); hasAttribute(); hasAttribute()

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:

add(XMLTriple triple, string value)

Adds an attribute to this list of attributes.

: Some explanations are in order about the behavior of XMLAttributes with respect to namespace prefixes and namespace URIs. XMLAttributes does not verify the consistency of different uses of an XML namespace and the prefix used to refer to it in a given context. It cannot, because the prefix used for a given XML namespace in an XML document may intentionally be different on different elements in the document. Consequently, callers need to manage their own prefix-to-namespace mappings, and need to ensure that the desired prefix is used in any given context.

When called with attribute names, prefixes and namespace URIs, XMLAttributes pays attention to the namespace URIs and not the prefixes: a match is established by a combination of attribute name and namespace URI, and if on different occasions a different prefix is used for the same name/namespace combination, the prefix associated with the namespace on that attribute is overwritten.

Some examples will hopefully clarify this. Here are the results of a sequence of calls to the XMLAttributes add methods with different argument combinations. First, we create the object and add one attribute:

XMLAttributes att = new XMLAttributes();

att->add('myattribute', '1', 'myuri');

The above adds an attribute named myattribute in the namespace myuri, and with the attribute value 1. No namespace prefix is associated with the attribute (but the attribute is recorded to exist in the namespace myuri). If this attribute object were written out in XML, it would look like the following (and note that, since no namespace prefix was assigned, none is written out):

myattribute='1'

Continuing with this series of examples, suppose we invoke the add method again as follows:

att->add('myattribute', '2');

The above adds a new attribute also named myattribute, but in a different XML namespace: it is placed in the namespace with no URI, which is to say, the default XML namespace. Both attributes coexist on this XMLAttributes object; both can be independently retrieved.

att->add('myattribute', '3');

The code above now replaces the value of the attribute myattribute that resides in the default namespace. The attribute in the namespace myuri remains untouched.

att->add('myattribute', '4', 'myuri');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. The attribute in the default namespace remains untouched.

att->add('myattribute', '5', 'myuri', 'foo');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also now assigns a namespace prefix, foo, to the attribute. The attribute myattribute in the default namespace remains untouched. If this XMLAttributes object were written out in XML, it would look like the following:

myattribute='3'
foo:myattribute='5'

Pressing on, now suppose we call the add method as follows:

att->add('myattribute', '6', 'myuri', 'bar');

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also assigns a different prefix to the attribute. The namespace of the attribute remains myuri.

att->add('myattribute', '7', '', 'foo');

The code above replaces the value of the attribute myattribute that resides in the default namespace. It also now assigns a namespace prefix, foo, to that attribute. If this XMLAttributes object were written out in XML, it would look like the following:

bar:myattribute='6'
foo:myattribute='7'

Parameters

triple	an XMLTriple object describing the attribute to be added.
value	a string, the value of the attribute.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_OBJECT – this value is returned if any of the arguments are None. To set an empty value for the attribute, use an empty string rather than None.

Note: If an attribute with the same name and XML namespace URI already exists in the list of attributes held by this XMLAttributes object, then the previous value of that attribute will be replaced with the new value provided to this method.

See also: add(); getIndex(); getIndex(); hasAttribute(); hasAttribute()

def libsbml.XMLAttributes.clear ( self )

Removes all attributes in this XMLAttributes object.

clear()   int

Returns

integer value indicating success/failure of the function. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_SUCCESS

See also: remove(); remove(); remove()

def libsbml.XMLAttributes.clone ( self )

Creates and returns a deep copy of this XMLAttributes object.

clone()   XMLAttributes

Returns: the (deep) copy of this XMLAttributes object.

def libsbml.XMLAttributes.getIndex	(	self,
		args
	)

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

getIndex(string name)   int
getIndex(string name, string uri)   int
getIndex(XMLTriple triple)   int

Each variant is described separately below.

Method variant with the following signature:

getIndex(XMLTriple triple)

Returns the index of the attribute defined by the given XMLTriple object.

Parameters

triple an XMLTriple describing the attribute being sought.

Returns: the index of an attribute described by the given XMLTriple object, or -1 if no such attribute is present.

See also: hasAttribute(); hasAttribute()

Method variant with the following signature:

getIndex(string name, string uri)

Returns the index of the attribute having a given name and XML namespace URI.

Parameters

name	a string, the name of the attribute being sought.
uri	a string, the namespace URI of the attribute being sought.

Returns: the index of an attribute with the given local name and namespace URI, or -1 if no such attribute is present.

See also: hasAttribute(); hasAttribute()

Method variant with the following signature:

getIndex(string name)

Returns the index of an attribute having a given name.

Note: This method does not check XML namespaces. Thus, if there are multiple attributes with the same local name but different namespaces, this method will return the first one found. Callers should use the more specific methods XMLAttributes.getIndex() or XMLAttributes.getIndex() to find attributes in particular namespaces.

Parameters

name	a string, the name of the attribute whose index is begin sought.

Returns: the index of an attribute with the given local name, or -1 if no such attribute is present.

See also: hasAttribute(); hasAttribute()

def libsbml.XMLAttributes.getLength ( self )

Returns the number of attributes in this list of attributes.

getLength()   int

Returns: the number of attributes contained in this XMLAttributes object.

def libsbml.XMLAttributes.getName	(	self,
		index
	)

Returns the name of the nth attribute in this list of attributes.

getName(int index)   string

Parameters

index an integer, the position of the attribute whose name is being sought.

Returns: the local name of the nth attribute.

Note: If index is out of range, this method will return an empty string. Callers should use XMLAttributes.getLength() to check the number of attributes contained in this object or XMLAttributes.hasAttribute() to test for the existence of an attribute at a given position.; Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); hasAttribute()

def libsbml.XMLAttributes.getNumAttributes ( self )

Returns the number of attributes in this list of attributes.

getNumAttributes()   int

This function is merely an alias of XMLAttributes.getLength() introduced for consistency with other libXML classes.

Returns: the number of attributes contained in this XMLAttributes object.

def libsbml.XMLAttributes.getPrefix	(	self,
		index
	)

Returns the namespace prefix of the nth attribute in this attribute set.

getPrefix(int index)   string

Parameters

index an integer, the position of the attribute whose namespace prefix is being sought.

Returns: the XML namespace prefix of the nth attribute.

Note: If index is out of range, this method will return an empty string. Callers should use XMLAttributes.getLength() to check the number of attributes contained in this object or XMLAttributes.hasAttribute() to test for the existence of an attribute at a given position.; Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); hasAttribute()

def libsbml.XMLAttributes.getPrefixedName	(	self,
		index
	)

Returns the prefix name of the nth attribute in this attribute set.

getPrefixedName(int index)   string

Parameters

index an integer, the position of the attribute whose prefixed name is being sought.

Returns: the prefixed name of the nth attribute.

Note: If index is out of range, this method will return an empty string. Callers should use XMLAttributes.getLength() to check the number of attributes contained in this object or XMLAttributes.hasAttribute() to test for the existence of an attribute at a given position.; Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); hasAttribute()

def libsbml.XMLAttributes.getURI	(	self,
		index
	)

Returns the XML namespace URI of the nth attribute in this attribute set.

getURI(int index)   string

Parameters

index an integer, the position of the attribute whose namespace URI is being sought.

Returns: the XML namespace URI of the nth attribute.

Note: If index is out of range, this method will return an empty string. Callers should use XMLAttributes.getLength() to check the number of attributes contained in this object or XMLAttributes.hasAttribute() to test for the existence of an attribute at a given position.; Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); hasAttribute()

def libsbml.XMLAttributes.getValue	(	self,
		args
	)

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

getValue(int index)   string
getValue(string name)   string
getValue(string name, string uri)   string
getValue(XMLTriple triple)   string

Each variant is described separately below.

Method variant with the following signature:

getValue(XMLTriple triple)

Return the value of an attribute described by a given XMLTriple object.

Parameters

triple an XMLTriple describing the attribute whose value is being sought.

Returns: The attribute value as a string.

Note: If an attribute with the properties given by triple does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes.hasAttribute() to test for an attribute's existence.

See also: hasAttribute(); hasAttribute()

Method variant with the following signature:

getValue(int index)

Returns the value of the nth attribute in this list of attributes.

Parameters

index an integer, the position of the attribute whose value is being sought.

Returns: the XML value of the nth attribute.

Note: If index is out of range, this method will return an empty string. Callers should use XMLAttributes.getLength() to check the number of attributes contained in this object or XMLAttributes.hasAttribute() to test for the existence of an attribute at a given position.; Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); hasAttribute()

Method variant with the following signature:

getValue(string name)

Returns a named attribute's value.

Parameters

name	a string, the unprefixed name of the attribute whose value is being sought.

Returns: The attribute value as a string.

Note: If an attribute with the given local name does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes.hasAttribute() to test for an attribute's existence. This method also does not check the XML namespace of the named attribute. Thus, if there are multiple attributes with the same local name but different namespaces, this method will return the value of the first such attribute found. Callers should use the more specific methods XMLAttributes.getIndex() or XMLAttributes.getIndex() to find attributes in particular namespaces.

See also: hasAttribute(); hasAttribute()

Method variant with the following signature:

getValue(string name, string uri)

Returns a named attribute's value.

Parameters

name	a string, the name of the attribute whose value is being sought.
uri	a string, the XML namespace URI of the attribute.

Returns: The attribute value as a string.

Note: If an attribute with the given name and namespace uri does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes.hasAttribute() to test for an attribute's existence.

See also: hasAttribute(); hasAttribute()

def libsbml.XMLAttributes.hasAttribute	(	self,
		args
	)

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

hasAttribute(int index)   bool
hasAttribute(string name, string uri)   bool
hasAttribute(string name)   bool
hasAttribute(XMLTriple triple)   bool

Each variant is described separately below.

Method variant with the following signature:

hasAttribute(string name, string uri='')

Returns True if an attribute with a given name and namespace URI exists.

Parameters

name	a string, the unprefixed name of the attribute.
uri	a string, the XML namespace URI of the attribute.

Returns: True if an attribute with the given local name and XML namespace URI exists in this XMLAttributes object, False otherwise.

See also: add(); add()

Method variant with the following signature:

hasAttribute(XMLTriple triple)

Returns True if an attribute with the given properties exists.

Parameters

triple an XMLTriple describing the attribute to be tested.

Returns: True if an attribute with the given XML triple exists in this XMLAttributes object, False otherwise.

See also: add(); add()

Method variant with the following signature:

hasAttribute(int index)

Returns True if an attribute exists at a given index.

Parameters

index an integer, the position of the attribute to be tested.

Returns: True if an attribute with the given index exists in this XMLAttributes object, False otherwise.

Note: Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

def libsbml.XMLAttributes.isEmpty ( self )

Returns True if this list of attributes is empty.

isEmpty()   bool

Returns: True if this XMLAttributes object is empty, False otherwise.

def libsbml.XMLAttributes.remove	(	self,
		args
	)

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

remove(int n)   int
remove(string name, string uri)   int
remove(string name)   int
remove(XMLTriple triple)   int

Each variant is described separately below.

Method variant with the following signature:

remove(string name, string uri = '')

Removes a named attribute from this list of attributes.

Parameters

name	a string, the unprefixed name of the attribute to be removed.
uri	a string, the namespace URI of the attribute to be removed.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute with the given name (and uri if specified).

See also: remove(); remove()

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:

remove(int n)

Removes the nth attribute from this list of attributes.

Parameters

n	an integer the index of the resource to be deleted.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute at the given index n.

Note: Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.

See also: getLength(); remove(); remove()

Method variant with the following signature:

remove(XMLTriple triple)

Removes a specific attribute from this list of attributes.

Parameters

triple an XMLTriple describing the attribute to be removed.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute matching the properties of the given triple.

See also: remove(); remove()

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation