Service Calls

class ServiceRegistry:
    """Offer the services over the eventbus."""
    
    def __init__(self, hass: HomeAssistant) -> None:
        """Initialize a service registry."""
        self._services: dict[str, dict[str, Service]] = {}
        self._hass = hass

class Service:
    """Representation of a callable service."""
    
    def __init__(
        self,
        func: Callable[[ServiceCall], Coroutine[Any, Any, ServiceResponse] | ServiceResponse | None],
        schema: VolSchemaType | None,
        domain: str,
        service: str,
        context: Context | None = None,
        supports_response: SupportsResponse = SupportsResponse.NONE,
        job_type: HassJobType | None = None,
        description_placeholders: Mapping[str, str] | None = None,
    ) -> None:
        self.job = HassJob(func, f"service {domain}.{service}", job_type=job_type)
        self.schema = schema
        self.supports_response = supports_response
        self.description_placeholders = description_placeholders

class ServiceCall:
    """Representation of a call to a service."""
    
    def __init__(
        self,
        hass: HomeAssistant,
        domain: str,
        service: str,
        data: dict[str, Any] | None = None,
        context: Context | None = None,
        return_response: bool = False,
    ) -> None:
        self.hass = hass
        self.domain = domain
        self.service = service
        self.data = ReadOnlyDict(data or {})
        self.context = context or Context()
        self.return_response = return_response

class SupportsResponse(enum.StrEnum):
    """Service call response configuration."""
    
    NONE = "none"        # No response data (default)
    OPTIONAL = "optional" # Response data when requested
    ONLY = "only"        # Must always request response

async def async_call(
    self,
    domain: str,
    service: str,
    service_data: dict[str, Any] | None = None,
    blocking: bool = False,
    context: Context | None = None,
    target: dict[str, Any] | None = None,
    return_response: bool = False,
) -> ServiceResponse:
    """Call a service."""
    context = context or Context()
    service_data = service_data or {}
    
    # Lookup service handler
    try:
        handler = self._services[domain][service]
    except KeyError:
        domain = domain.lower()
        service = service.lower()
        try:
            handler = self._services[domain][service]
        except KeyError:
            raise ServiceNotFound(domain, service) from None
    
    # Validate response support
    if return_response and handler.supports_response is SupportsResponse.NONE:
        raise ServiceValidationError("Service does not support response")
    
    # Merge target into service_data
    if target:
        service_data.update(target)
    
    # Validate service data
    if handler.schema:
        processed_data = handler.schema(service_data)
    else:
        processed_data = service_data
    
    # Create ServiceCall object
    service_call = ServiceCall(
        self._hass, domain, service, processed_data, context, return_response
    )
    
    # Fire call_service event
    self._hass.bus.async_fire_internal(
        EVENT_CALL_SERVICE,
        {
            ATTR_DOMAIN: domain,
            ATTR_SERVICE: service,
            ATTR_SERVICE_DATA: service_data,
        },
        context=context,
    )
    
    # Execute service
    coro = self._execute_service(handler, service_call)
    if not blocking:
        # Run in background
        self._hass.async_create_task_internal(
            self._run_service_call_catch_exceptions(coro, service_call),
            f"service call background {service_call.domain}.{service_call.service}",
            eager_start=True,
        )
        return None
    
    # Wait for completion
    response_data = await coro
    if not return_response:
        return None
    return response_data

async def _execute_service(
    self, handler: Service, service_call: ServiceCall
) -> ServiceResponse:
    """Execute a service."""
    job = handler.job
    target = job.target
    
    if job.job_type is HassJobType.Coroutinefunction:
        # Async function - await directly
        return await target(service_call)
    
    if job.job_type is HassJobType.Callback:
        # Callback - call immediately
        return target(service_call)
    
    # Executor job - run in thread pool
    return await self._hass.async_add_executor_job(target, service_call)