earwax.menus.config_menu module

Provides the ConfigMenu class,.

class earwax.menus.config_menu.ConfigMenu(game: Game, title: Union[str, TitleFunction], dismissible: bool = True, item_select_sound_path: Optional[pathlib.Path] = None, item_activate_sound_path: Optional[pathlib.Path] = None, position: int = -1, search_timeout: float = 0.5, search_time: float = 0.0, config: earwax.config.Config = NOTHING)

Bases: earwax.menus.menu.Menu

A menu that allows the user to set values on configuration sections.

If an option is present with a type the menu doesn’t know how to handle, earwax.UnknownTypeError will be raised.

Variables:

• config – The configuration section this menu will configure.
• type_handlers –

  Functions to handle the types this menu knows about.

  New types can be handled with the type_handler() method.

activate_handler(handler: earwax.menus.config_menu.TypeHandler, option: earwax.config.ConfigValue) → Callable[[], Optional[Generator[None, None, None]]]

Activates the given handler with the given configuration value.

Used by the option_menu() method when building menus.

Parameters:

• handler – The TypeHandler instance that should be activated.
• option – The ConfigValue instance the handler should work with.

clear_value(option: earwax.config.ConfigValue) → None

Clear the value.

Sets option.value to None.

Used by the default TypeHandler that handles nullable values.

Parameters:option – The ConfigValue instance whose value should be set to None.

earwax_config() → earwax.config.Config

Return the main earwax configuration.

get_option_name(option: earwax.config.ConfigValue, name: str) → str

Get the name for the given option.

The provided name argument will be the attribute name, so should only be used if the option has no __section_name__ attribute.

Parameters:

• option – The ConfigValue instance whose name should be returned.
• name – The name of the attribute that holds the option.

get_subsection_name(subsection: earwax.config.Config, name: str) → str

Get the name for the given subsection.

The provided name argument will be the attribute name, so should only be used if the subsection has no __section_name__ attribute.

Parameters:

• subsection – The Config instance whose name should be returned.
• name – The name of the attribute that holds the subsection.

handle_bool(option: earwax.config.ConfigValue) → None

Toggle a boolean value.

Used by the default TypeHandler that handles boolean values.

Parameters:option – The ConfigValue instance to work on.

handle_float(option: earwax.config.ConfigValue) → Generator[None, None, None]

Allow editing floats.

Used by the default TypeHandler that handles float values.

Parameters:option – The ConfigValue instance to work on.

handle_int(option: earwax.config.ConfigValue) → Generator[None, None, None]

Allow editing integers.

Used by the default TypeHandler that handles integer values.

Parameters:option – The ConfigValue instance to work on.

handle_path(option: earwax.config.ConfigValue) → Generator[None, None, None]

Allow selecting files and folders.

Used by the default TypeHandler that handles pathlib.Path values.

Parameters:option – The ConfigValue instance to work on.

handle_string(option: earwax.config.ConfigValue) → Generator[None, None, None]

Allow editing strings.

Used by the default TypeHandler that handles string values.

Parameters:option – The ConfigValue instance to work on.

option_menu(option: earwax.config.ConfigValue, name: str) → Callable[[], Generator[None, None, None]]

Add a menu for the given option.

If the type of the provided option is a Union type (like Optional[str]), then an entry for editing each type will be added to the menu. Otherwise, there will be only one entry.

The only special case is when the type is a tuple of values. If this happens, the menu will instead be populated with a list of entries corrisponding to the values of the tuple.

At the end of the menu, there will be an option to restore the default value.

Parameters:

• option – The ConfigValue instance to generate a menu for.
• name – The proper name of the given option, as returned by get_option_name().

set_value(option: earwax.config.ConfigValue, value: Any, message: str = 'Done.') → Callable[[], None]

Set a value.

Returns a callable that can be used to set the value of the provided option to the provided value.

This method returns a callable because it is used extensively by option_menu(), and a bunch of lambdas becomes less readable. Plus, Mypy complains about them.

Parameters:

• option – The ConfigValue instance to work on.
• value – The value to set option.value to.
• message – The message to be spoken after setting the value.

subsection_menu(subsection: earwax.config.Config, name: str) → Callable[[], Generator[None, None, None]]

Add a menu for the given subsection.

By default, creates a new earwax.ConfigMenu instance, and returns a function that - when called - will push it onto the stack.

Parameters:

• subsection – The Config instance to create a menu for.
• name – The proper name of the subsection, returned by get_subsection_name().

type_handler(type_: object, title: Callable[[earwax.config.ConfigValue, str], str]) → Callable[[Callable[[earwax.config.ConfigValue], Optional[Generator[None, None, None]]]], Callable[[earwax.config.ConfigValue], Optional[Generator[None, None, None]]]]

Add a type handler.

Decorate a function to be used as a type handler:

from datetime import datetime, timedelta
from earwax import ConfigMenu, tts

m = ConfigMenu(pretend_config, 'Options', game)

@m.type_handler(datetime, lambda option, name: 'Add a week')
def add_week(option):
    '''Add a week to the current value.'''
    option.value += timedelta(days=7)
    self.game.output('Added a week.')
    m.game.pop_level()

Handlers can do anything menu item functions can do, including creating more menus, and yielding.

Parameters:

• type – The type this handler should be registered for.
• title – A function which will return the title for the menu item for this handler.

class earwax.menus.config_menu.TypeHandler(title: Callable[[earwax.config.ConfigValue, str], str], func: Callable[[earwax.config.ConfigValue], Optional[Generator[None, None, None]]])

Bases: object

A type handler for use with ConfigMenu instances.

Variables:

• title – A function that will return a string which can be used as the title for the menu item generated by this handler.
• func – The function that will be called when this handler is required.

exception earwax.menus.config_menu.UnknownTypeError

Bases: Exception

An unknown type was encountered.

An exception which will be thrown if a ConfigMenu instance doesn’t know how to handle the given type.