Home Assistant Unofficial Reference 2024.12.1
Classes | Functions | Variables
homeassistant.config Namespace Reference

Classes

class  _PlatformIntegration
 
class  ConfigErrorTranslationKey
 
class  ConfigExceptionInfo
 
class  IntegrationConfigInfo
 

Functions

ConfigType|None _async_load_and_validate_platform_integration (str domain, str|None integration_docs, list[ConfigExceptionInfo] config_exceptions, _PlatformIntegration p_integration)
 
tuple[str, int|str]|None _get_annotation (Any item)
 
Any _get_by_path (dict|list data, list[Hashable] items)
 
tuple[str|None, bool, dict[str, str]] _get_log_message_and_stack_print_pref (HomeAssistant hass, str domain, ConfigExceptionInfo platform_exception)
 
str|None _identify_config_schema (ComponentProtocol module)
 
None _log_pkg_error (HomeAssistant hass, str package, str|None component, dict config, str message)
 
str|None _recursive_merge (dict[str, Any] conf, dict[str, Any] package)
 
str _relpath (HomeAssistant hass, str path)
 
None _validate_package_definition (str name, Any conf)
 
bool _write_default_config (str config_dir)
 
str|None async_check_ha_config_file (HomeAssistant hass)
 
bool async_create_default_config (HomeAssistant hass)
 
ConfigType|None async_drop_config_annotations (IntegrationConfigInfo integration_config_info, Integration integration)
 
None async_enable_safe_mode (HomeAssistant hass)
 
bool async_ensure_config_exists (HomeAssistant hass)
 
None async_handle_component_errors (HomeAssistant hass, IntegrationConfigInfo integration_config_info, Integration integration, bool raise_on_failure=False)
 
dict async_hass_config_yaml (HomeAssistant hass)
 
None async_log_config_validator_error (vol.Invalid|HomeAssistantError exc, str domain, dict config, HomeAssistant hass, str|None link=None)
 
None async_log_schema_error (vol.Invalid exc, str domain, dict config, HomeAssistant hass, str|None link=None)
 
ConfigType|None async_process_component_and_handle_errors (HomeAssistant hass, ConfigType config, Integration integration, bool raise_on_failure=False)
 
IntegrationConfigInfo async_process_component_config (HomeAssistant hass, ConfigType config, Integration integration, ComponentProtocol|None component=None)
 
Iterable[tuple[str|None, ConfigType]] config_per_platform (ConfigType config, str domain)
 
ConfigType config_without_domain (ConfigType config, str domain)
 
Sequence[str] extract_domain_configs (ConfigType config, str domain)
 
dict[str, set[str]] extract_platform_integrations (ConfigType config, set[str] domains)
 
tuple[str, int|str]|None find_annotation (dict|list config, list[Hashable] path)
 
str format_homeassistant_error (HomeAssistant hass, HomeAssistantError exc, str domain, dict config, str|None link=None)
 
str format_schema_error (HomeAssistant hass, vol.Invalid exc, str domain, dict config, str|None link=None)
 
str get_default_config_dir ()
 
str humanize_error (HomeAssistant hass, vol.Invalid validation_error, str domain, dict config, str|None link, int max_sub_error_length=MAX_VALIDATION_ERROR_ITEM_LENGTH)
 
dict[Any, Any] load_yaml_config_file (str config_path, Secrets|None secrets=None)
 
dict merge_packages_config (HomeAssistant hass, dict config, dict[str, Any] packages, Callable[[HomeAssistant, str, str|None, dict, str], None] _log_pkg_error=_log_pkg_error)
 
None process_ha_config_upgrade (HomeAssistant hass)
 
bool safe_mode_enabled (str config_dir)
 
str stringify_invalid (HomeAssistant hass, vol.Invalid exc, str domain, dict config, str|None link, int max_sub_error_length)
 

Variables

 _LOGGER = logging.getLogger(__name__)
 
string AUTOMATION_CONFIG_PATH = "automations.yaml"
 
string CONFIG_DIR_NAME = ".homeassistant"
 
string DEFAULT_CONFIG
 
string DEFAULT_SECRETS
 
tuple INTEGRATION_LOAD_EXCEPTIONS = (IntegrationNotFound, RequirementsNotFound)
 
tuple LOAD_EXCEPTIONS = (ImportError, FileNotFoundError)
 
 RE_ASCII = re.compile(r"\033\[[^m]*m")
 
 RE_YAML_ERROR = re.compile(r"homeassistant\.util\.yaml")
 
string SAFE_MODE_FILENAME = "safe-mode"
 
string SCENE_CONFIG_PATH = "scenes.yaml"
 
