earwax.config module

Provides the Config and ConfigValue classes.

class earwax.config.Config

Bases: object

Holds configuration subsections and values.

Any attribute that is an instance of earwax.Config is considered a subsection.

Any attribute that is an instance of earwax.ConfigValue is considered a configuration value.

You can create sections like so:

from earwax import Config, ConfigValue

class GameConfig(Config):
    '''Example configuration page.'''

    hostname = ConfigValue('localhost')
    port = ConfigValue(1234)

c = GameConfig()

Then you can access configuration values like this:

host_string = f'{c.hostname.value}:{c.port.value}'
# ...

Use the dump() method to get a dictionary suitable for dumping with json.

To set the name that will be used by earwax.ConfigMenu, subclass earwax.Config, and include a __section_name__ attribute:

class NamedConfig(Config):
    __section_name__ = 'Options'
Variables:__section_name__ –

The human-readable name of this section.

At present, this attribute is only used by earwax.ConfigMenu.
dump() → Dict[str, Any]

Return all configuration values, recursing through subsections.

For example:

c = ImaginaryConfiguration()
d = c.dump()
with open('config.yaml', 'w') as f:
    json.dump(d, f)

Use the populate_from_dict() method to restore dumped values.

load(f: TextIO) → None

Load data from a file.

Uses the populate_from_dict() method on dataloaded from the given file:

c = ImaginaryConfigSection()
with open('config.yaml', 'r'):
    c.load(f)

To save the data in the first place, use the save() method.

Parameters:f – A file-like object to load data from.
populate_from_dict(data: Dict[str, Any]) → None

Populate values from a dictionary.

This function is compatible with (and used by) dump():

c = Config()
with open('config.yaml', 'r') as f:
    c.populate_from_dict(json.load(f))

Any missing values from data are ignored.

Parameters:data – The data to load.
save(f: TextIO) → None

Dump this configuration section to a file.

Uses the dump() method to get the dumpable data.

You can save a configuration section like so:

c = ImaginaryConfigSection()
with open('config.yaml', 'w') as f:
    c.save(f)

By default, YAML is used.

Parameters:f – A file-like object to write the resulting data to.
class earwax.config.ConfigValue(value: T, name: Optional[str] = None, type_: Optional[object] = None, value_converters: Optional[Dict[object, Callable[[ConfigValue], str]]] = None, dump_func: Optional[Callable[[T], T]] = None, load_func: Optional[Callable[[str], T]] = None)

Bases: typing.Generic

A configuration value.

This class is used to make configuration values:

name = ConfigValue('username', name='Your character name', type_=str)

If you are dealing with a non-standard object, you can set custom functions for loading and dumping the objects:

from pathlib import Path
option = ConfigValue(Path.cwd(), name='Some directory')

@option.dump
def dump_path(value: Path) -> str:
    return str(value)

@option.load
def load_path(value: str) -> Path:
    return Path(value)
Variables:
  • value – The value held by this configuration value.
  • name –

    The human-readable name of this configuration value.

    The name is currently only used by earwax.ConfigMenu.

  • type_ –

    The type of this value. Can be inferred from value.

    Currently this attribute is used by earwax.ConfigMenu to figure out how to construct the widget that will represent this value.

  • value_converters –

    A dictionary of type: converter functions.

    These are used by earwax.ConfigMenu.option_menu() to print value, instead of value_to_string().

  • default –

    The default value for this configuration value.

    This will be inferred from value.

  • dump_func – A function that will take the actual value, and return something that YAML can dump.
  • load_func – A function that takes the value that was loaded by YAML, and returns the actual value.
dump(func: Callable[[T], T]) → Callable[[T], T]

Add a dump function.

Parameters:func –

The function that will be decorated.

See the description for dump_func.
load(func: Callable[[str], T]) → Callable[[str], T]

Add a load function.

Parameters:func –

The function that will be decorated.

See the description for load_func.
value_to_string() → str

Return value as a string.

This method is used by earwax.ConfigMenu when it shows values.