Give the mypy gate something to check

Reported by Codex on #19. The mypy job added with the typed coordinator
passed on its first run, which should have been the tell: Home Assistant
was not installed for it and ignore_missing_imports was on, so every
homeassistant.* import resolved to Any. WineCellarData derives from
DataUpdateCoordinator, a class deriving from Any inherits Any for every
member it does not declare, and coordinator.data was therefore Any at all
five sensors, both views and the diagnostics - the exact call sites
DataUpdateCoordinator[CellarData] was introduced to type.

Confirmed before fixing: reveal_type(coordinator.data) reported Any, and
coordinator.data["definitely_not_a_key"] was accepted in silence. The job
reported success over code it had never checked, which is worse than no job
at all, because the PR claimed those errors were now impossible.

Resolving Home Assistant's real types found four genuine bugs the Any gate
had accepted: the four entity classes derived from a bare CoordinatorEntity,
so their coordinator was DataUpdateCoordinator[dict[str, Any]] and
CellarLastSyncSensor read a last_success that type does not have.

  * requirements_mypy.txt installs a pinned Home Assistant for the job;
    the test matrix keeps its light stub harness and its seconds-long run.
  * No ignore_missing_imports. disallow_any_unimported and warn_return_any
    make an unresolved import fail rather than degrade - without Home
    Assistant the job now reports 84 errors instead of success.
  * stubs/cellartracker for the one dependency that ships no py.typed:
    RateLimited derives from its CannotConnect, so an Any base there is the
    same hole one dependency further down.
  * tests/typing_gate.py asserts what the gate is supposed to guarantee in
    the checker's own terms - assert_type fails on Any, and the
    misspelled-key checks are type: ignore comments that warn_unused_ignores
    turns into errors if they ever stop being necessary.
  * tests/test_mypy_gate.py pins the wiring from pytest's side.

Every reader of the payload is now typed rather than Any, which cost the
four CoordinatorEntity[WineCellarData] parameterisations, a Literal key on
the drink-window counters, and one honest redeclaration: Home Assistant
types data as the payload and then assigns None to it before the first
refresh, so the F-15 guards read as dead code until the coordinator says so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LLPEGFSy3fLEuXNUPAPWR4

Author: claude

.github/workflows/ci.yml

@@ -60,9 +60,16 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          # Home Assistant 2026.2 requires 3.13; the runtime matrix above still
+          # covers 3.12, which is what the integration has to keep working on.
+          python-version: "3.13"
           cache: pip
-      - run: pip install mypy==1.18.2 -r requirements_test.txt
+
+      # Home Assistant itself, not just mypy. Without it every homeassistant.*
+      # import resolves to Any, classes deriving from Any inherit Any for
+      # everything, and the job reports success over code it never checked.
+      - run: pip install -r requirements_mypy.txt
+
       - run: mypy
 
   hassfest:

custom_components/cellar_tracker/__init__.py

@@ -3,11 +3,11 @@
 from pathlib import Path
 
 from homeassistant.components.http import StaticPathConfig
-from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import config_validation as cv
+from homeassistant.helpers.typing import ConfigType
 
-from .cellar_data import WineCellarData
+from .cellar_data import CellarTrackerConfigEntry, WineCellarData
 from .const import DASHBOARD_FILENAME, DASHBOARD_URL, DOMAIN, PLATFORMS
 from .views import CellarTrackerInventoryView, CellarTrackerSettingsView
 
@@ -21,7 +21,7 @@
 # integration was installed - HACS or a manual copy - the page is present.
 DASHBOARD_FILE = Path(__file__).parent / "www" / DASHBOARD_FILENAME
 
-async def async_setup(hass: HomeAssistant, config: dict) -> bool:
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the component.
 
     Home Assistant calls this once, before the first config entry. The views
@@ -62,7 +62,7 @@ async def _async_register_dashboard(hass: HomeAssistant) -> None:
         [StaticPathConfig(DASHBOARD_URL, str(DASHBOARD_FILE), False)]
     )
 
-async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+async def async_setup_entry(hass: HomeAssistant, entry: CellarTrackerConfigEntry) -> bool:
     """Set up CellarTracker from a config entry."""
     coordinator = WineCellarData(hass, entry)
     await coordinator.async_config_entry_first_refresh()
@@ -78,14 +78,19 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
 
     return True
 
-async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+async def async_unload_entry(hass: HomeAssistant, entry: CellarTrackerConfigEntry) -> bool:
     """Unload a config entry."""
     unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
     if unload_ok:
         # Cleared so the views stop seeing this entry immediately, and so a
         # setup that failed before assigning it unloads without a KeyError.
