1.9.3

[eXPerience83]

PR Type

Enhancement, Tests, Bug fix, Documentation

---

Description

• Major refactoring: Extracted PollenDataUpdateCoordinator and GooglePollenApiClient into separate modules (coordinator.py, client.py) with comprehensive HTTP retry logic and error handling

• New runtime data management: Introduced PollenLevelsRuntimeData dataclass and migration logic to store coordinator/client instances per config entry instead of in hass.data

• Enhanced config flow validation: Refactored with dynamic schema builders, comprehensive input validation (API key, coordinates, intervals, forecast days), and improved error handling distinguishing between auth failures and update failures

• Improved error handling: Added extract_error_message() utility for safe HTTP response parsing, API key redaction in logs, and Retry-After header parsing for rate limit resilience

• Setup validation: Implemented coordinate validation (finite values, in-range checks), numeric option sanitization, and config entry setup with initial data refresh

• Comprehensive test expansion: Added 30+ new test cases covering migration logic, validation bounds, HTTP error handling, diagnostics privacy, and translation key discovery

• Translation updates: Enhanced all 25 language files with new configuration fields (forecast_days, create_forecast_sensors), error message placeholders, and improved descriptions

• Documentation improvements: Updated README with selector notation clarification, API setup guidance, troubleshooting section, and added CONTRIBUTING.md with code standards

• Bug fix: Improved async test detection in pytest configuration using inspect.iscoroutinefunction()

• Version bump: Updated to 1.9.2 with detailed changelog documenting all changes

---

Diagram Walkthrough

flowchart LR
  A["Config Flow<br/>Validation"] -->|"Dynamic Schema<br/>& Validation"| B["Setup Entry<br/>with Migration"]
  B -->|"Create & Store"| C["Runtime Data<br/>Coordinator/Client"]
  D["HTTP Client<br/>Retry Logic"] -->|"Fetch Data"| E["Coordinator<br/>Process Forecast"]
  E -->|"Update"| C
  C -->|"Access"| F["Sensors<br/>& Diagnostics"]
  G["Comprehensive<br/>Tests"] -->|"Validate"| A
  G -->|"Validate"| B
  G -->|"Validate"| D
  H["25 Language<br/>Translations"] -->|"Support"| A

Loading

File Walkthrough

	Relevant files
