armi.settings.settingsIO module

This module contains classes and methods for reading and writing Settings, and the contained Setting.

class armi.settings.settingsIO.Roots

Bases: object

XML tree root node common strings

CUSTOM = 'settings'

VERSION = 'version'

class armi.settings.settingsIO.SettingRenamer(settings: Dict[str, armi.settings.setting.Setting])

Bases: object

Utility class to help with setting rename migrations.

This class stores a cache of renaming maps, derived from the Setting.oldNames values of the passed settings. Expired renames are retained, so that meaningful warning messages can be generated if one attempts to use one of them. The renaming logic follows the rules described in renameSetting().

renameSetting(name) → Tuple[str, bool]

Attempt to rename a candidate setting.

Renaming follows these rules:

• If the name corresponds to a current setting name, do not attempt to rename it.

• If the name does not correspond to a current setting name, but is one of the active renames, return the corresponding active rename.

• If the name does not correspond to a current setting name, but is one of the expired renames, produce a warning and do not rename it.

Parameters

name (str) – The candidate setting name to potentially rename.

Returns

• name (str) – The potentially-renamed setting

• renamed (bool) – Whether the setting was actually renamed

class armi.settings.settingsIO.SettingsReader(cs)

Bases: object

Abstract class for processing settings files.

Parameters

cs (CaseSettings) – The settings object to read into

class SettingsInputFormat

Bases: enum.Enum

An enumeration.

XML = 1

YAML = 2

fromExt = <bound method SettingsReader.SettingsInputFormat.fromExt of <enum 'SettingsInputFormat'>>

property isXmlFormat

True if file read is in the old XML format.

readFromFile(path, handleInvalids=True)

Load file and read it.

readFromStream(stream, handleInvalids=True, fmt=<SettingsInputFormat.YAML: 2>)

Read from a file-like stream.

_readXml(stream)

Read user settings from XML stream.

_readYaml(stream)

Read settings from a YAML stream.

Notes

This is intended to replace the XML stuff as we converge on consistent input formats.

_checkInvalidSettings()

_interpretXmlSetting(settingElement)

_applySettings(name, val)

applyConversions(name, value)

Applies conversion rules to give special behavior to certain named settings.

Intended to be applied on setting names and attributes as soon as they’re read in keep in mind everything in the attributes dictionary is still a string even if it’s intended to be something else later, that happens at a later stage.

armi.settings.settingsIO.applyTypeConversions(settingObj, value)

Coerce value to proper type given a valid setting object.

Useful in converting XML settings with no type info (all string) as well as in GUI operations.

class armi.settings.settingsIO.SettingsWriter(settings_instance, style='short')

Bases: object

Writes settings out to files.

This can write in two styles:

short

setting values that are not their defaults only

full

all setting values regardless of default status

class Styles

Bases: object

Enumeration of valid output styles

short = 'short'

full = 'full'

static _getVersion()

writeXml(stream)

Write settings to XML file.

writeYaml(stream)

Write settings to YAML file.

_preprocessYaml(settingData)

Clean up the dict before dumping to yaml.

If it has just a value attrib it flattens it for brevity.

_getSettingDataToWrite()

Make an ordered dict with all settings slated for being written.

This is general so it can be dumped to whatever file format.

prettyPrintXmlRecursively(node, indentation=0, spacing=True)

Generates a pretty output string of an element tree better than the default .write()

Uses helper cleanQuotesFromString to get everything both python and xml readable

Parameters

• node (ET.Element) – the element tree element to write the output for

• indentation (int,) – not for manual use, but for the recursion to nicely nest parts of the string

• spacing (bool) – used to flip the newline behavior for spacing out an xml file or keeping it compact primarily for the difference between a default settings and a custom settings file.

cleanStringForXml(s)

Assures no XML entity issues will occur on parsing a string

A helper function used to make strings xml friendly XML has some reserved characters, this should handle them. apostrophes aren’t being dealt with but seem to behave nicely as is.

http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

armi.settings.settingsIO.prompt(statement, question, *options)

Prompt the user for some information.

exception armi.settings.settingsIO.RunLogPromptCancel

Bases: Exception

An error that occurs when the user submits a cancel on a runLog prompt which allows for cancellation

exception armi.settings.settingsIO.RunLogPromptUnresolvable

Bases: Exception

An error that occurs when the current mode enum in armi.__init__ suggests the user cannot be communicated with from the current process.