Parameter

class audobject.Parameter(*, value_type=<class 'str'>, description='', value=None, default_value=None, choices=None, version=None)[source]

Single parameter.

A parameter steers the behaviour of a an object (e.g. tuning a model). It has a specific type and default value, possibly one of a set of choices. It is possible to bound a parameter to a specific version (range).

Parameters

  • value_type (type) – data type, one of (None, str, int, float, bool) or a list or dict of those

  • description (str) – description

  • value (Optional[Any]) – value, if None set to default_value

  • default_value (Optional[Any]) – default value

  • choices (Optional[Sequence[Any]]) – list with choices

  • version (Optional[str]) – string defining in which versions the parameter is used (e.g. '>=1.0.0,<2.0.0,!=1.5.0'), None matches any version

Raises

Examples

>>> foo = Parameter(
...     value_type=str,
...     description='some parameter',
...     default_value='bar',
...     choices=['bar', 'Bar', 'BAR'],
...     version='>=1.0.0,<2.0.0',
... )
>>> # check version
>>> '1.5.0' in foo
True
>>> '2.0.0' in foo
False
>>> # get/set value
>>> foo.value
'bar'
>>> foo.set_value('Bar')
>>> foo.value
'Bar'
>>> # set invalid value
>>> try:
...     foo.set_value('par')
... except ValueError as ex:
...     print(ex)
Invalid value 'par', expected one of ['bar', 'Bar', 'BAR'].

__contains__()

Parameter.__contains__(version)[source]

Check if parameter is in parameter object.

Return type

bool

__hash__()

Parameter.__hash__()

Hash based on object ID.

Return type

int

arguments

Parameter.arguments

Returns arguments that are serialized.

Returns

Dictionary of arguments and their values.

Raises

RuntimeError – if arguments are found that are not assigned to attributes of the same name

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject('test', point=(1, 1))
>>> o.arguments
{'name': 'test', 'point': (1, 1)}

borrowed_arguments

Parameter.borrowed_arguments

Returns borrowed arguments.

Returns

Dictionary with borrowed arguments.

choices

Parameter.choices

Possible choices for parameter

default_value

Parameter.default_value

Default value of parameter

description

Parameter.description

Value of parameter, use ‘set_value’ for type checking

from_dict()

static Parameter.from_dict(d, root=None, **kwargs)
Return type

Object

from_yaml()

static Parameter.from_yaml(path_or_stream, **kwargs)
Return type

Object

from_yaml_s()

static Parameter.from_yaml_s(yaml_string, **kwargs)
Return type

Object

hidden_arguments

Parameter.hidden_arguments

Returns hidden arguments.

Returns

List with names of hidden arguments.

id

Parameter.id

Object identifier.

The ID of an object ID is created from its non-hidden arguments.

Returns

object identifier

Examples

>>> class Foo(Object):
...    def __init__(self, bar: str):
...        self.bar = bar
>>> foo1 = Foo('I am unique!')
>>> foo1.id
'893df240-babe-d796-cdf1-c436171b7a96'
>>> foo2 = Foo('I am different!')
>>> foo2.id
'9303f2a5-bfc9-e5ff-0ffa-a9846e2d2190'
>>> foo3 = Foo('I am unique!')
>>> foo1.id == foo3.id
True

is_loaded_from_dict

Parameter.is_loaded_from_dict

Check if object was loaded from a dictionary.

Returns True if object was initialized from a dictionary, e.g. after loading it from a YAML file.

Returns

True if object was loaded from a dictionary,

otherwise False

resolvers

Parameter.resolvers

Return resolvers.

Returns

Dictionary with resolvers.

set_value()

Parameter.set_value(value)[source]

Sets a new value.

Applies additional checks, e.g. if value is of the expected type.

Parameters

value (Any) – new value

Raises

short_id

Parameter.short_id

Short object identifier.

The short ID consists of eight characters and is created from its non-hidden arguments.

Returns

short object identifier

Examples

>>> class Foo(Object):
...    def __init__(self, bar: str):
...        self.bar = bar
>>> foo1 = Foo('I am unique!')
>>> foo1.id
'893df240-babe-d796-cdf1-c436171b7a96'
>>> foo1.short_id
'171b7a96'
>>> foo2 = Foo('I am different!')
>>> foo2.short_id
'6e2d2190'
>>> foo3 = Foo('I am unique!')
>>> foo1.short_id == foo3.short_id
True

to_dict()

Parameter.to_dict(*, include_version=True, flatten=False, root=None)

Converts object to a dictionary.

Includes items from audobject.Object.arguments. If an argument has a resolver, its value is encoded. Usually, the object can be re-instantiated using audobject.Object.from_dict(). However, if flatten=True, this is not possible.

Parameters

  • include_version (bool) – add version to class name

  • flatten (bool) – flatten the dictionary

  • root (Optional[str]) – if file is written to disk, set to target directory

Return type

Dict[str, Union[bool, datetime, dict, float, int, list, None, str]]

Returns

dictionary that represent the object

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject('test', point=(1, 1))
>>> o.to_dict(include_version=False)
{'$audobject.core.testing.TestObject': {'name': 'test', 'point': [1, 1]}}
>>> o.to_dict(flatten=True)
{'name': 'test', 'point.0': 1, 'point.1': 1}

to_yaml()

Parameter.to_yaml(path_or_stream, *, include_version=True)

Save object to YAML file.

Parameters

  • path_or_stream (Union[str, IO]) – file path or stream

  • include_version (bool) – add version to class name

to_yaml_s()

Parameter.to_yaml_s(*, include_version=True)

Convert object to YAML string.

Parameters

include_version (bool) – add version to class name

Return type

str

Returns

YAML string

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject('test', point=(1, 1))
>>> print(o.to_yaml_s(include_version=False))
$audobject.core.testing.TestObject:
  name: test
  point:
  - 1
  - 1

value

Parameter.value

Description of parameter

value_type

Parameter.value_type

Data type of parameter

version

Parameter.version

Versions in which the parameter is used