Tests	6 files test_sensor.py Refactor tests to use injected client and coordinator modules tests/test_sensor.py Enhanced _StubSensorEntity with unique_id and device_info properties to support entity registry testing Added _stub_parse_http_date() function to parse HTTP-date formatted retry headers Refactored test fixtures to use separate client_mod and coordinator_mod modules instead of monkeypatching Added 8 new coordinator tests covering forecast day clamping, missing dailyInfo handling, color channel validation, and deterministic key ordering Updated existing tests to instantiate GooglePollenApiClient and PollenDataUpdateCoordinator directly with proper client injection Modified RegistryEntry to use NamedTuple and updated RegistryStub to support async_entries_for_config_entry() method Added tests for HTTP-date retry-after parsing and improved auth/forbidden error handling tests +686/-83 test_translations.py Enhance translation tests with services and sensor key validation tests/test_translations.py Added _extract_services_from_services_yaml() to parse service names from services.yaml without PyYAML Added _extract_service_labels_from_services_yaml() to extract name/description labels from services.yaml Added _extract_sensor_translation_key_usage() to discover entity and device translation keys from sensor.py AST Added _extract_schema_key_aliases() to resolve schema key wrapper aliases like location_field = vol.Required(CONF_LOCATION) Refactored _fields_from_schema_call() to return tuple of (fields, sections) and support nested section() wrappers Added _extract_helper_error_keys() to discover error keys emitted by helper functions like _parse_int_option() Added _ScopedErrorsVisitor to collect helper-propagated errors in class scopes Added 4 new test functions: test_config_flow_extractor_includes_helper_error_keys(), test_sensor_translation_keys_present(), test_services_translation_keys_present(), test_services_yaml_labels_match_translations() +474/-48 test_init.py Comprehensive test infrastructure expansion with migration and validation tests tests/test_init.py Added comprehensive stub modules for Home Assistant components (sensor, const, aiohttp, helpers, entity_registry, entity, dt, util, update_coordinator) to support integration testing Expanded _FakeConfigEntries and _FakeEntry classes with additional attributes (data, options, version, runtime_data) and methods (async_update_entry, async_entries) Added _ServiceRegistry class to mock Home Assistant service registration and calling Implemented 13 new test cases covering config entry setup validation (missing API key, invalid/out-of-range coordinates, boundary conditions, decimal options) Added 9 migration tests validating version bumping, legacy key cleanup, and per-day sensor mode normalization across data/options Updated existing setup/unload tests to verify runtime_data coordinator assignment and cleanup +584/-7  test_config_flow.py Enhanced test stubs and validation test coverage for config flow tests/test_config_flow.py Introduced _force_module() helper to replace setdefault() calls, ensuring test stubs override pre-existing modules Extended selector stubs with NumberSelector, TextSelector, SelectSelector and their config classes Enhanced _StubResponse with json() and text() async methods for realistic HTTP response handling Added add_suggested_values_to_schema() method to _StubConfigFlow for form schema manipulation Implemented 8 new validation tests for update interval parsing, HTTP error code mapping, API key redaction, and error placeholder management Added 2 parametrized tests for _parse_int_option() helper validating non-finite and decimal value rejection +508/-18 test_diagnostics.py New diagnostics test module for privacy and payload validation tests/test_diagnostics.py New test module with 3 test cases validating diagnostics privacy and payload sizing Tests verify coordinate rounding, data key truncation, and non-finite value handling Validates that API keys are redacted and coordinates are removed from entry data +195/-0  test_options_flow.py Options flow validation and schema sanitization tests        tests/test_options_flow.py Added 3 tests validating update interval bounds checking and error handling Implemented 3 parametrized tests for schema default sanitization (update interval, forecast days, sensor mode) Tests verify that invalid defaults are clamped to supported ranges during form rendering +144/-1
Enhancement	8 files config_flow.py Refactor config flow with comprehensive validation and UI improvements custom_components/pollenlevels/config_flow.py Increased VERSION from 1 to 3 to trigger re-validation of existing entries Replaced hardcoded schema with _build_step_user_schema() that dynamically constructs form with all fields (API key, location, interval, language, forecast days, sensor mode) Added helper functions _parse_int_option(), _parse_update_interval(), _sanitize_*_for_default() for robust input validation and clamping Enhanced _async_validate_input() to validate all config options (interval, forecast days, sensor mode compatibility) and extract error messages from API responses Improved error handling to distinguish between 401 (auth failed), 403 with invalid key message (auth failed), and 403 forbidden (update failed) Updated async_step_init() (options flow) to use the new schema builders and validation helpers Added imports for NumberSelector, SelectSelector, TextSelector and related config classes +355/-156 util.py Add utility functions for error extraction and mode normalization custom_components/pollenlevels/util.py Added extract_error_message() async function to safely extract and normalize error messages from HTTP responses Added normalize_sensor_mode() function to validate and default forecast sensor mode with logging Updated __all__ export list to include new functions Added TYPE_CHECKING imports for ClientResponse type hint with runtime fallback +76/-1    coordinator.py New coordinator module with data update and forecast processing custom_components/pollenlevels/coordinator.py New module extracting PollenDataUpdateCoordinator class from sensor.py with full pollen data fetch and forecast processing logic Implemented helper functions for color normalization (_normalize_channel, _rgb_from_api, _rgb_to_hex_triplet) and plant code normalization Added comprehensive forecast attribute processing (_process_forecast_attributes) with trend calculation and expected peak detection Implemented per-day type sensor creation (D+1, D+2) with day-specific inSeason and health recommendations Integrated plant forecast attributes with cross-day code matching and color handling +529/-0  __init__.py Migration logic, setup validation, and runtime data management custom_components/pollenlevels/init.py Added async_migrate_entry() function to migrate per-day sensor mode from data to options and clean up legacy keys Implemented comprehensive config entry setup validation: API key presence, coordinate validation (finite and in-range), numeric option sanitization Integrated PollenDataUpdateCoordinator and GooglePollenApiClient instantiation during setup with initial data refresh Refactored async_setup() service handler to use entry.runtime_data for coordinator access and improved error logging with API key redaction Updated async_unload_entry() to clear runtime_data instead of managing hass.data dictionary Changed log level from INFO to DEBUG for force_update service execution +228/-20 client.py New HTTP client with retry logic and error handling            custom_components/pollenlevels/client.py New module implementing GooglePollenApiClient for Google Pollen API HTTP requests with retry logic Implemented retry handling for 429 (rate limit), 5xx (server errors), and transient failures (timeout, network errors) Added HTTP status-specific error handling: 401 raises ConfigEntryAuthFailed, 403 checks for invalid API key message Integrated Retry-After header parsing and jittered exponential backoff for resilient API calls Implemented error message extraction and API key redaction for safe logging +224/-0  diagnostics.py Runtime data access and defensive numeric handling in diagnostics custom_components/pollenlevels/diagnostics.py Updated coordinator access to use entry.runtime_data instead of hass.data dictionary Enhanced coordinate rounding to handle non-finite values defensively with math.isfinite() checks Implemented forecast days clamping to supported range (MIN/MAX_FORECAST_DAYS) in diagnostics examples Added data_keys_total field and truncated data_keys list to first 50 items to limit payload size Removed precise coordinates from entry data section while keeping rounded coordinates in request examples +31/-23  const.py New constants for validation bounds and API configuration custom_components/pollenlevels/const.py Added numeric bounds constants: MIN_UPDATE_INTERVAL_HOURS, MAX_UPDATE_INTERVAL_HOURS, MIN_FORECAST_DAYS Added API-related constants: POLLEN_API_TIMEOUT, MAX_RETRIES, POLLEN_API_KEY_URL, RESTRICTING_API_KEYS_URL Implemented is_invalid_api_key_message() function to detect invalid API key error messages Added ATTRIBUTION constant for data source attribution Converted FORECAST_SENSORS_CHOICES to explicit list type annotation +31/-1    runtime.py New runtime data container for config entry state                custom_components/pollenlevels/runtime.py New module defining PollenLevelsRuntimeData dataclass to hold coordinator and client instances per config entry Added type alias PollenLevelsConfigEntry for type-hinted config entry access to runtime data +24/-0
Refactoring	1 files sensor.py Extract coordinator and runtime data to separate modules  custom_components/pollenlevels/sensor.py Removed PollenDataUpdateCoordinator class (moved to separate coordinator.py module) Removed color processing functions _normalize_channel(), _rgb_from_api(), _rgb_to_hex_triplet() (moved to coordinator) Simplified async_setup_entry() to retrieve coordinator from config_entry.runtime_data instead of creating it inline Added ForecastSensorMode enum for type-safe forecast sensor mode values Updated imports to use PollenLevelsConfigEntry and PollenLevelsRuntimeData types from new runtime.py module Removed direct imports of aiohttp, random, asyncio from coordinator logic Updated PollenSensor.extra_state_attributes() to exclude color_raw from public attributes Enhanced device_info property to infer group type when missing from data Changed attribution constant reference to use ATTRIBUTION from const module +60/-626
Configuration changes	3 files __init__.py Mark tests directory as a Python package                                  tests/init.py Created new __init__.py file to mark tests directory as a package Added docstring explaining purpose of preventing import conflicts with third-party tests package +6/-0      pyproject.toml Version bump and pytest configuration updates                        pyproject.toml Bumped version from 1.8.6 to 1.9.2 Added pytest configuration with importlib mode to avoid test module name collisions +7/-1      manifest.json Version update in manifest                                                              custom_components/pollenlevels/manifest.json Bumped version from 1.8.6 to 1.9.2 +1/-1
Documentation	26 files services.yaml Add service metadata for force_update action                          custom_components/pollenlevels/services.yaml Added name field with value "Force Update" to the force_update service Added description field explaining the service purpose +2/-0      CHANGELOG.md Detailed release notes for versions 1.9.2, 1.9.1, and 1.9.0-rc1 CHANGELOG.md Added comprehensive 1.9.2 release notes documenting fixes for coordinator updates, coordinate validation, and numeric parsing hardening Added 1.9.1 release notes covering data preservation, API key redaction, and service improvements Added 1.9.0-rc1 release notes detailing major refactoring: runtime data migration, client extraction, HTTP error handling, and migration logic Updated existing changelog entries with improved formatting and clarity +189/-12 cs.json Czech translation updates for new fields and error messages custom_components/pollenlevels/translations/cs.json Enhanced setup flow description with API key URL placeholders and best practices link Added new fields to setup data: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed error context Added new error codes: invalid_update_interval and invalid_forecast_days with localized messages Fixed options flow description typo (D+2 → D+1+2) and added new error codes +14/-13  hu.json Hungarian translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/hu.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  uk.json Ukrainian translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/uk.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  pl.json Polish translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/pl.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  ca.json Catalan translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/ca.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +13/-12  fi.json Finnish translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/fi.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  ro.json Romanian translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/ro.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  sv.json Swedish translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/sv.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  it.json Italian translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/it.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  fr.json French translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/fr.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  nb.json Norwegian Bokmål translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/nb.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  ru.json Russian translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/ru.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  da.json Danish translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/da.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  de.json German translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/de.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  zh-Hant.json Traditional Chinese translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/zh-Hant.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  nl.json Dutch translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/nl.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  es.json Spanish translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/es.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +13/-12  pt-PT.json Portuguese (Portugal) translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/pt-PT.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  pt-BR.json Portuguese (Brazil) translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/pt-BR.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  zh-Hans.json Simplified Chinese translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/zh-Hans.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +14/-13  en.json English translation updates for enhanced configuration and error handling custom_components/pollenlevels/translations/en.json Enhanced user setup description with links to API key documentation and best practices Added new configuration fields: forecast_days and create_forecast_sensors Updated error messages to include {error_message} placeholder for detailed API responses Added validation error messages for invalid_update_interval and invalid_forecast_days Fixed per-day sensor option notation from D+2 to D+1+2 in options flow +13/-12  README.md Documentation updates for configuration options and API setup guidance README.md Clarified per-day sensor selector options with D+1+2 notation for creating both D+1 and D+2 sensors Updated update interval documentation to specify 1–24 hour range Added section on modern Home Assistant selectors with links to Google API setup and security best practices Enhanced API key setup instructions with IP address restriction recommendations Added troubleshooting section for 403 errors with details on common causes Removed color_raw from rich attributes list +26/-7    CONTRIBUTING.md New contributing guidelines for code standards and translations CONTRIBUTING.md New file establishing contribution guidelines for the project Specifies Python 3.13 compatibility requirement for integration code Documents code formatting standards using Black and Ruff Clarifies translation source of truth as en.json with sync requirements Emphasizes coordinator-driven architecture and avoiding blocking I/O +10/-0    AGENTS.md Translation guidance updates for agent instructions            AGENTS.md Added guidance on translation source of truth being en.json Clarified requirement to keep all locale files in sync without strings.json +1/-0
Bug fix	1 files conftest.py Improved async test detection in pytest configuration        tests/conftest.py Updated pytest_pyfunc_call() to use inspect.iscoroutinefunction() instead of asyncio.iscoroutinefunction() for more reliable async test detection +2/-1

