Classes
class	ReloadServiceHelper

class	SelectedEntities

class	ServiceParams

class	ServiceTargetSelector

Functions
None	_async_admin_handler (HomeAssistant hass, HassJob[[ServiceCall], Awaitable[None]\|None] service_job, ServiceCall call)

dict[str, ModuleType]	_base_components ()

def	_EntityT

list[Entity]	_get_permissible_entity_candidates (ServiceCall call, dict[str, Entity] entities, Callable[[str, str], bool]\|None entity_perms, bool target_all_entities, set[str]\|None all_referenced)

ServiceResponse	_handle_entity_call (HomeAssistant hass, Entity entity, str\|HassJob func, dict\|ServiceCall data, Context context)

TypeGuard[str\|list[str]]	_has_match (str\|list[str]\|None ids)

JSON_TYPE	_load_services_file (HomeAssistant hass, Integration integration)

list[JSON_TYPE]	_load_services_files (HomeAssistant hass, Iterable[Integration] integrations)

Any	_validate_option_or_feature (str option_or_feature, str label)

None	async_call_from_config (HomeAssistant hass, ConfigType config, bool blocking=False, TemplateVarsType variables=None, bool validate_config=True, Context\|None context=None)

set[str]	async_extract_config_entry_ids (HomeAssistant hass, ServiceCall service_call, bool expand_group=True)

set[str]	async_extract_entity_ids (HomeAssistant hass, ServiceCall service_call, bool expand_group=True)

SelectedEntities	async_extract_referenced_entity_ids (HomeAssistant hass, ServiceCall service_call, bool expand_group=True)

dict[str, dict[str, Any]]	async_get_all_descriptions (HomeAssistant hass)

dict[str, Any]\|None	async_get_cached_service_description (HomeAssistant hass, str domain, str service)

ServiceParams	async_prepare_call_from_config (HomeAssistant hass, ConfigType config, TemplateVarsType variables=None, bool validate_config=False)

None	async_register_admin_service (HomeAssistant hass, str domain, str service, Callable[[ServiceCall], Awaitable[None]\|None] service_func, VolSchemaType schema=vol.Schema({}, extra=vol.PREVENT_EXTRA))

None	async_register_entity_service (HomeAssistant hass, str domain, str name, *dict[str, Entity] entities, str\|Callable[..., Any] func, HassJobType\|None job_type, Iterable[int]\|None required_features=None, VolDictType\|VolSchemaType\|None schema, SupportsResponse supports_response=SupportsResponse.NONE)

None	async_set_service_schema (HomeAssistant hass, str domain, str service, dict[str, Any] schema)

None	call_from_config (HomeAssistant hass, ConfigType config, bool blocking=False, TemplateVarsType variables=None, bool validate_config=True)

EntityServiceResponse\|None	entity_service_call (HomeAssistant hass, dict[str, Entity] registered_entities, str\|HassJob func, ServiceCall call, Iterable[int]\|None required_features=None)

set[str]	extract_entity_ids (HomeAssistant hass, ServiceCall service_call, bool expand_group=True)

dict[Any, Any]	remove_entity_service_fields (ServiceCall call)

str	starts_with_dot (str key)

Any	validate_attribute_option (str attribute_option)

Any	validate_supported_feature (str supported_feature)

Callable[[Callable[[ServiceCall], Any]], Callable[[ServiceCall], Any]]	verify_domain_control (HomeAssistant hass, str domain)

Variables
	_FIELD_SCHEMA

	_LOGGER = logging.getLogger(__name__)

	_SECTION_SCHEMA

	_SERVICE_SCHEMA

	_SERVICES_SCHEMA

string	CONF_SERVICE_ENTITY_ID = "entity_id"

Detailed Description

Service calling related helpers.

Function Documentation

◆ _async_admin_handler()

None homeassistant.helpers.service._async_admin_handler	(	HomeAssistant	hass,
		HassJob[[ServiceCall], Awaitable[None] \| None]	service_job,
		ServiceCall	call
	)

private

Run an admin service.

Definition at line 1095 of file service.py.

◆ _base_components()

dict[str, ModuleType] homeassistant.helpers.service._base_components ( )

private

Return a cached lookup of base components.

Definition at line 85 of file service.py.

◆ _EntityT()

def homeassistant.helpers.service._EntityT

private

Definition at line 451 of file service.py.

◆ _get_permissible_entity_candidates()

list[Entity] homeassistant.helpers.service._get_permissible_entity_candidates	(	ServiceCall	call,
		dict[str, Entity]	entities,
		Callable[[str, str], bool] \| None	entity_perms,
		bool	target_all_entities,
		set[str] \| None	all_referenced
	)

private

Get entity candidates that the user is allowed to access.

Definition at line 871 of file service.py.

◆ _handle_entity_call()

ServiceResponse homeassistant.helpers.service._handle_entity_call	(	HomeAssistant	hass,
		Entity	entity,
		str \| HassJob	func,
		dict \| ServiceCall	data,
		Context	context
	)

