espnet2.train.class_choices.ClassChoices

source

class espnet2.train.class_choices.ClassChoices(name: str, classes: Mapping[str, Type], type_check: Type | None = None, default: str | None = None, optional: bool = False)

Bases: object

Helper class to manage the options for variable objects and their configuration.

This class allows the definition of a set of classes that can be chosen dynamically at runtime, along with optional configurations for those classes. It also provides methods to add command-line argument parsing support for selecting the class and passing configuration parameters.

name

The name of the variable being managed.

• Type: str

base_type

The base type that all classes must inherit from.

• Type: Optional[Type]

classes

A mapping of class names to class types.

• Type: Mapping[str, Type]

optional

Indicates if the choice is optional.

• Type: bool

default

The default class name if none is specified.

• Type: Optional[str]

• Parameters:

  • name (str) – The name of the variable.
  • classes (Mapping *[*str , Type ]) – A mapping of class names to class types.
  • type_check (Optional *[*Type ]) – A base class type that the classes must inherit from.
  • default (Optional *[*str ]) – The default class name to use if none is provided.
  • optional (bool) – Whether the choice of class is optional.

• Returns: None

• Raises:ValueError – If “none”, “nil”, or “null” are included in class names or if a class does not inherit from the specified base type.

######### Examples

>>> class A:
...     def __init__(self, foo=3):  pass
>>> class B:
...     def __init__(self, bar="aaaa"):  pass
>>> choices = ClassChoices("var", dict(a=A, b=B), default="a")
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> choices.add_arguments(parser)
>>> args = parser.parse_args(["--var", "a", "--var_conf", "foo=4"])
>>> args.var
'a'
>>> args.var_conf
{'foo': 4}
>>> class_obj = choices.get_class(args.var)
>>> a_object = class_obj(**args.var_conf)

NOTE

The class names are case insensitive and are stored in lowercase.

add_arguments(parser)

Adds command-line arguments for the specified variable and its configuration.

This method integrates with an argparse parser to allow users to specify the type of class they wish to instantiate along with its configuration parameters.

• Parameters:parser (argparse.ArgumentParser) – The argument parser to which the arguments will be added.

######### Examples

>>> import argparse
>>> choices = ClassChoices("var", dict(a=A, b=B), default="a")
>>> parser = argparse.ArgumentParser()
>>> choices.add_arguments(parser)
>>> args = parser.parse_args(["--var", "a", "--var_conf", "foo=4"])
>>> args.var
'a'
>>> args.var_conf
{'foo': 4}

NOTE

The configuration parameters are expected to be provided as a dictionary. The NestedDictAction is used to parse these arguments appropriately.

choices() → Tuple[str | None, ...]

Helper class to manage the options for variable objects and their configuration.

This class provides a way to define a set of choices for a variable, allowing for the selection of classes based on user input. It also facilitates the configuration of those classes through keyword arguments.

Example:

>>> class A:
...     def __init__(self, foo=3): pass
>>> class B:
...     def __init__(self, bar="aaaa"): pass
>>> choices = ClassChoices("var", dict(a=A, b=B), default="a")
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> choices.add_arguments(parser)
>>> args = parser.parse_args(["--var", "a", "--var_conf", "foo=4"])
>>> args.var
'a'
>>> args.var_conf
{'foo': 4}
>>> class_obj = choices.get_class(args.var)
>>> a_object = class_obj(**args.var_conf)

name

The name of the variable.

• Type: str

base_type

The base type for type checking.

• Type: Optional[Type]

classes

A mapping of class names to class types.

• Type: Mapping[str, Type]

optional

Indicates if the choice is optional.

• Type: bool

default

The default choice if none is provided.

• Type: Optional[str]

• Parameters:

  • name (str) – The name of the variable.
  • classes (Mapping *[*str , Type ]) – A mapping of strings to class types.
  • type_check (Optional *[*Type ]) – A type to check against the classes.
  • default (Optional *[*str ]) – The default choice for the variable.
  • optional (bool) – If True, the choice can be omitted.

• Raises:ValueError – If “none”, “nil”, or “null” is in classes or if a class does not subclass the specified type_check.

get_class(name: str | None) → type | None

Retrieve the class associated with the given name.

This method looks up the class in the internal mapping of classes and returns the corresponding class type. If the name is not found or is invalid, it raises a ValueError.

• Parameters:name (Optional *[*str ]) – The name of the class to retrieve. It should match one of the keys in the classes mapping, case-insensitively.
• Returns: The class associated with the given name, or None : if the name is None or represents a null value.
• Return type: Optional[type]
• Raises:ValueError – If the name is not one of the valid options in choices().

######### Examples

>>> choices = ClassChoices("var", dict(a=A, b=B), default="a")
>>> class_obj = choices.get_class("a")
>>> print(class_obj)
<class '__main__.A'>

>>> class_obj = choices.get_class("b")
>>> print(class_obj)
<class '__main__.B'>

>>> class_obj = choices.get_class("none")
>>> print(class_obj)
None

>>> choices.get_class("invalid")  # Raises ValueError