pygcam.utils

This module contains constants, functions, and classes that are used by various other modules of the pygcam toolkit.

API

class pygcam.utils.ParseCommaList(option_strings, dest, nargs=None, **kwargs)
pygcam.utils.coercible(value, type, raiseError=True)

Attempt to coerce a value to type and raise an error on failure.

Parameters

  • value – any value coercible to type

  • type – any Python type

Returns

(type) the coerced value, if it’s coercible, otherwise None if raiseError is False

Raises

PygcamException – if not coercible and raiseError is True

pygcam.utils.copyResource(relpath, dest, overwrite=True)

Copy a resource from the ‘pygcam’ package to the given destination.

Parameters

  • relpath – (str) a path relative to the pygcam package

  • dest – (str) the pathname of the file to create by copying the resource.

  • overwrite – (bool) if False, raise an error if the destination file already exists.

Returns

none

pygcam.utils.digitColumns(df, asInt=False)

Get a list of columns with integer names (as strings, e.g., “2007”) in df. If asInt is True return as a list of integers, otherwise as strings.

pygcam.utils.flatten(listOfLists)

Flatten one level of nesting given a list of lists. That is, convert [[1, 2, 3], [4, 5, 6]] to [1, 2, 3, 4, 5, 6].

Parameters

listOfLists – a list of lists, obviously

Returns

the flattened list

pygcam.utils.getBooleanXML(value)

Get a value from an XML file and convert it into a boolean True or False.

Parameters

value – any value (it’s first converted to a string)

Returns

True if the value is in [‘true’, ‘yes’, ‘1’], False if the value is in [‘false’, ‘no’, ‘0’]. An exception is raised if any other value is passed.

Raises

PygcamException

pygcam.utils.getRegionList(workspace=None, states='withGlobal')

Set the list of the defined region names from the data system, if possible, otherwise use the built-in list of 32 regions. If config variable “GCAM.RegionDiscovery” is True (the default) then the reference configuration file is consulted L file is read to see whether the tag “socioeconomics” or “socio_usa” is defined, and the XML file indicated there is parsed to extract region names. If “GCAM.RegionDiscovery” is False, the built-in list of 32 regions is used.

Parameters

  • workspace – (str) The workspace to use as the base for interpreting relative pathnames in the reference configuration file. If workspace is None, the value of config variable “GCAM.RefWorkspace” is used.

  • states – (str) One of {‘together’, ‘only’, ‘none’}. Default is ‘together’. Defines which regions to return: “together” means combine states and global regions (but drop USA from list of states); “only” means return only the states; “none” means return only the global regions (no states).

Returns

a list of strings with the names of the defined regions

pygcam.utils.getResource(relpath)

Extract a resource (e.g., file) from the given relative path in the pygcam package.

Parameters

relpath – (str) a path relative to the pygcam package

Returns

the file contents

pygcam.utils.getYearCols(years, timestep=5)

Generate a list of names of year columns in GCAM result files from a string indicating a year range.

Parameters

  • years – (str) a string of the form “2020-2050”

  • timestep – (int) the number of years between timesteps

Returns

(list of strings) the names of the corresponding columns

pygcam.utils.importFrom(modname, objname, asTuple=False)

Import modname and return reference to objname within the module.

Parameters

  • modname – (str) the name of a Python module

  • objname – (str) the name of an object in module modname

  • asTuple – (bool) if True a tuple is returned, otherwise just the object

Returns

(object or (module, object)) depending on asTuple

pygcam.utils.importFromDotSpec(spec)

Import an object from an arbitrary dotted sequence of packages, e.g., “a.b.c.x” by splitting this into “a.b.c” and “x” and calling importFrom().

Parameters

spec – (str) a specification of the form package.module.object

Returns

none

Raises

PygcamException – if the import fails

pygcam.utils.loadModuleFromPath(modulePath, raiseOnError=True)

Load a module from a ‘.py’ or ‘.pyc’ file from a path that ends in the module name, i.e., from “foo/bar/Baz.py”, the module name is ‘Baz’.

Parameters

  • modulePath – (str) the pathname of a python module (.py or .pyc)

  • raiseOnError – (bool) if True, raise an error if the module cannot be loaded

Returns

(module) a reference to the loaded module, if loaded, else None.

Raises

PygcamException

pygcam.utils.printSeries(series, label, header='', asStr=False)

Print a series of values, with a give label.

Parameters

  • series – (convertible to pandas Series) the values

  • label – (str) a label to print for the data

Returns

none

pygcam.utils.queueForStream(stream)

Create a thread to read from a non-socket file descriptor and its contents to a socket so non-blocking read via select() works on Windows. (Since Windows doesn’t support select on pipes.)

Parameters

stream – (file object) the input to read from, presumably a pipe from a subprocess

Returns

(int) a file descriptor for the socket to read from.

pygcam.utils.random_sleep(low_secs, high_secs)

Sleep a random number of seconds between low_secs and high_secs

Parameters

  • low_secs – (float) the minimum number of seconds to sleep

  • high_secs – (float) the maximum number of seconds to sleep

Returns

none

pygcam.utils.resourceStream(relpath)

Return a stream on the resource found on the given path relative to the pygcam package.

Parameters

relpath – (str) a path relative to the pygcam package

Returns

(file-like stream) a file-like buffer opened on the desired resource.

pygcam.utils.shellCommand(command, shell=True, raiseError=True)

Run a shell command and optionally raise PygcamException error.

Parameters

  • command – (str or list of str) the command to run, with arguments.

  • shell – if True, run command in a shell, otherwise run it directly.

  • raiseError – if True, raise PygcamException on command failure.

Returns

exit status of executed command

Raises

PygcamException

pygcam.utils.simpleFormat(s, varDict)

Simple version of str.format that does not treat ‘.’ as an attribute reference.

Parameters

  • s – (str) string with args in curly braces

  • varDict – (dict) dictionary of var names and values

Returns

(str) formatted string

pygcam.utils.writeXmldbDriverProperties(outputDir='.', inMemory=True, filterFile='', batchFile='', batchLog='')

Write a XMLDBDriver.properties file using the values passed in the arguments.

Parameters

  • outputDir – (str) where to write the file

  • inMemory – (bool) if True, the in-memory attribute is set to True

  • filterFile – (str) a file that filters GCAM query output to limit what’s written to the database

  • batchFile – (str) the path to an XML batch query file

  • batchLog – (str) the path to a log file into which to direct batch query messages (queries can be pretty verbose…)

Returns

none