pygcam.xml_edit

The setup sub-command reads instructions from a scenarios.xml file or runs a Python script to create the XML input files necessary to run a project’s scenarios. See GCAM XML-Setup for more information.

API

pygcam.xml_edit.expandYearRanges(seq)

Expand a sequence of (year, value) tuples, or a dict keyed by year, where the year argument may be a string containing identifying range of values with an optional “step” value indicated after a “:”. The default step is 5 years. For example, “2015-2030” expands to (2015, 2020, 2025, 2030), and “2015-2020:1” expands to (2015, 2016, 2017, 2018, 2019, 2020). When a range is given, the tuple is replaced with a sequence of tuples naming each year explicitly. Typical usage is for year, price in expandYearRanges(values): ....

Parameters

seq – (tuple, list, dict) The sequence of (year, value) tuples, or any object with an items() method that returns (year, value) pairs.

Returns

A list of tuples with the expanded sequence.

pygcam.xml_edit.xmlEdit(obj, pairs, op='set', useCache=True)

Edit the XML file filename in place, applying the values to the given xpaths in the list of pairs.

Parameters

  • obj – (CachedFile, GcamPath, or str) the file to edit

  • pairs – (iterable of (xpath, value) pairs) In each pair, the xpath selects elements or attributes to update with the given values.

  • op – (str) Operation to perform. Must be in (‘set’, ‘multiply’, ‘add’). Note that ‘multiply’ and ‘add’ are not available for xpaths selecting attributes rather than node values. For ‘multiply’ and ‘add’, the value should be passed as a float. For ‘set’, it can be a float or a string.

  • useCache – (bool) if True, the etree is sought first in the XmlCache. This avoids repeated parsing, but the file is always written (eventually) if updated by this function.

Returns

True on success, else False

pygcam.xml_edit.xmlIns(obj, xpath, elt)

Insert the element elt as a child to the node found with xpath.

Parameters

  • obj – (CachedFile, GcamPath, or str) the file to edit

  • xpath – (str) the xml element(s) to search for

  • elt – (etree.Element) the node to insert

Returns

none

pygcam.xml_edit.xmlSel(obj, xpath, asText=False)

Return True if the XML component identified by the xpath argument exists in filename. Useful for deciding whether to edit or insert an XML element.

Parameters

  • obj – (CachedFile, GcamPath, or str) the file to edit

  • xpath – (str) the xml element(s) to search for

  • asText – (str) if True, return the text of the node, if found, else None

Returns

(bool) True if found, False otherwise. (see asText)