cape.cfdx.options.util: Utilities for options modules

This module provides utilities for the CAPE options module. It includes the cape.options.util.odict class upon which all CAPE options classes are based, and it several basic methods useful to processing options.

The getel() and setel() methods in particular play an important role in the entire CAPE coding strategy.

class cape.cfdx.options.util.odict

Dictionary-based options module

Call:
>>> opts = odict(**kw)
Inputs:
kw: dict

Dictionary of options

Outputs:
opts: cape.options.util.odict

Dictionary-based options interface

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: More robust get_key() using rck

copy()

Create a copy of an options interface

Call:
>>> opts1 = opts.copy()
Inputs:
opts: odict

Options instance

Outputs:
opts1: odict

Deep copy of options instance

Versions:

  • 2019-05-10 @ddalle: Version 1.0

get_key(k, i=None, rck=None)

Intelligently get option for index i of key k

This is a two-step process. The first is to get the dictionary value or the default if k is not in opts. The default is rc[k]. Let V be the result of the process.

The second step is to apply indexing. If V is a scalar or i is None, then V is the output. Otherwise, the function will attempt to return V[i], but if i is too large, V[-1] is the output.

Call:
>>> v = opts.get_key(k, i, rck=None)
Inputs:
k: str

Name of key to get

i: int | None

Index to apply

rck: str | None

Name of rc0 key to default to

Outputs:
v: any

Let V=opts.get(k,rc[k]). Then v is either V[i] if possible, V[-1] if V is a list and i is not None, or V otherwise

See also:

  • cape.options.util.getel()

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: Version 1.1; add rck

init_section(cls, sec=None, parent=None, prefix=None)

Initialize a generic section

Call:
>>> opts.init_section(cls, sec=None, **kw)
Inputs:
opts: odict

Options interface

cls: type

Class to use for opts[sec]

sec: {cls.__name__} | str

Specific key name to use for subsection

parent: {None} | str

Other subsection from which to inherit defaults

prefix: {None} | str

Prefix to add at beginning of each key

Versions:

  • 2021-10-18 @ddalle: Version 1.0

set_key(k, v=None, i=None, rck=None)

Set option for key k

This sets the value for opts[k] or opts[k][i] if appropriate. If i is greater than the length of opts[k], then opts[k] is appended with its current last value enough times to make opts[k][i] exist.

Call:
>>> opts.set_key(k, v=None, i=None, rck=None)
Inputs:
k: str

Name of key to set

i: int | None

Index to apply

v: any

Value to set

rck: str | None

Name of key in rc0 default option dictionary; defaults to k

See also:

  • cape.options.util.setel()

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: Version 1.1; add rck

cape.cfdx.options.util.applyDefaults(opts, defs)

Recursively apply defaults for any missing options

Call:
>>> opts = applyDefaults(opts, defs)
Inputs:
opts: dict | odict

Options dictionary with some options possibly missing

defs: dict

Full dictionary of default settings

Outputs:
opts: dict | odict

Input dictionary with all of the fields of defs

Versions:

  • 2014-06-17 @ddalle: Version 1.0

  • 2014-07-28 @ddalle: Version 1.1; move to options module

cape.cfdx.options.util.expandJSONFile(fname)

Expand contents of other JSON files

Call:
>>> txt, fnames, linenos = expandJSONFile(fname)
Inputs:
fname: str | unicode

Name of JSON file to read

Outputs:
txt: unicode

Full text with references to JSON file(s) expanded

fnames: list[str]

List of files read (can include the same file multiple times) including fname and any other expanded JSONFile() directives

linenos: np.ndarray (int, ndim=2)

Line numbers in original files; column j represents the line number of each line in file j; 0 for lines not from file j

Versions:

  • 2015-12-10 @ddalle: Version 1.0

cape.cfdx.options.util.getCapeDefaults()

Read default CAPE settings configuration file

Call:
>>> defs = getCapeDefaults()
Outputs:
defs: dict

Dictionary of settings read from JSON file

Versions:

  • 2015-09-20 @ddalle: Version 1.0

  • 2021-03-01 @ddalle: Version 2.0; local JSON file

cape.cfdx.options.util.getDefaults(fname)

Read default settings configuration file

Call:
>>> defs = getDefaults(fname)
Inputs:
fname: str

Name of file with settings to read

Outputs:
defs: dict

Dictionary of settings read from JSON file

Versions:

  • 2014-06-03 @ddalle: Version 1.0

  • 2014-07-28 @ddalle: Version 1.1; in options module

cape.cfdx.options.util.getTemplateFile(fname)

Get the absolute path to a template file by name

Call:
>>> fabs = getTemplateFile(fname)
Inputs:
fname: str

Name of file, such as input.cntl

fabs: str

Full path to file

Versions:

  • 2015-10-26 @ddalle: Version 1.0

cape.cfdx.options.util.getel(x, i=None)

Return element i of an array if possible

Call:
>>> x = getel(x)
>>> xi = getel(x, i)
Inputs:
x: number-like or list-like

A number or list or NumPy vector

i: None | int

Index

Outputs:
xi: scalar

Equal to x[i] if possible, x[-1] if i is greater than the length of x, or x if x is not a list or numpy.ndarray instance

Examples:
>>> getel('abc', 2)
'abc'
>>> getel(1.4, 0)
1.4
>>> getel([200, 100, 300], 1)
100
>>> getel([200, 100, 300], 15)
300
>>> getel([200, 100, 300])
200
Versions:

  • 2014-07-29 @ddalle: Version 1.0

  • 2021-10-18 @ddalle: Version 1.1; add tuple

cape.cfdx.options.util.isArray(x)

Test if a variable is “list-like.”

Call:
>>> q = isArray(x)
Inputs:
x: any

Any variable