-        entry.runtime_data = None
+        # The ignore is the price of the alias: runtime_data is typed as the
+        # coordinator because that is what every reader wants it to be, and
+        # this is the one line where it is deliberately not one. Home Assistant
+        # deletes the attribute itself once unload returns, so this only
+        # narrows the window in which a request could still find the entry.
+        entry.runtime_data = None  # type: ignore[assignment]
     return unload_ok
 
-async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
+async def update_listener(hass: HomeAssistant, entry: CellarTrackerConfigEntry) -> None:
     await hass.config_entries.async_reload(entry.entry_id)

custom_components/cellar_tracker/cellar_data.py

@@ -256,6 +256,17 @@ async def async_fetch_inventory_payload(
 class WineCellarData(DataUpdateCoordinator[CellarData]):
     """Fetch and process CellarTracker inventory data."""
 
+    # Home Assistant declares `data` as the payload itself and then assigns
+    # None to it until the first refresh completes - a white lie the framework
+    # tells with a `type: ignore` of its own. Every reader here already guards
+    # for that (see F-15: a state read must survive a coordinator with no data
+    # yet), and without this redeclaration mypy calls those guards dead code,
+    # because a TypedDict with required keys can never be falsy.
+    #
+    # Stated once here rather than narrowed at each of the five call sites. If
+    # Home Assistant ever types it honestly, warn_unused_ignores will say so.
+    data: CellarData | None  # type: ignore[assignment]
+
     def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
         """Initialize the data coordinator."""
         self._hass = hass
@@ -350,10 +361,6 @@ def compact_body(self) -> bytes:
         """
         return self._compact_body
 
-    # Declared because the base class is unresolved without Home Assistant
-    # installed, so mypy has nothing to infer this from.
-    update_interval: timedelta | None
-
     def _backoff_for(self, retry_after: int | None) -> timedelta:
         """How long to wait after being throttled.
 

custom_components/cellar_tracker/config_flow.py

@@ -41,7 +41,7 @@
 REAUTH_SCHEMA = vol.Schema({vol.Required(CONF_PASSWORD): str})
 
 
-class CellarTrackerConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):  # type: ignore[call-arg]
+class CellarTrackerConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     """Handle a config flow for CellarTracker."""
 
     VERSION = 1

custom_components/cellar_tracker/diagnostics.py

@@ -18,10 +18,11 @@
 from typing import Any
 
 from homeassistant.components.diagnostics import async_redact_data
-from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import CONF_PASSWORD, CONF_USERNAME
 from homeassistant.core import HomeAssistant
 
+from .cellar_data import CellarTrackerConfigEntry
+
 # "title" as well as the credential keys: async_step_user names the entry
 # after the account, so the title *is* the username for every entry this
 # integration creates. Redacting only the username field would have published
@@ -48,12 +49,12 @@
 
 
 async def async_get_config_entry_diagnostics(
-    hass: HomeAssistant, entry: ConfigEntry
+    hass: HomeAssistant, entry: CellarTrackerConfigEntry
 ) -> dict[str, Any]:
     """Return redacted diagnostics for a config entry."""
     coordinator = entry.runtime_data
