pygcam.config

See the configuration system page for a detailed description of available configuration variables. This page documents the API to the configuration system.

API

pygcam.config.getConfig(reload=False, allowMissing=False)

Return the configuration object. If one has been created already via readConfigFiles, it is returned; otherwise a new one is created and the configuration files are read. Applications generally do not need to use this object directly since the single instance is stored internally and referenced by the other API functions.

Param

reload (bool) if True, instantiate a new global ConfigParser.

Param

allowMissing (bool) if True, a missing config file is not treated as an error. This is used only when generating documentation, e.g., on readthedocs.org.

Returns

a ConfigParser instance.

pygcam.config.getConfigDict(section='DEFAULT', raw=False)

Return all variables defined in section as a dictionary.

Parameters

  • section – (str) the name of a section in the config file

  • raw – (bool) whether to return raw or interpolated values.

Returns

(dict) all variables defined in the section (which includes those defined in DEFAULT.)

pygcam.config.getParam(name, section=None, raw=False, raiseError=True)

Get the value of the configuration parameter name. Calls getConfig() if needed.

Parameters

  • name – (str) the name of a configuration parameters. Note that variable names are case-insensitive. Note that environment variables are available using the ‘$’ prefix as in a shell. To access the value of environment variable FOO, use getParam(‘$FOO’).

  • section – (str) the name of the section to read from, which defaults to the value used in the first call to getConfig, readConfigFiles, or any of the getParam variants.

Returns

(str) the value of the variable, or None if the variable doesn’t exist and raiseError is False.

Raises

NoOptionError – if the variable is not found in the given section and raiseError is True

pygcam.config.getParamAsBoolean(name, section=None)

Get the value of the configuration parameter name, coerced into a boolean value, where any (case-insensitive) value in the set {'true','yes','on','1'} are converted to True, and any value in the set {'false','no','off','0'} is converted to False. Any other value raises an exception. Calls getConfig() if needed.

Parameters

  • name – (str) the name of a configuration parameters.

  • section – (str) the name of the section to read from, which defaults to the value used in the first call to getConfig, readConfigFiles, or any of the getParam variants.

Returns

(bool) the value of the variable

Raises

pygcam.error.ConfigFileError

pygcam.config.getParamAsFloat(name, section=None)

Get the value of the configuration parameter name as a float. Calls getConfig() if needed.

Parameters

  • name – (str) the name of a configuration parameters.

  • section – (str) the name of the section to read from, which defaults to the value used in the first call to getConfig, readConfigFiles, or any of the getParam variants.

Returns

(float) the value of the variable

pygcam.config.getParamAsInt(name, section=None)

Get the value of the configuration parameter name, coerced to an integer. Calls getConfig() if needed.

Parameters

  • name – (str) the name of a configuration parameters.

  • section – (str) the name of the section to read from, which defaults to the value used in the first call to getConfig, readConfigFiles, or any of the getParam variants.

Returns

(int) the value of the variable

pygcam.config.getParamAsPath(name, section=None)

Get the value of the configuration parameter name as a UNIX path. Calls getConfig() if needed.

Parameters

  • name – (str) the name of a configuration parameters.

  • section – (str) the name of the section to read from, which defaults to the value used in the first call to getConfig, readConfigFiles, or any of the getParam variants.

Returns

(str) the path

pygcam.config.mkdirs(newdir, mode=504)

Try to create the full path newdir and ignore the error if it already exists.

Parameters

newdir – the directory to create (along with any needed parent directories)

Returns

nothing

pygcam.config.readConfigFiles(allowMissing=False)

Read the pygcam configuration files, starting with pygcam/etc/system.cfg, followed by pygcam/etc/{platform}.cfg if present. If the environment variable PYGCAM_SITE_CONFIG is defined, its value should be a config file, which is read next. Finally, the user’s config file, ~/.pygcam.cfg, is read. Each successive file overrides values for any variable defined in an earlier file.

Returns

a populated ConfigParser instance

pygcam.config.savePathMap(mapString)

Save a list of pathname translations (sorted, descending by length) for use with docker, mapping host directories to container-mounted directories. The function getParam() performs the translations.

Parameters

mapString – (str) sequence of newline-limited lines, each containing a pair of the form “host-path:container-path”.

Returns

nothing

pygcam.config.setInputFilesByVersion()

Set “GCAM.InputFiles” to the correct version-specific config parameter. First check for “GCAM.InputFiles.” plus major.minor.patch version, then just major.minor, and finally, just the major version number. For example, if “GCAM.VersionNumber” is “5.1.2”, and “GCAM.InputFiles.5.1.2” is not defined, but “GCAM.InputFiles.5.1” is, we set “GCAM.InputFiles” to the value of parameter “GCAM.InputFiles.5.1”.

pygcam.config.setMacJavaVars()

Set the environment vars java uses to locate libraries. If var is already set, don’t override it. Must be called after config info has been read since it references GCAM.RefWorkspace.

pygcam.config.setParam(name, value, section=None)

Set a configuration parameter in memory.

Parameters

  • name – (str) parameter name

  • value – (any, coerced to str) parameter value

  • section – (str) if given, the name of the section in which to set the value. If not given, the value is set in the established project section, or DEFAULT if no project section has been set.

Returns

value

pygcam.config.setSection(section)

Set the name of the default config file section to read from.

Parameters

section – (str) a config file section name.

Returns

none

pygcam.config.unixPath(path, rmFinalSlash=False, abspath=False, normpath=False)

Convert a path to use Unix-style slashes, optionally removing the final slash, if present.

Parameters

  • path – (str) a pathname

  • rmFinalSlash – (bool) True if a final slash should be removed, if present.

Returns

(str) the modified pathname

pygcam.config.usingMCS()

Check if the user environment is configured to use pygcam.mcs, which requires that the file ~/.use_pygcam_mcs exists. This lets gcamtool know whether to load the corresponding built-in sub-commands.

Returns

(bool) True if user environment indicates to use pygcam-mcs.

pygcam.config.writeSystemDefaultsFile(systemDefaults)

If the system defaults file (~/pygcam.defaults) doesn’t exist, write the system defaults to the file. Otherwise, just return.