private

Handle calling service method.

Definition at line 1055 of file service.py.

◆ _has_match()

TypeGuard[str | list[str]] homeassistant.helpers.service._has_match ( str | list[str] | None ids )

private

Check if ids can match anything.

Definition at line 499 of file service.py.

◆ _load_services_file()

JSON_TYPE homeassistant.helpers.service._load_services_file	(	HomeAssistant	hass,
		Integration	integration
	)

private

Load services file for an integration.

Definition at line 658 of file service.py.

◆ _load_services_files()

list[JSON_TYPE] homeassistant.helpers.service._load_services_files	(	HomeAssistant	hass,
		Iterable[Integration]	integrations
	)

private

Load service files for multiple integrations.

Definition at line 681 of file service.py.

◆ _validate_option_or_feature()

Any homeassistant.helpers.service._validate_option_or_feature	(	str	option_or_feature,
		str	label
	)

private

Validate attribute option or supported feature.

Definition at line 129 of file service.py.

◆ async_call_from_config()

None homeassistant.helpers.service.async_call_from_config	(	HomeAssistant	hass,
		ConfigType	config,
		bool	blocking = `False`,
		TemplateVarsType	variables = `None`,
		bool	validate_config = `True`,
		Context \| None	context = `None`
	)

Call a service based on a config hash.

Definition at line 324 of file service.py.

◆ async_extract_config_entry_ids()

set[str] homeassistant.helpers.service.async_extract_config_entry_ids	(	HomeAssistant	hass,
		ServiceCall	service_call,
		bool	expand_group = `True`
	)

Extract referenced config entry ids from a service call.

Definition at line 633 of file service.py.

◆ async_extract_entity_ids()

set[str] homeassistant.helpers.service.async_extract_entity_ids	(	HomeAssistant	hass,
		ServiceCall	service_call,
		bool	expand_group = `True`
	)

Extract a set of entity ids from a service call.

Will convert group entity ids to the entity ids it represents.

Definition at line 488 of file service.py.

◆ async_extract_referenced_entity_ids()

SelectedEntities homeassistant.helpers.service.async_extract_referenced_entity_ids	(	HomeAssistant	hass,
		ServiceCall	service_call,
		bool	expand_group = `True`
	)

Extract referenced entity IDs from a service call.

Definition at line 505 of file service.py.

◆ async_get_all_descriptions()

dict[str, dict[str, Any]] homeassistant.helpers.service.async_get_all_descriptions ( HomeAssistant hass )

Return descriptions (i.e. user documentation) for all service calls.

Definition at line 697 of file service.py.

◆ async_get_cached_service_description()

dict[str, Any] \| None homeassistant.helpers.service.async_get_cached_service_description	(	HomeAssistant	hass,
		str	domain,
		str	service
	)

Return the cached description for a service.

Definition at line 689 of file service.py.

◆ async_prepare_call_from_config()

ServiceParams homeassistant.helpers.service.async_prepare_call_from_config	(	HomeAssistant	hass,
		ConfigType	config,
		TemplateVarsType	variables = `None`,
		bool	validate_config = `False`
	)

Prepare to call a service based on a config hash.

Definition at line 347 of file service.py.

◆ async_register_admin_service()

None homeassistant.helpers.service.async_register_admin_service	(	HomeAssistant	hass,
		str	domain,
		str	service,
		Callable[[ServiceCall], Awaitable[None] \| None]	service_func,
		VolSchemaType	schema = `vol.Schema({}, extra=vol.PREVENT_EXTRA)`
	)

Register a service that requires admin access.

Definition at line 1115 of file service.py.

◆ async_register_entity_service()

None homeassistant.helpers.service.async_register_entity_service	(	HomeAssistant	hass,
		str	domain,
		str	name,
		*dict[str, Entity]	entities,
		str \| Callable[..., Any]	func,
		HassJobType \| None	job_type,
		Iterable[int] \| None	required_features = `None`,
		VolDictType \| VolSchemaType \| None	schema,
		SupportsResponse	supports_response = `SupportsResponse.NONE`
	)

Help registering an entity service.

This is called by EntityComponent.async_register_entity_service and
EntityPlatform.async_register_entity_service and should not be called
directly by integrations.

Definition at line 1258 of file service.py.

◆ async_set_service_schema()

None homeassistant.helpers.service.async_set_service_schema	(	HomeAssistant	hass,
		str	domain,
		str	service,
		dict[str, Any]	schema
	)

Register a description for a service.

Definition at line 842 of file service.py.

◆ call_from_config()

None homeassistant.helpers.service.call_from_config	(	HomeAssistant	hass,
		ConfigType	config,
		bool	blocking = `False`,
		TemplateVarsType	variables = `None`,
		bool	validate_config = `True`
	)

Call a service based on a config hash.

Definition at line 309 of file service.py.

◆ entity_service_call()