-    data = coordinator.data or {}
-    bottles = data.get("bottles") or []
+    data = coordinator.data
+    bottles = [] if data is None else data.get("bottles") or []
 
     return {
         "entry": async_redact_data(entry.as_dict(), TO_REDACT),
@@ -64,8 +65,8 @@ async def async_get_config_entry_diagnostics(
             "currency": coordinator.currency,
         },
         "totals": {
-            "total_bottles": data.get("total_bottles"),
-            "total_value": data.get("total_value"),
+            "total_bottles": None if data is None else data.get("total_bottles"),
+            "total_value": None if data is None else data.get("total_value"),
         },
         # Sorted so two reports can be diffed when a schema change is suspected.
         "columns": sorted(bottles[0]) if bottles else [],

custom_components/cellar_tracker/sensor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any
+from datetime import datetime
+from typing import Literal
 
 from homeassistant.components.sensor import (
     SensorDeviceClass,
@@ -14,7 +15,7 @@
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.update_coordinator import CoordinatorEntity
 
-from .cellar_data import CellarTrackerConfigEntry, WineCellarData
+from .cellar_data import CellarData, CellarTrackerConfigEntry, WineCellarData
 from .const import CONF_CURRENCY, DEFAULT_CURRENCY, DOMAIN, normalize_currency
 
 # One typed place for what five constructors used to spell out. The key is
@@ -61,6 +62,21 @@
 DESCRIPTIONS_BY_KEY = {description.key: description for description in SENSOR_DESCRIPTIONS}
 
 
+def _count(
+    data: CellarData | None,
+    key: Literal["total_bottles", "ready_to_drink", "past_drink_window"],
+) -> int:
+    """Read a count from the payload, defaulting rather than raising.
+
+    Both defences are deliberate and covered by F-15. ``data`` is None until
+    the first refresh succeeds, which is the state a sensor is in if its
+    entity is read during a failed setup; and a payload that predates a key -
+    the drink-window counters were added after the totals - has no such key at
+    all. Neither should turn a state read into a traceback.
+    """
+    return 0 if data is None else data.get(key, 0)
+
+
 async def async_setup_entry(
     hass: HomeAssistant,
     entry: CellarTrackerConfigEntry,
@@ -99,7 +115,7 @@ async def async_setup_entry(
     async_add_entities(sensors)
 
 
-class TotalBottlesSensor(CoordinatorEntity, SensorEntity):
+class TotalBottlesSensor(CoordinatorEntity[WineCellarData], SensorEntity):
     """How many bottles the cellar currently holds."""
 
     # Home Assistant composes the friendly name as "<device> <entity>", so the
@@ -116,12 +132,11 @@ def __init__(
         self._attr_device_info = device_info
 
     @property
-    def native_value(self) -> Any:
-        # `or {}`: coordinator.data is None until the first successful refresh.
-        return (self.coordinator.data or {}).get("total_bottles", 0)
+    def native_value(self) -> int:
+        return _count(self.coordinator.data, "total_bottles")
 
 
-class TotalValueSensor(CoordinatorEntity, SensorEntity):
+class TotalValueSensor(CoordinatorEntity[WineCellarData], SensorEntity):
     """What the cellar is worth, in the configured currency.
 
     MONETARY with state_class TOTAL, so Home Assistant keeps a long-term
@@ -147,11 +162,12 @@ def __init__(
         self._attr_native_unit_of_measurement = currency
 
     @property
-    def native_value(self) -> Any:
-        return (self.coordinator.data or {}).get("total_value", 0.0)
+    def native_value(self) -> float:
+        data = self.coordinator.data
+        return 0.0 if data is None else data.get("total_value", 0.0)
 
 
-class _BottleCountSensor(CoordinatorEntity, SensorEntity):
+class _BottleCountSensor(CoordinatorEntity[WineCellarData], SensorEntity):
     """Shared shape for the drink-window counters.
 
     Both are plain counts the coordinator computed during the parse, so they
@@ -161,7 +177,9 @@ class _BottleCountSensor(CoordinatorEntity, SensorEntity):
     """
 
     _attr_has_entity_name = True
-    _data_key: str
+    # A literal union rather than a bare str: it is used to index CellarData,
+    # and only a literal lets the checker confirm the key exists at all.
+    _data_key: Literal["ready_to_drink", "past_drink_window"]
 
     def __init__(
         self, coordinator: WineCellarData, device_info: DeviceInfo, entry_id: str
@@ -172,11 +190,8 @@ def __init__(
         self._attr_device_info = device_info
 
     @property
-    def native_value(self) -> Any:
-        # Defaulted rather than indexed: coordinator.data is None before the
-        # first refresh, and a payload cached by an older version has no such
-        # key at all.
-        return (self.coordinator.data or {}).get(self._data_key, 0)
+    def native_value(self) -> int:
+        return _count(self.coordinator.data, self._data_key)
 
 
 class ReadyToDrinkSensor(_BottleCountSensor):
@@ -191,7 +206,7 @@ class PastDrinkWindowSensor(_BottleCountSensor):
     _data_key = "past_drink_window"
 
 
-class CellarLastSyncSensor(CoordinatorEntity, SensorEntity):
+class CellarLastSyncSensor(CoordinatorEntity[WineCellarData], SensorEntity):
     """When the cellar last synchronised with CellarTracker.
 
     This replaces a status sensor that reported "Connected" or "Empty". After
@@ -219,6 +234,6 @@ def __init__(
         self._attr_device_info = device_info
 
     @property
-    def native_value(self) -> Any:
+    def native_value(self) -> datetime | None:
         """The last successful refresh, or None if none has happened yet."""
         return self.coordinator.last_success

custom_components/cellar_tracker/views.py

@@ -12,7 +12,7 @@
 from .const import CURRENCY_SYMBOLS, DEFAULT_CURRENCY, DOMAIN
 
 if TYPE_CHECKING:
-    from .cellar_data import WineCellarData
+    from .cellar_data import CellarTrackerConfigEntry, WineCellarData
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -51,9 +51,16 @@ def _coordinator(self, request: web.Request) -> WineCellarData | None:
         and so still forwards the parameter. Serving the lowest entry id there
         would answer for an account the caller did not ask for.
         """
+        # async_entries is typed for any integration, so it hands back
+        # ConfigEntry[Any]; naming the type here is what stops runtime_data
+        # laundering Any into everything this method returns. Only entries of
+        # our own domain are asked for, so the claim holds.
+        entries: list[CellarTrackerConfigEntry] = self.hass.config_entries.async_entries(
+            DOMAIN
+        )
         coordinators = {
             entry.entry_id: entry.runtime_data
-            for entry in self.hass.config_entries.async_entries(DOMAIN)
+            for entry in entries
             # runtime_data is assigned at setup and cleared at unload, so its
             # presence is what "this entry is serving requests" means here.
             if getattr(entry, "runtime_data", None) is not None

pyproject.toml

@@ -15,13 +15,24 @@ testpaths = ["tests"]
 known-first-party = ["cellar_tracker", "conftest"]
 
 [tool.mypy]
-python_version = "3.12"
-files = ["custom_components/cellar_tracker"]
-# Home Assistant itself is not installed here - pytest-homeassistant-custom-component
-# cannot build its wheels in this environment - so its imports are unresolved by
-# design. Everything about *our* code is still checked.
-ignore_missing_imports = true
-follow_imports = "silent"
+# 3.13 because that is what Home Assistant 2026.2 requires; the runtime matrix
+# in CI still covers 3.12 as well.
+python_version = "3.13"
+
+# custom_components so that `cellar_tracker` resolves as a top-level package,
+# stubs/ for the one dependency that ships no types of its own.
+mypy_path = ["custom_components", "stubs"]
+files = ["custom_components/cellar_tracker", "tests/typing_gate.py"]
+
+# No ignore_missing_imports. Home Assistant is installed for this job
+# (requirements_mypy.txt) precisely so that it is not waved through: an
+# unresolved `homeassistant.*` makes DataUpdateCoordinator `Any`, a class
+# deriving from `Any` inherits `Any` for everything it does not declare, and
+# `coordinator.data` is then unchecked at every call site - the generic
+# parameter reduced to decoration. tests/typing_gate.py asserts, in the
+# checker's own terms, that this has not happened.
+disallow_any_unimported = true
+warn_return_any = true
 
 warn_unused_ignores = true
 warn_redundant_casts = true

requirements_mypy.txt

@@ -0,0 +1,15 @@
+# The type gate's dependencies, pinned and separate from requirements_test.txt.
+#
+# Home Assistant is here for one reason: without it installed, every
+# `homeassistant.*` import resolves to `Any`, subclassing `Any` makes every
+# inherited member `Any`, and the checker then accepts a misspelled coordinator
+# key or an invalid framework call in silence. See tests/typing_gate.py.
+#
+# It is deliberately absent from requirements_test.txt: the unit tests stub the
+# handful of symbols they need (tests/conftest.py) and run in seconds on both
+# supported Python versions, which is worth keeping.
+#
+# 2026.2.3 is the last release that runs on Python 3.13; 2026.3 requires 3.14.
+# Bump both this pin and the mypy job's python-version together.
+homeassistant==2026.2.3
+mypy==1.18.2

stubs/cellartracker/README.md

@@ -0,0 +1,14 @@
+# Type stubs for `cellartracker`
+
+`cellartracker` 1.1.1 ships no `py.typed` marker, so mypy resolves everything
+imported from it to `Any`. That matters more than it looks: `RateLimited`
+subclasses `CannotConnect`, and a class whose base is `Any` has `Any` for every
+member it did not declare itself - the same hole that made the coordinator's
+own `data` untyped before this.
+
+Waving it through with `ignore_missing_imports` would leave that hole open and
+make `disallow_any_unimported` unusable, so the four symbols the integration
+actually imports are declared here instead. The surface is deliberately narrow:
+two constants, two enums and two exception types, pinned by
+`cellartracker==1.1.1` in `requirements_test.txt`. If the library grows a
+`py.typed` of its own, delete this directory and the `mypy_path` entry.