string SCRIPT_CONFIG_PATH = "scripts.yaml"
 
string TTS_92
 
string TTS_PRE_92
 
string VERSION_FILE = ".HA_VERSION"
 
string YAML_CONFIG_FILE = "configuration.yaml"
 

Detailed Description

Module to help with parsing and generating configuration files.

Function Documentation

◆ _async_load_and_validate_platform_integration()

ConfigType | None homeassistant.config._async_load_and_validate_platform_integration ( str  domain,
str | None  integration_docs,
list[ConfigExceptionInfo]  config_exceptions,
_PlatformIntegration  p_integration 
)
private 
Load a platform integration and validate its config.

Definition at line 1047 of file config.py.

◆ _get_annotation()

tuple[str, int | str] | None homeassistant.config._get_annotation ( Any  item)
private

Definition at line 377 of file config.py.

◆ _get_by_path()

Any homeassistant.config._get_by_path ( dict | list  data,
list[Hashable]  items 
)
private 
Access a nested object in root by item sequence.

Returns None in case of error.

Definition at line 384 of file config.py.

◆ _get_log_message_and_stack_print_pref()

tuple[str | None, bool, dict[str, str]] homeassistant.config._get_log_message_and_stack_print_pref ( HomeAssistant  hass,
str  domain,
ConfigExceptionInfo   platform_exception 
)
private 
Get message to log and print stack trace preference.

Definition at line 804 of file config.py.

◆ _identify_config_schema()

str | None homeassistant.config._identify_config_schema ( ComponentProtocol  module)
private 
Extract the schema and identify list or dict based.

Definition at line 593 of file config.py.

◆ _log_pkg_error()

None homeassistant.config._log_pkg_error ( HomeAssistant  hass,
str  package,
str | None  component,
dict  config,
str   message 
)
private 
Log an error while merging packages.

Definition at line 580 of file config.py.

◆ _recursive_merge()

str | None homeassistant.config._recursive_merge ( dict[str, Any]  conf,
dict[str, Any]  package 
)
private 
Merge package into conf, recursively.

Definition at line 647 of file config.py.

◆ _relpath()

str homeassistant.config._relpath ( HomeAssistant  hass,
str  path 
)
private 
Return path relative to the Home Assistant config dir.

Definition at line 448 of file config.py.

◆ _validate_package_definition()

None homeassistant.config._validate_package_definition ( str  name,
Any  conf 
)
private 
Validate basic package definition properties.

Definition at line 641 of file config.py.

◆ _write_default_config()

bool homeassistant.config._write_default_config ( str  config_dir)
private 
Write the default config.

Definition at line 168 of file config.py.

◆ async_check_ha_config_file()

str | None homeassistant.config.async_check_ha_config_file ( HomeAssistant  hass) 
Check if Home Assistant configuration file is valid.

This method is a coroutine.

Definition at line 1319 of file config.py.

◆ async_create_default_config()

bool homeassistant.config.async_create_default_config ( HomeAssistant  hass) 
Create a default configuration file in given configuration directory.

Return if creation was successful.

Definition at line 158 of file config.py.

◆ async_drop_config_annotations()

ConfigType | None homeassistant.config.async_drop_config_annotations ( IntegrationConfigInfo  integration_config_info,
Integration  integration 
) 
Remove file and line annotations from str items in component configuration.

Definition at line 881 of file config.py.

◆ async_enable_safe_mode()

None homeassistant.config.async_enable_safe_mode ( HomeAssistant  hass) 
Enable safe mode.

Definition at line 1346 of file config.py.

◆ async_ensure_config_exists()

bool homeassistant.config.async_ensure_config_exists ( HomeAssistant  hass) 
Ensure a configuration file exists in given configuration directory.

Creating a default one if needed.
Return boolean if configuration dir is ready to go.

Definition at line 141 of file config.py.

◆ async_handle_component_errors()

None homeassistant.config.async_handle_component_errors ( HomeAssistant  hass,
IntegrationConfigInfo  integration_config_info,
Integration  integration,
bool   raise_on_failure = False 
) 
Handle component configuration errors from async_process_component_config.

In case of errors:
- Print the error messages to the log.
- Raise a ConfigValidationError if raise_on_failure is set.

Definition at line 916 of file config.py.

◆ async_hass_config_yaml()

dict homeassistant.config.async_hass_config_yaml ( HomeAssistant  hass) 
Load YAML from a Home Assistant configuration file.

This function allows a component inside the asyncio loop to reload its
configuration by itself. Include package merge.

Definition at line 209 of file config.py.

◆ async_log_config_validator_error()

