Skip to content

epymorph.settings

The module to organize epymorph's configuration settings and related functionality.

ValueT module-attribute 

ValueT = TypeVar('ValueT')

The type of the value of a setting.

SETTINGS module-attribute 

SETTINGS = list[Setting]()

A list of epymorph configuration settings.

InvalidBooleanError

Bases: Exception

Raised when a value cannot be interpreted as a boolean.

Setting

Bases: NamedTuple, Generic[ValueT]

An epymorph configuration setting.

name instance-attribute 

name: str

The name of the setting.

description instance-attribute 

description: str

The description of the setting.

getter instance-attribute 

getter: Callable[[], ValueT]

A function to get the value of the setting.

get 

get() -> ValueT

Get the current value of the setting.

strtobool 

strtobool(value: str) -> bool

Interpret a string as a boolean, if possible.

We use the widely-adopted distutils.util.strtobool convention for strings which can be interpreted as booleans. To quote the documentation: "True values are y, yes, t, true, on, and 1; false values are n, no, f, false, off, and 0." Whitespace will be stripped and values are case-insensitive.

Parameters:

  • value (str) –

    The string to interpret.

Returns:

  • bool –

    The boolean value if valid.

Raises:

env_flag 

env_flag(
    name: str, default_value: bool | None = None
) -> bool | None

Load an environment variable assuming it represents a boolean setting.

See the strtobool function for the set of strings which are allowed for True and False.

Parameters:

  • name (str) –

    The name of the environment variable to load.

  • default_value (bool | None, default: None ) –

    A default value to use in case the variable is not present or can't be interpreted as a boolean.

Returns:

  • bool | None –

    If the named variable is present and if the value can be interpreted as a boolean, return the boolean. Else return default_value.

declare_setting 

declare_setting(
    name: str,
    description: str,
    getter: Callable[[], ValueT],
) -> Setting[ValueT]

Declare an application configuration setting.

Parameters:

  • name (str) –

    The setting name.

  • description (str) –

    The setting description.

  • getter (Callable[[], ValueT]) –

    A function to get the value of the setting.

Returns:

Raises:

  • ValueError –

    If a setting of the same name has been previously declared.