---

[eXPerience83]

/gemini review

[gemini-code-assist]

Code Review

This is a massive and impressive pull request that significantly refactors the integration for improved robustness, maintainability, and adherence to modern Home Assistant practices. The extraction of the API client and coordinator, the move to per-entry runtime data, and the comprehensive enhancements to validation and error handling are all excellent changes. The expansion of the test suite is particularly noteworthy and provides strong confidence in the stability of this major refactoring. I have one suggestion regarding code duplication for a parsing helper, but overall, this is an exemplary contribution.

[eXPerience83]

/gemini review

[gemini-code-assist]

Code Review

This is an extensive and high-quality pull request that significantly refactors the integration. The changes, including the extraction of the API client and coordinator, the introduction of a runtime data container, and the complete overhaul of the config flow with improved validation and error handling, are excellent. The test suite has been massively expanded, covering migrations, validation, and even translation key discovery, which is impressive. The code is robust, secure, and follows modern Home Assistant best practices. I have reviewed the changes thoroughly and could not find any issues of medium or higher severity. This is an outstanding contribution.

[qodo-code-review]

Persistent suggestions updated to latest commit 4edfc09

[eXPerience83]

/gemini review

[gemini-code-assist]

Code Review

The pull request introduces a significant refactoring of the Pollen Levels integration, moving the API client and data update coordinator into dedicated modules and adopting the modern runtime_data pattern for config entries. The enhanced validation in the config flow and the robust error handling in the HTTP client are excellent improvements. I have identified a minor issue in the test mocks where a synchronous Home Assistant function is mocked as asynchronous, which should be corrected to align with best practices.

[eXPerience83]

/improve

[qodo-code-review]

Persistent suggestions updated to latest commit 57796fe