textual_shell.configure

MissingSection

Bases: Exception

Custom Exception for when a section is not found.

Source code in src/textual_shell/configure.py

class MissingSection(Exception):
    """Custom Exception for when a section is not found."""
    pass

MissingSetting

Bases: Exception

Custom Exception for when a setting is not found.

Source code in src/textual_shell/configure.py

class MissingSetting(Exception):
    """Custom Exception for when a setting is not found."""
    pass

add_section(section_name, section, path)

Add a section to the config.

Parameters:

Name	Type	Description	Default
section	dict[str, str]	The section name.	required
path	str	The path to the config	required

Source code in src/textual_shell/configure.py

def add_section(
    section_name: Annotated[str, 'The section key'],
    section: Annotated[dict[str, str], 'Section config'],
    path: Annotated[str, 'The path to the config file.']
) -> None:
    """
    Add a section to the config.

    Args:
        section (dict[str, str]): The section name.
        path (str): The path to the config
    """
    config = get_config(path)
    if section_name not in config:
        config.update(section)

    with open(path, 'w') as config_file:
        yaml.dump(config, config_file)

check_section(section, path)

Check if a section exists in the config.

Parameters:

Name	Type	Description	Default
section	str	The section of the config.	required
path	str	The path to the config.	required

Returns:

Name	Type	Description
exists	bool	True if it exists else False.

Source code in src/textual_shell/configure.py

def check_section(
    section: Annotated[str, 'The name of the section.'],
    path: Annotated[str, 'The path to create the config file.'],
) -> bool:
    """
    Check if a section exists in the config.

    Args:
        section (str): The section of the config.
        path (str): The path to the config.

    Returns:
        exists (bool): True if it exists else False.
    """
    config = get_config(path)
    return section in config

create_config(path, config={})

Create a default config for the application.

Parameters:

Name	Type	Description	Default
path	str	The path to create the config file.	required

Source code in src/textual_shell/configure.py

def create_config(
    path: Annotated[str, 'The path to create the config file.'],
    config: Annotated[dict[str, str], 'Settings']={}
) -> None:
    """
    Create a default config for the application.

    Args:
        path (str): The path to create the config file.
    """
    if not os.path.exists(path):
        with open(path, 'w') as config_file:
            yaml.dump(config, config_file)

get_config(path)

Load the config into a dictionary.

Parameters:

Name	Type	Description	Default
path	str	The path to the config.	required

Source code in src/textual_shell/configure.py

def get_config(
    path: Annotated[str, 'The path to the config file.']
) -> Annotated[dict, 'The config loaded into a dictionary.']:
    """
    Load the config into a dictionary.

    Args:
        path (str): The path to the config.
    """
    if not os.path.exists(path):
        create_config(path)

    with open(path, 'r') as config_file:
        return yaml.safe_load(config_file) or {}

get_section(section_name, path)

Get the section sub dictionary.

Parameters:

Name	Type	Description	Default
section_name	str	The section of the config.	required
path	str	The path to the config.	required

Raises:

Type	Description
MissingSection	Exception for missing section

Source code in src/textual_shell/configure.py

def get_section(
    section_name: Annotated[str, 'The section of the config.'],
    path: Annotated[str, 'The path to create the config file.']
) -> Annotated[dict[str,dict], 'The section sub dictionary.']:
    """
    Get the section sub dictionary.

    Args:
        section_name (str): The section of the config.
        path (str): The path to the config.

    Raises:
        MissingSection: Exception for missing section
    """
    config = get_config(path)
    section = config.get(section_name, None)

    if section is None:
        raise MissingSection(f'Section: {section_name} does not exists!')

    return section 

get_setting(section_name, setting_name, path)

Get the setting sub dictionary.

Parameters:

Name	Type	Description	Default
section_name	str	The section of the config.	required
setting_name	str	The setting to retrieve the value for.	required
path	str	The path to the config.	required

Returns:

Name	Type	Description
setting	dict	The description and value of a setting.

Raises:

Type	Description
MissingSetting	Exception for missing setting.

Source code in src/textual_shell/configure.py