None homeassistant.config.async_log_config_validator_error ( vol.Invalid | HomeAssistantError  exc,
str  domain,
dict  config,
HomeAssistant  hass,
str | None   link = None 
) 
Log an error from a custom config validator.

Definition at line 361 of file config.py.

◆ async_log_schema_error()

None homeassistant.config.async_log_schema_error ( vol.Invalid  exc,
str  domain,
dict  config,
HomeAssistant  hass,
str | None   link = None 
) 
Log a schema validation error.

Definition at line 348 of file config.py.

◆ async_process_component_and_handle_errors()

ConfigType | None homeassistant.config.async_process_component_and_handle_errors ( HomeAssistant  hass,
ConfigType  config,
Integration  integration,
bool   raise_on_failure = False 
) 
Process and component configuration and handle errors.

In case of errors:
- Print the error messages to the log.
- Raise a ConfigValidationError if raise_on_failure is set.

Returns the integration config or `None`.

Definition at line 857 of file config.py.

◆ async_process_component_config()

IntegrationConfigInfo homeassistant.config.async_process_component_config ( HomeAssistant  hass,
ConfigType  config,
Integration  integration,
ComponentProtocol | None   component = None 
) 
Check component configuration.

Returns processed configuration and exception information.

This method must be run in the event loop.

Definition at line 1097 of file config.py.

◆ config_per_platform()

Iterable[tuple[str | None, ConfigType]] homeassistant.config.config_per_platform ( ConfigType  config,
str   domain 
) 
Break a component config into different platforms.

For example, will find 'switch', 'switch 2', 'switch 3', .. etc
Async friendly.

Definition at line 967 of file config.py.

◆ config_without_domain()

ConfigType homeassistant.config.config_without_domain ( ConfigType  config,
str  domain 
) 
Return a config with all configuration for a domain removed.

Definition at line 1313 of file config.py.

◆ extract_domain_configs()

Sequence[str] homeassistant.config.extract_domain_configs ( ConfigType  config,
str  domain 
) 
Extract keys from config for given domain name.

Async friendly.

Definition at line 1022 of file config.py.

◆ extract_platform_integrations()

dict[str, set[str]] homeassistant.config.extract_platform_integrations ( ConfigType  config,
set[str]   domains 
) 
Find all the platforms in a configuration.

Returns a dictionary with domain as key and a set of platforms as value.

Definition at line 993 of file config.py.

◆ find_annotation()

tuple[str, int | str] | None homeassistant.config.find_annotation ( dict | list  config,
list[Hashable]   path 
) 
Find file/line annotation for a node in config pointed to by path.

If the node pointed to is a dict or list, prefer the annotation for the key in
the key/value pair defining the dict or list.
If the node is not annotated, try the parent node.

Definition at line 395 of file config.py.

◆ format_homeassistant_error()

str homeassistant.config.format_homeassistant_error ( HomeAssistant  hass,
HomeAssistantError  exc,
str  domain,
dict  config,
str | None   link = None 
) 
Format HomeAssistantError thrown by a custom config validator.

Definition at line 541 of file config.py.

◆ format_schema_error()

str homeassistant.config.format_schema_error ( HomeAssistant  hass,
vol.Invalid  exc,
str  domain,
dict  config,
str | None   link = None 
) 
Format configuration validation error.

Definition at line 569 of file config.py.

◆ get_default_config_dir()

str homeassistant.config.get_default_config_dir ( ) 
Put together the default configuration directory based on the OS.

Definition at line 135 of file config.py.

◆ humanize_error()

str homeassistant.config.humanize_error ( HomeAssistant  hass,
vol.Invalid  validation_error,
str  domain,
dict  config,
str | None  link,
int   max_sub_error_length = MAX_VALIDATION_ERROR_ITEM_LENGTH 
) 
Provide a more helpful + complete validation error message.

This is a modified version of voluptuous.error.Invalid.__str__,
the modifications make some minor changes to the formatting.

Definition at line 513 of file config.py.

◆ load_yaml_config_file()

dict[Any, Any] homeassistant.config.load_yaml_config_file ( str  config_path,
Secrets | None   secrets = None 
) 
Parse a YAML configuration file.

Raises FileNotFoundError or HomeAssistantError.

This method needs to run in an executor.

Definition at line 266 of file config.py.

◆ merge_packages_config()

dict homeassistant.config.merge_packages_config ( HomeAssistant  hass,
dict  config,
dict[str, Any]  packages,
Callable[ [HomeAssistant, str, str | None, dict, str], None ]   _log_pkg_error = _log_pkg_error 
) 
Merge packages into the top-level configuration.

