optdict.optitem: Tools to access items from option lists

This module provides several utilities for accessing items from a list or a so-called “psuedo-list.”

For example, if the value of the option is just "name", this is considered to be a list with "name" repeating infinitely many times. If an option is [1, 7], this is interpreted as either 1 and 7 alternating back and forth or 1 followed by 7 arbitrarily many times (depending on which access function is used).

cape.optdict.optitem.assert_array(obj, listdepth: int, desc=None)

Check that obj is an array to depth listdpeth

Call:
>>> assert_array(obj, listdepth, desc=None)
Inputs:
obj: object

Object whose type is checked

listdepth: int

Minimum number of levels of nested arrays required

desc: {None} | str

Optional description for obj in case of failure

Raises:

OptdictTypeError

Versions:

  • 2023-01-25 @ddalle: Version 1.0

cape.optdict.optitem.check_array(v, listdepth=0)

Check if v is an array type to at least specified depth

Call:
>>> q = check_array(v, listdepth=0)
Inputs:
v: object

Any value

listdepth: {0} | int > 0

Minimum number of array depth; if 0, always returns True; if 2, then v must be a list of lists

Outputs:
q: bool

Whether or not v is an array to specified depth

Versions:

  • 2023-01-25 @ddalle: Version 1.0

cape.optdict.optitem.check_scalar(v, listdepth=0)

Check if v is a “scalar” to specified depth

Call:
>>> q = check_scalar(v, listdepth=0)
Inputs:
v: object

Any value

listdepth: {0} | int > 0

Depth of list to treat as a “scalar;” e.g. if listdepth is 1, then [3, 4] is a “scalar”, but if listdepth is 0, then [3, 4] is not a scalar

Outputs:
q: bool

Whether or not v is a scalar to specified depth

Versions:

  • 2021-12-16 @ddalle: Version 1.0

cape.optdict.optitem.getel(v, j=None, **kw)

Return the jth element of an array if possible

Call:
>>> vj = getel(v, j=None, **kw)
Inputs:
v: scalar | list

A scalar or list of items

j: {None} | int

Phase index; use None to just return v

x, values: {None} | dict

Reference conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

i, index: {None} | int | np.ndarray

Case index or indices to use with @expr, @map, etc.

ring: True | {False}

If True, then use x[j % len(x)]; if False, use x[-1] if j > len(x)

listdepth: {0} | int > 0

Depth of list to treat as a “scalar;” e.g. if listdepth is 1, then [3, 4] is a “scalar”, but if listdepth is 0, then [3, 4] is not a scalar

Outputs:
xj: object

  • x if j is None

  • x if x is scalar (see check_scalar())

  • None if x==[]

  • x[j % len(x)] if ring

  • x[j] if possible

  • x[-1] if j is greater than len(x)-1

  • x[0] if j is less than -len(x)

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, 100, 300]
>>> getel({"@expr": "$a"}, x={"a": [1, 2]})
[1, 2]
Versions:

  • 2015-12-08 @ddalle: Version 1.0

  • 2019-03-02 @ddalle: Version 1.1; in cape.tnakit

  • 2021-12-15 @ddalle: Version 1.2; in optdict

  • 2021-12-16 @ddalle: Version 2.0; add ring, listdepth

  • 2022-09-12 @ddalle: Version 3.0; add @map, @expr, @cons

cape.optdict.optitem.setel(x, xj, j=None, listdepth=0)

Set the jth element of a list if possible

Call:
>>> y = setel(x, xj, j=None, listdepth=0)
Inputs:
x: list | tuple | object

A list or scalar object

j: {None} | int

Phase index; use None to just return x

xj: object

Value to set at x[j] if possible

listdepth: {0} | int > 0

Depth of list to treat as a “scalar;” e.g. if listdepth is 1, then [3, 4] is a “scalar”, but if listdepth is 0, then [3, 4] is not a scalar

Outputs:
y: xj | list

Input x with y[j] set to xj unless j is None

Examples:
>>> setel(['a', 2, 'c'], 'b', 1)
['a', 'b', 'c']
>>> setel(['a', 'b'], 'c', 2)
['a', 'b', 'c']
>>> setel(['a', 'b'], 'c', j=3)
['a', 'b', 'b', 'c']
>>> setel([0, 1], 'a')
'a'
>>> setel([0, 1], 'a', -4)
['a', 0, 0, 1]
>>> setel([0, 1], 'a', j=1, listdepth=1)
[[0, 1], 'a']
>>> setel([0, 1], 'a', j=1, listdepth=2)
[[[0, 1]], 'a']
Versions:

  • 2015-12-08 @ddalle: Version 1.0; in cape.tnakit

  • 2021-12-17 @ddalle: Version 2.0