def get_setting(
    section_name: Annotated[str, 'The section of the config.'],
    setting_name: Annotated[str, 'The setting to get.'],
    path: Annotated[str, 'The path to create the config file.']
) -> Annotated[str | None, 'The setting sub dictionary.']:
    """
    Get the setting sub dictionary.

    Args:
        section_name (str): The section of the config.
        setting_name (str): The setting to retrieve the value for.
        path (str): The path to the config.

    Returns:
        setting (dict): The description and value of a setting.

    Raises:
        MissingSetting: Exception for missing setting.
    """
    section = get_section(section_name, path)
    setting = section.get(setting_name, None)

    if setting is None:
        raise MissingSetting(
            f'Setting: {section_name}.{setting_name} does not exist!'
        )

    return setting

get_setting_description(section, setting, path)

Retrieve the description of a setting.

Parameters:

Name	Type	Description	Default
section	str	The section of the config.	required
setting	str	The setting to retrieve the value for.	required
path	str	The path to the config.	required

Returns:

Name	Type	Description
description	str	The description of the setting.

Source code in src/textual_shell/configure.py

def get_setting_description(
    section: Annotated[str, 'The section of the config.'],
    setting: Annotated[str, 'The setting to get.'],
    path: Annotated[str, 'The path to the config file.']
) -> Annotated[str, 'The description of the setting.']:
    """
    Retrieve the description of a setting.

    Args:
        section (str): The section of the config.
        setting (str): The setting to retrieve the value for.
        path (str): The path to the config.

    Returns: 
        description (str): The description of the setting.
    """
    setting = get_setting(section, setting, path)
    return setting.get('description')

get_setting_options(section, setting, path)

Get the options for a specific setting if they exist.

Parameters:

Name	Type	Description	Default
section	str	The section of the config.	required
setting	str	The setting to retrieve the value for.	required
path	str	The path to the config.	required

Returns:

Name	Type	Description
options	list[str] | dict[str, str]	The options can either be a list of possible values, or a dictionary where the keys are the values that will be displayed and the value will be the actual value.

Source code in src/textual_shell/configure.py

def get_setting_options(
    section: Annotated[str, 'The section of the config.'],
    setting: Annotated[str, 'The setting to get.'],
    path: Annotated[str, 'The path to the config file.']
) -> (list[str] | dict[str, str]):
    """
    Get the options for a specific setting if they exist.

    Args:
        section (str): The section of the config.
        setting (str): The setting to retrieve the value for.
        path (str): The path to the config.

    Returns:
        options (list[str] | dict[str, str]):
            The options can either be a list of possible values, 
            or a dictionary where the keys are the values that will
            be displayed and the value will be the actual value.
    """
    setting = get_setting(section, setting, path)

    return setting.get('options', None)

get_setting_value(section, setting, path)

Get the value of the setting.

Parameters:

Name	Type	Description	Default
section	str	The section of the config.	required
setting	str	The setting to retrieve the value for.	required
path	str	The path to the config.	required

Returns:

Name	Type	Description
value	str	The value of the setting.

Source code in src/textual_shell/configure.py

def get_setting_value(
    section: Annotated[str, 'The section of the config.'],
    setting: Annotated[str, 'The setting to get.'],
    path: Annotated[str, 'The path to the config file.']
) -> Annotated[str, 'The value of the setting.']:
    """
    Get the value of the setting.

    Args:
        section (str): The section of the config.
        setting (str): The setting to retrieve the value for.
        path (str): The path to the config.

    Returns:
        value (str): The value of the setting.
    """
    setting = get_setting(section, setting, path)
    return setting.get('value')

update_setting(section, setting, path, value=None)

Update the value of a setting.

Parameters:

Name	Type	Description	Default
section	str	The section of the config.	required
setting	str	The setting to retrieve the value for.	required
path	str	The path to the config.	required
value	str	The new value.	None

Source code in src/textual_shell/configure.py

def update_setting(
    section: Annotated[str, 'The section of the config.'],
    setting: Annotated[str, 'The setting to update.'],
    path: Annotated[str, 'The path to create the config file.'],
    value: Annotated[str, 'The new value']=None,
) -> None:
    """
    Update the value of a  setting.

    Args:
        section (str): The section of the config.
        setting (str): The setting to retrieve the value for.
        path (str): The path to the config.
        value (str): The new value.
    """
    config = get_config(path)
    if section not in config:
        config[section] = {}

    config[section][setting]['value'] = value

    with open(path, 'w') as config_file:
        yaml.dump(config, config_file)