Ignores packages that cannot be setup. Mutates config. Raises
vol.Invalid if whole package config is invalid.

Definition at line 669 of file config.py.

◆ process_ha_config_upgrade()

None homeassistant.config.process_ha_config_upgrade ( HomeAssistant  hass) 
Upgrade configuration if necessary.

This method needs to run in an executor.

Definition at line 291 of file config.py.

◆ safe_mode_enabled()

bool homeassistant.config.safe_mode_enabled ( str  config_dir) 
Return if safe mode is enabled.

If safe mode is enabled, the safe mode file will be removed.

Definition at line 1334 of file config.py.

◆ stringify_invalid()

str homeassistant.config.stringify_invalid ( HomeAssistant  hass,
vol.Invalid  exc,
str  domain,
dict  config,
str | None  link,
int  max_sub_error_length 
) 
Stringify voluptuous.Invalid.

This is an alternative to the custom __str__ implemented in
voluptuous.error.Invalid. The modifications are:
- Format the path delimited by -> instead of @data[]
- Prefix with domain, file and line of the error
- Suffix with a link to the documentation
- Give a more user friendly output for unknown options
- Give a more user friendly output for missing options

Definition at line 453 of file config.py.

Variable Documentation

◆ _LOGGER

homeassistant.config._LOGGER = logging.getLogger(__name__)
private

Definition at line 40 of file config.py.

◆ AUTOMATION_CONFIG_PATH

string homeassistant.config.AUTOMATION_CONFIG_PATH = "automations.yaml"

Definition at line 48 of file config.py.

◆ CONFIG_DIR_NAME

string homeassistant.config.CONFIG_DIR_NAME = ".homeassistant"

Definition at line 46 of file config.py.

◆ DEFAULT_CONFIG

string homeassistant.config.DEFAULT_CONFIG
Initial value:
1 = f"""
2 # Loads default set of integrations. Do not remove.
3 default_config:
4 
5 # Load frontend themes from the themes folder
6 frontend:
7  themes: !include_dir_merge_named themes
8 
9 automation: !include {AUTOMATION_CONFIG_PATH}
10 script: !include {SCRIPT_CONFIG_PATH}
11 scene: !include {SCENE_CONFIG_PATH}
12 """

Definition at line 57 of file config.py.

◆ DEFAULT_SECRETS

string homeassistant.config.DEFAULT_SECRETS
Initial value:
1 = """
2 # Use this file to store secrets like usernames and passwords.
3 # Learn more at https://www.home-assistant.io/docs/configuration/secrets/
4 some_password: welcome
5 """

Definition at line 69 of file config.py.

◆ INTEGRATION_LOAD_EXCEPTIONS

tuple homeassistant.config.INTEGRATION_LOAD_EXCEPTIONS = (IntegrationNotFound, RequirementsNotFound)

Definition at line 53 of file config.py.

◆ LOAD_EXCEPTIONS

tuple homeassistant.config.LOAD_EXCEPTIONS = (ImportError, FileNotFoundError)

Definition at line 52 of file config.py.

◆ RE_ASCII

homeassistant.config.RE_ASCII = re.compile(r"\033\[[^m]*m")

Definition at line 43 of file config.py.

◆ RE_YAML_ERROR

homeassistant.config.RE_YAML_ERROR = re.compile(r"homeassistant\.util\.yaml")

Definition at line 42 of file config.py.

◆ SAFE_MODE_FILENAME

string homeassistant.config.SAFE_MODE_FILENAME = "safe-mode"

Definition at line 55 of file config.py.

◆ SCENE_CONFIG_PATH

string homeassistant.config.SCENE_CONFIG_PATH = "scenes.yaml"

Definition at line 50 of file config.py.

◆ SCRIPT_CONFIG_PATH

string homeassistant.config.SCRIPT_CONFIG_PATH = "scripts.yaml"

Definition at line 49 of file config.py.

◆ TTS_92

string homeassistant.config.TTS_92
Initial value:
1 = """
2 tts:
3  - platform: google_translate
4  service_name: google_say
5 """

Definition at line 78 of file config.py.

◆ TTS_PRE_92

string homeassistant.config.TTS_PRE_92
Initial value:
1 = """
2 tts:
3  - platform: google
4 """

Definition at line 74 of file config.py.

◆ VERSION_FILE

string homeassistant.config.VERSION_FILE = ".HA_VERSION"

Definition at line 45 of file config.py.

◆ YAML_CONFIG_FILE

string homeassistant.config.YAML_CONFIG_FILE = "configuration.yaml"

Definition at line 44 of file config.py.