Outputs:
q: bool

True if and only if x is a list or NumPy array

Versions:

  • 2014-12-17 @ddalle: Version 1.0

cape.cfdx.options.util.isStr(x)

Test if a variable is “string-like”

Call:
>>> q = isArray(x)
Inputs:
x: any

Any variable

Outputs:
q: bool

True if and only if x is a string or unicode

Versions:

  • 2014-12-17 @ddalle: Version 1.0

cape.cfdx.options.util.loadJSONFile(fname)

Read JSON file w/ helpful error handling and comment stripping

Call:
>>> d = loadJSONFile(fname)
Inputs:
fname: str

Name of JSON file to read

Outputs:
d: dict

JSON contents in Python form

Versions:

  • 2015-12-15 @ddalle: Version 1.0

class cape.cfdx.options.util.odict

Dictionary-based options module

Call:
>>> opts = odict(**kw)
Inputs:
kw: dict

Dictionary of options

Outputs:
opts: cape.options.util.odict

Dictionary-based options interface

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: More robust get_key() using rck

copy()

Create a copy of an options interface

Call:
>>> opts1 = opts.copy()
Inputs:
opts: odict

Options instance

Outputs:
opts1: odict

Deep copy of options instance

Versions:

  • 2019-05-10 @ddalle: Version 1.0

get_key(k, i=None, rck=None)

Intelligently get option for index i of key k

This is a two-step process. The first is to get the dictionary value or the default if k is not in opts. The default is rc[k]. Let V be the result of the process.

The second step is to apply indexing. If V is a scalar or i is None, then V is the output. Otherwise, the function will attempt to return V[i], but if i is too large, V[-1] is the output.

Call:
>>> v = opts.get_key(k, i, rck=None)
Inputs:
k: str

Name of key to get

i: int | None

Index to apply

rck: str | None

Name of rc0 key to default to

Outputs:
v: any

Let V=opts.get(k,rc[k]). Then v is either V[i] if possible, V[-1] if V is a list and i is not None, or V otherwise

See also:

  • cape.options.util.getel()

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: Version 1.1; add rck

init_section(cls, sec=None, parent=None, prefix=None)

Initialize a generic section

Call:
>>> opts.init_section(cls, sec=None, **kw)
Inputs:
opts: odict

Options interface

cls: type

Class to use for opts[sec]

sec: {cls.__name__} | str

Specific key name to use for subsection

parent: {None} | str

Other subsection from which to inherit defaults

prefix: {None} | str

Prefix to add at beginning of each key

Versions:

  • 2021-10-18 @ddalle: Version 1.0

set_key(k, v=None, i=None, rck=None)

Set option for key k

This sets the value for opts[k] or opts[k][i] if appropriate. If i is greater than the length of opts[k], then opts[k] is appended with its current last value enough times to make opts[k][i] exist.

Call:
>>> opts.set_key(k, v=None, i=None, rck=None)
Inputs:
k: str

Name of key to set

i: int | None

Index to apply

v: any

Value to set

rck: str | None

Name of key in rc0 default option dictionary; defaults to k

See also:

  • cape.options.util.setel()

Versions:

  • 2014-08-02 @ddalle: Version 1.0

  • 2015-11-10 @ddalle: Version 1.1; add rck

cape.cfdx.options.util.promote_subsec(cls1, cls2, sec=None, skip=[], **kw)

Promote all methods of a subsection class to parent options class

Methods of parent class will not be overwritten

Call:
>>> promote_subsec(cls1, cls2, sec=None, skip=[], **kw)
Inputs:
cls1: type

Parent class

cls2: type

Subsection class

skip: {[]} | list

List of methods from cls2 not to add to cls1

init: {True} | False

If True, initialize subsection when cls1 methods used

parent: {None} | str

Name of section from which to get default settings

Versions:

  • 2019-01-10 @ddalle: Version 1.0

cape.cfdx.options.util.rc0(p)

Return default setting for named parameter

Call:
>>> v = rc0(p)
Inputs:
p: str

Name of parameter to extract

Outputs:
v: any

Either rc[p] or rc[p][0], whichever is appropriate

Versions:

  • 2014-08-01 @ddalle: Version 1.0

cape.cfdx.options.util.setel(x, i, xi)

Return element i of an array if possible

Call:
>>> y = setel(x, i, xi)
Inputs:
x: number-like or list-like

A number or list or NumPy vector

i: int

Index. If i is None, the output is reset to xi

xi: scalar

Value to set at scalar

Outputs:
y: number-like or list-like

Input x with y[i] set to xi unless i is None

Examples:
>>> setel(['a', 2, 'c'], 1, 'b')
['a', 'b', 'c']
>>> setel(['a', 'b'], 2, 'c')
['a', 'b', 'c']
>>> setel('a', 2, 'c')
['a', None, 'b']
>>> setel([0, 1], None, 'a')
'a'
Versions:

  • 2014-07-29 @ddalle: Version 1.0

  • 2021-10-18 @ddalle: Version 1.1; add tuple

cape.cfdx.options.util.subsec_func(cls, sec=None, parent=None, init=True)

Decorator (w/ args) to apply a function from a subsection class

Call:
>>> f = subsec_func(cls, sec=None, parent=None, init=True)
Inputs:
cls:type

Class to apply to subsection

sec: {cls.__name} | str

Name of subsection

init: {True} | False

If True and nontrivial cls, initialize subsection

parent: {None} | str

Name of section from which to get default settings

Outputs:
f: function

Decorator with arguments expanded

Examples:
@subsec_func("RunControl", RunControl)
def get_PhaseSequence(self, *a, **kw):
    pass
Versions:

  • 2019-01-10 @ddalle: Version 1.0

  • 2021-10-18 @ddalle: Version 1.1; default sec