Add TCL (Transports en commun à Lyon) integration

New integration for Lyon public transport and Vélo'v bike-sharing data.
Supports config subentries for transit stops (with estimated/theoretical
passage merging) and Vélo'v stations (with electrical/mechanical bike
breakdown). Includes reconfiguration flow for credentials.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Crocmagnon

CODEOWNERS

@@ -0,0 +1,44 @@
+"""The TCL integration."""
+
+from __future__ import annotations
+
+from transports_commun_lyon import TCLClient
+
+from homeassistant.const import CONF_PASSWORD, CONF_USERNAME, Platform
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+from .coordinator import TCLConfigEntry, TCLCoordinator
+
+PLATFORMS: list[Platform] = [Platform.SENSOR]
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: TCLConfigEntry) -> bool:
+    """Set up TCL from a config entry."""
+    session = async_get_clientsession(hass)
+    client = TCLClient(
+        session=session,
+        username=entry.data.get(CONF_USERNAME),
+        password=entry.data.get(CONF_PASSWORD),
+    )
+
+    coordinator = TCLCoordinator(hass, entry, client)
+    await coordinator.async_config_entry_first_refresh()
+
+    entry.runtime_data = coordinator
+
+    entry.async_on_unload(entry.add_update_listener(async_update_entry))
+
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+
+    return True
+
+
+async def async_update_entry(hass: HomeAssistant, entry: TCLConfigEntry) -> None:
+    """Handle config entry update (e.g., subentry changes)."""
+    await hass.config_entries.async_reload(entry.entry_id)
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: TCLConfigEntry) -> bool:
+    """Unload a config entry."""
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

homeassistant/components/tcl/__init__.py

