named_values.py

Define utilities for using named values with associated units.

Utilities

Unitstype alias

define a type hint for associated units

ValueAndUnitstype alias

define a type hint for a single value paired with its associated units

OptionalValueAndUnitstype alias

define a type hint for an optional single value paired with its associated units

class NamedValues

define a collection of named values with associated units

class aviary.utils.named_values.NamedValues(other=None, **kwargs)

Bases: Collection

Define a collection of named values with associated units.

__contains__(key)

Return whether or not the named value exists.

__init__(other=None, **kwargs)

Initialize this collection.

Notes

When initializing from another collection, the following types of collections are supported:

• NamedValues

• Dict[str, ValueAndUnits]

• Iterable[Tuple[str, ValueAndUnits]]

When initializing from keyword arguments, the mapped item must be of a type of ValueAndUnits.

__iter__()

Return an iterator over the (key, (val, units)) data stored in this collection.

clear()

Remove all items from the collection.

copy()

Return a copy of the instance of this class.

Parameters:

None

Return type:

NamedValues()

deepcopy()

Return a deep copy of the instance of this class.

Parameters:

None

Return type:

NamedValues()

delete(key)

Remove the named value and its associated units.

Raises:

KeyError – if the named value does not exist

get_item(key, default=(None, None)) → Tuple[Any, str] | Any

Return the named value and its associated units.

Note, this method never raises KeyError or TypeError.

Parameters:

• key (str) – the name of the item

• default (OptionalValueAndUnits (None, None)) – if the item does not exist, return this object

Return type:

OptionalValueAndUnits

See also

get_val, set_val

get_val(key, units='unitless') → Any

Return the named value in the specified units.

Note, requesting a named value that does not exist will raise KeyError.

Note, specifying units of None or units of any type other than str will raise TypeError.

Parameters:

• key (str) – the name of the item

• units (str ('unitless')) – the units of the returned value

Return type:

val

Raises:

• KeyError – if the named value does not exist

• TypeError – if units of None were specified or units of any type other than str

set_val(key, val, units='unitless')

Update the named value and its associated units.

Note, specifying units of None or units of any type other than str will raise Typerror.

Parameters:

• key (str) – the name of the item

• val (Any) – the new value of the item

• units (str ('unitless')) – the units associated with the new value, if any

Raises:

TypeError – if units of None were specified or units of any type other than str

update(other=None, **kwargs)

Assign named values and their associated units found in another collection to this collection, overwriting existing items.

If keyword arguments are specified, the collection is then assigned those named values and their associated units, overwriting existing items.

Parameters:

• (None) (other) – a collection of named values and their associated units

• (optional) (**kwargs) – individual named values and their associated units

Notes

The following types of collections are supported

• NamedValues

• Dict[str, ValueAndUnits]

• Iterable[Tuple[str, ValueAndUnits]]

When assigning from keyword arguments, the mapped item must be of a type of ValueAndUnits.

aviary.utils.named_values.get_items(named_values: NamedValues)

Return a new view of the collection’s (key, (val, units)).

aviary.utils.named_values.get_keys(named_values: NamedValues)

Return a new view of the collection’s names.

aviary.utils.named_values.get_values(named_values: NamedValues)

Return a new view of the collection’s (val, units).