ParameterList

The ParameterList class is augmented to behave somewhat like a python dictionary. Here are the following differences between the C++ and python implementations:

• Ignored methods: begin(), end(), entry(), getEntryPtr(), getPtr(), isType(), name(ConstIterator) and setEntry().

• Dictionary constructors. A ParameterList can be constructed using a dictionary:

  plist = Teuchos.ParameterList(dict[,string])
  

  where dict is a dictionary whose keys are all strings and whose values are of types supported in the above table. The string name argument is optional and defaults to "ANONYMOUS".

• Set methods. The templated C++ set() method is replaced in python with a method that takes a string name and a python object of supported type. For example:

  plist = Teuchos.ParameterList()
  plist.set("b",True)
  plist.set("i",10)
  plist.set("f",2.718)
  plist.set("s","Trilinos")
  plist.set("d",{"a":1, "b":2})
  

• Get methods. The templated C++ get() method is replaced in python with a method that returns a python object. From the previous example:

  print plist.get("f")
  print plist.get("d")
  

  will output:

  2.718
  {'a': 1, 'b': 2}
  

• The setParameters() method can take either a ParameterList or a python dictionary as its argument. The ParameterList is updated to contain all of the entries of the argument.

• Printing. Since print is a python keyword, the print() C++ method has been renamed _print in python. It takes an optional file argument that defaults to standard output. Its output is the same as the C++ implementation.

  The __str__() method returns a string representation of the ParameterList as though it were a python dictionary. The python eval function applied to the output of __str__() will produce an equivalent dictionary.

  The __repr__() method returns the __str__() output encapsulated by ParameterList(...). The python eval function applied to the output of __repr__() will produce an equivalent ParameterList.

• The unused() method in python takes an optional python file object as its argument, defaulting to standard output.

• Parameter type determination. With the templated isType() methods disabled, type determination of python ParameterList entries is accomplished with the type() method, which returns python type objects. From our previous example:

  print plist.type("b")
  print plist.type("s")
  

  results in:

  <type 'bool'>
  <type 'str'>
  

  A non-existent key given as the argument will raise a KeyError exception.

• An asDict() method has been added that returns the contents of the ParameterList converted to a python dictionary.

The following python dictionary methods and operators are added to the python implementation of the ParameterList class:

• Comparison. The == and != comparison operators work for ParameterList objects. Comparison against other ParameterList objects, as well as python dictionaries, is supported. Less-than and greater-than operators also work, mimicking the default dictionary behavior, but are less useful.

• The in operator also works, searching the parameter names:

  print "a" in plist
  print "b" in plist
  

  produces:

  False
  True
  

• Length method. The python len() function works on ParameterLists:

  print len(plist)
  

  gives:

  5
  

• Iteration. To iterate over the parameters in a ParameterList, treat it like a dictionary:

  for key in plist:
    print key, ":", plist[key]
  

  will result in the output:

  b : True
  d : {'a': 1, 'b': 2}
  f : 2.718
  i : 10
  s : Trilinos
  

  Note that the order of the parameters is somewhat indeterminant, as with dictionaries, because the iteration object is obtained from an equivalent dictionary, and dictionaries are ordered by hash function.

• Index notation. Like dictionaries, parameters can be set and gotten using square brackets:

  plist["zero"] = 0
  e = plist["f"]
  

• Update methods. An update() method has been added that can accept either a ParameterList or a python dictionary. Otherwise, it behaves just as the dictionary method, which is functionally equivalent to the setParameters() method.

• Other new methods for the python implementation that behave just as with dictionaries: has_key(), items(), iteritems(), iterkeys(), itervalues(), keys() and values().

Note that the C++ implementation of the ParameterList class does not support parameter deletion. Therefore, python dictionary methods that delete items, such as pop() or __delitem__(), have not been added to the ParameterList class.

XML Support

PyTrilinos.Teuchos supports several classes related to XML. They are:

• XMLObject - The python implementation of this class is largely unchanged from the C++ interface, with the following exceptions:
  • The constructor that takes an XMLObjectImplem* argument has been removed. The XMLObjectImplem class is hidden from the python user.
  • A __str__() method has been added, so that it is possible to print an XMLObject object. It returns the same string as the toString() method, but if toString() raises an exception (such as when the XMLObject is empty), the __str__() method returns the empty string.
• XMLParameterListWriter - This simple class has been implemented unchanged from its C++ interface. Its purpose is to convert ParameterList objects into XMLObject objects.
• XMLParameterListReader - This simple class has been implemented unchanged from its C++ interface. Its purpose is to convert XMLObject objects into ParameterList objects.
• XMLInputSource - This is a base class from which FileInputSource and StringInputSource derive. The source() method is ignored.
• FileInputSource - This is a class for reading an XML object from a file. The source() method is ignored.
• StringInputSource - This is a class for reading an XML object from a string. The source() method is ignored.