@@ -0,0 +1,328 @@
+"""Config flow for the TCL integration."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from transports_commun_lyon import PassageType, TCLClient
+import voluptuous as vol
+
+from homeassistant.config_entries import (
+    ConfigEntry,
+    ConfigFlow,
+    ConfigFlowResult,
+    ConfigSubentryFlow,
+    SubentryFlowResult,
+)
+from homeassistant.const import CONF_NAME, CONF_PASSWORD, CONF_USERNAME
+from homeassistant.core import callback
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+from .const import (
+    CONF_LINE,
+    CONF_STATION_ID,
+    CONF_STOP_ID,
+    DOMAIN,
+    SUBENTRY_TYPE_STOP,
+    SUBENTRY_TYPE_VELOV,
+)
+
+STEP_USER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Optional(CONF_USERNAME): str,
+        vol.Optional(CONF_PASSWORD): str,
+    }
+)
+
+STEP_REAUTH_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_USERNAME): str,
+        vol.Required(CONF_PASSWORD): str,
+    }
+)
+
+STEP_STOP_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_LINE): str,
+        vol.Required(CONF_STOP_ID): vol.Coerce(int),
+        vol.Optional(CONF_NAME): str,
+    }
+)
+
+STEP_VELOV_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_STATION_ID): vol.Coerce(int),
+    }
+)
+
+
+class TCLConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for TCL."""
+
+    VERSION = 1
+
+    @classmethod
+    @callback
+    def async_get_supported_subentry_types(
+        cls, config_entry: ConfigEntry
+    ) -> dict[str, type[ConfigSubentryFlow]]:
+        """Return subentry types supported by this integration."""
+        return {
+            SUBENTRY_TYPE_STOP: StopSubentryFlowHandler,
+            SUBENTRY_TYPE_VELOV: VelovSubentryFlowHandler,
+        }
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle the initial step."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            self._async_abort_entries_match(
+                {CONF_USERNAME: user_input.get(CONF_USERNAME)}
+            )
+
+            data: dict[str, Any] = {}
+            if username := user_input.get(CONF_USERNAME):
+                data[CONF_USERNAME] = username
+            if password := user_input.get(CONF_PASSWORD):
+                data[CONF_PASSWORD] = password
+
+            if not await self._test_connection(data):
+                errors["base"] = "cannot_connect"
+            else:
+                return self.async_create_entry(title="TCL", data=data)
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=STEP_USER_DATA_SCHEMA,
+            errors=errors,
+        )
+
+    async def async_step_reconfigure(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle reconfiguration of the main config entry."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            data = {
+                CONF_USERNAME: user_input[CONF_USERNAME],
+                CONF_PASSWORD: user_input[CONF_PASSWORD],
+            }
+
+            if not await self._test_connection(data):
+                errors["base"] = "cannot_connect"
+            else:
+                return self.async_update_reload_and_abort(
+                    self._get_reconfigure_entry(),
+                    data=data,
+                )
+
+        return self.async_show_form(
+            step_id="reconfigure",
+            data_schema=self.add_suggested_values_to_schema(
+                STEP_USER_DATA_SCHEMA,
+                self._get_reconfigure_entry().data,
+            ),
+            errors=errors,
+        )
+
+    async def async_step_reauth(
+        self, entry_data: Mapping[str, Any]
+    ) -> ConfigFlowResult:
+        """Handle initiation of re-authentication."""
+        return await self.async_step_reauth_confirm()
+
+    async def async_step_reauth_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle re-authentication with new credentials."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            data = {
+                CONF_USERNAME: user_input[CONF_USERNAME],
+                CONF_PASSWORD: user_input[CONF_PASSWORD],
+            }
+            if not await self._test_connection(data):
+                errors["base"] = "cannot_connect"
+            else:
+                return self.async_update_reload_and_abort(
+                    self._get_reauth_entry(),
+                    data=data,
+                )
+
+        return self.async_show_form(
+            step_id="reauth_confirm",
+            data_schema=STEP_REAUTH_DATA_SCHEMA,
+            errors=errors,
+        )
+
+    async def _test_connection(self, data: dict[str, Any]) -> bool:
+        """Test connectivity by making a dummy API call."""
+        session = async_get_clientsession(self.hass)
+        client = TCLClient(
+            session=session,
+            username=data.get(CONF_USERNAME),
+            password=data.get(CONF_PASSWORD),
+        )
+        try:
+            if data.get(CONF_USERNAME):
+                await client.get_passages(
+                    ligne="__test__", stop_id=0, passage_type=PassageType.ESTIMATED
+                )
+            else:
+                await client.get_velov_station(0)
+        except Exception:  # noqa: BLE001
+            return False
+        return True
+
+
+class StopSubentryFlowHandler(ConfigSubentryFlow):
+    """Handle a subentry flow for adding/editing a TCL stop."""
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> SubentryFlowResult:
+        """Handle the user step to add a new stop."""
+        entry = self._get_entry()
+        if not entry.data.get(CONF_USERNAME):
+            return self.async_abort(reason="auth_required")
+
+        if user_input is not None:
+            line = user_input[CONF_LINE]
+            stop_id = user_input[CONF_STOP_ID]
+            unique_id = f"{line}_{stop_id}"
+
+            for subentry in entry.subentries.values():
+                if subentry.unique_id == unique_id:
+                    return self.async_abort(reason="already_configured")
+
+            name = user_input.get(CONF_NAME) or f"{line} - Stop {stop_id}"
+            return self.async_create_entry(
+                title=name,
+                data={CONF_LINE: line, CONF_STOP_ID: stop_id},
+                unique_id=unique_id,
+            )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=STEP_STOP_DATA_SCHEMA,
+        )
+
+    async def async_step_reconfigure(
+        self, user_input: dict[str, Any] | None = None
+    ) -> SubentryFlowResult:
+        """Handle reconfiguration of an existing stop."""
+        subentry = self._get_reconfigure_subentry()
+
+        if user_input is not None:
+            entry = self._get_entry()
+            line = user_input[CONF_LINE]
+            stop_id = user_input[CONF_STOP_ID]
+            name = user_input.get(CONF_NAME) or f"{line} - Stop {stop_id}"
+            self._async_update(
+                entry,
+                subentry,
+                data={CONF_LINE: line, CONF_STOP_ID: stop_id},
+                title=name,
+            )
+            return self.async_abort(reason="reconfigure_successful")
+
+        return self.async_show_form(
+            step_id="reconfigure",
+            data_schema=self.add_suggested_values_to_schema(
+                STEP_STOP_DATA_SCHEMA,
+                {
+                    CONF_LINE: subentry.data[CONF_LINE],
+                    CONF_STOP_ID: subentry.data[CONF_STOP_ID],
+                    CONF_NAME: subentry.title,
+                },
+            ),
+        )
+
+
+class VelovSubentryFlowHandler(ConfigSubentryFlow):
+    """Handle a subentry flow for adding/editing a Vélo'v station."""
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> SubentryFlowResult:
+        """Handle the user step to add a new Vélo'v station."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            station_id = user_input[CONF_STATION_ID]
+            unique_id = str(station_id)
+
+            entry = self._get_entry()
+            for subentry in entry.subentries.values():
+                if subentry.unique_id == unique_id:
+                    return self.async_abort(reason="already_configured")
+
+            try:
+                title = await self._fetch_station_title(station_id)
+            except Exception:  # noqa: BLE001
+                errors["base"] = "cannot_connect"
+            else:
+                if title is None:
+                    errors[CONF_STATION_ID] = "station_not_found"
+                else:
+                    return self.async_create_entry(
+                        title=title,
+                        data={CONF_STATION_ID: station_id},
+                        unique_id=unique_id,
+                    )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=STEP_VELOV_DATA_SCHEMA,
+            errors=errors,
+        )
+
+    async def async_step_reconfigure(
+        self, user_input: dict[str, Any] | None = None
+    ) -> SubentryFlowResult:
+        """Handle reconfiguration of an existing Vélo'v station."""
+        subentry = self._get_reconfigure_subentry()
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            station_id = user_input[CONF_STATION_ID]
+            try:
+                title = await self._fetch_station_title(station_id)
+            except Exception:  # noqa: BLE001
+                errors["base"] = "cannot_connect"
+            else:
+                if title is None:
+                    errors[CONF_STATION_ID] = "station_not_found"
+                else:
+                    entry = self._get_entry()
+                    self._async_update(
+                        entry,
+                        subentry,
+                        data={CONF_STATION_ID: station_id},
+                        title=title,
+                    )
+                    return self.async_abort(reason="reconfigure_successful")
+
+        return self.async_show_form(
+            step_id="reconfigure",
+            data_schema=self.add_suggested_values_to_schema(
+                STEP_VELOV_DATA_SCHEMA,
+                {CONF_STATION_ID: subentry.data[CONF_STATION_ID]},
+            ),
+            errors=errors,
+        )
+
+    async def _fetch_station_title(self, station_id: int) -> str | None:
+        """Fetch the station name from the API, returning None if not found."""
+        session = async_get_clientsession(self.hass)
+        client = TCLClient(session=session)
+        station = await client.get_velov_station(station_id)
+        if station is None:
+            return None
+        return station.name

homeassistant/components/tcl/config_flow.py

@@ -0,0 +1,15 @@
+"""Constants for the TCL integration."""
+
+import logging
+
+DOMAIN = "tcl"
+LOGGER = logging.getLogger(__package__)
+
+SUBENTRY_TYPE_STOP = "stop"
+SUBENTRY_TYPE_VELOV = "velov"
+
+CONF_LINE = "line"
+CONF_STOP_ID = "stop_id"
+CONF_STATION_ID = "station_id"
+
+MAX_PASSAGES_PER_LINE = 3