EntityServiceResponse \| None homeassistant.helpers.service.entity_service_call	(	HomeAssistant	hass,
		dict[str, Entity]	registered_entities,
		str \| HassJob	func,
		ServiceCall	call,
		Iterable[int] \| None	required_features = `None`
	)

Handle an entity service call.

Calls all platforms simultaneously.

Definition at line 919 of file service.py.

◆ extract_entity_ids()

set[str] homeassistant.helpers.service.extract_entity_ids	(	HomeAssistant	hass,
		ServiceCall	service_call,
		bool	expand_group = `True`
	)

Extract a list of entity ids from a service call.

Will convert group entity ids to the entity ids it represents.

Definition at line 438 of file service.py.

◆ remove_entity_service_fields()

dict[Any, Any] homeassistant.helpers.service.remove_entity_service_fields ( ServiceCall call )

Remove entity service fields.

Definition at line 831 of file service.py.

◆ starts_with_dot()

str homeassistant.helpers.service.starts_with_dot ( str key )

Check if key starts with dot.

Definition at line 201 of file service.py.

◆ validate_attribute_option()

Any homeassistant.helpers.service.validate_attribute_option ( str attribute_option )

Validate attribute option.

Definition at line 157 of file service.py.

◆ validate_supported_feature()

Any homeassistant.helpers.service.validate_supported_feature ( str supported_feature )

Validate supported feature.

Definition at line 162 of file service.py.

◆ verify_domain_control()

Callable[[Callable[[ServiceCall], Any]], Callable[[ServiceCall], Any]] homeassistant.helpers.service.verify_domain_control	(	HomeAssistant	hass,
		str	domain
	)

Ensure permission to access any entity under domain in service call.

Definition at line 1137 of file service.py.

Variable Documentation

◆ _FIELD_SCHEMA

homeassistant.helpers.service._FIELD_SCHEMA

private

Initial value:

 =  vol.Schema(
     {
         vol.Optional("filter"): {
             vol.Optional("attribute"): {
                 vol.Required(str): [vol.All(str, validate_attribute_option)],
             },
             vol.Optional("supported_features"): [
                 vol.All(str, validate_supported_feature)
             ],
         },
     },
     extra=vol.ALLOW_EXTRA,
 )

Definition at line 169 of file service.py.

◆ _LOGGER

homeassistant.helpers.service._LOGGER = logging.getLogger(__name__)

private

Definition at line 74 of file service.py.

◆ _SECTION_SCHEMA

homeassistant.helpers.service._SECTION_SCHEMA

private

Initial value:

 =  vol.Schema(
     {
         vol.Required("fields"): vol.Schema({str: _FIELD_SCHEMA}),
     },
     extra=vol.ALLOW_EXTRA,
 )

Definition at line 183 of file service.py.

◆ _SERVICE_SCHEMA

homeassistant.helpers.service._SERVICE_SCHEMA

private

Initial value:

 =  vol.Schema(
     {
         vol.Optional("target"): vol.Any(TargetSelector.CONFIG_SCHEMA, None),
         vol.Optional("fields"): vol.Schema(
             {str: vol.Any(_SECTION_SCHEMA, _FIELD_SCHEMA)}
         ),
     },
     extra=vol.ALLOW_EXTRA,
 )

Definition at line 190 of file service.py.

◆ _SERVICES_SCHEMA

homeassistant.helpers.service._SERVICES_SCHEMA

private

Initial value:

 =  vol.Schema(
     {
         vol.Remove(vol.All(str, starts_with_dot)): object,
         cv.slug: vol.Any(None, _SERVICE_SCHEMA),
     }
 )

Definition at line 208 of file service.py.

◆ CONF_SERVICE_ENTITY_ID

string homeassistant.helpers.service.CONF_SERVICE_ENTITY_ID = "entity_id"

Definition at line 72 of file service.py.

Home Assistant Unofficial Reference 2024.12.1

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _async_admin_handler()

◆ _base_components()

◆ _EntityT()

◆ _get_permissible_entity_candidates()

◆ _handle_entity_call()

◆ _has_match()

◆ _load_services_file()

◆ _load_services_files()

◆ _validate_option_or_feature()

◆ async_call_from_config()

◆ async_extract_config_entry_ids()

◆ async_extract_entity_ids()

◆ async_extract_referenced_entity_ids()

◆ async_get_all_descriptions()

◆ async_get_cached_service_description()

◆ async_prepare_call_from_config()

◆ async_register_admin_service()

◆ async_register_entity_service()

◆ async_set_service_schema()

◆ call_from_config()

◆ entity_service_call()

◆ extract_entity_ids()

◆ remove_entity_service_fields()

◆ starts_with_dot()

◆ validate_attribute_option()

◆ validate_supported_feature()

◆ verify_domain_control()

Variable Documentation

◆ _FIELD_SCHEMA

◆ _LOGGER

◆ _SECTION_SCHEMA

◆ _SERVICE_SCHEMA

◆ _SERVICES_SCHEMA

◆ CONF_SERVICE_ENTITY_ID