[core] Restore cv.parse_esphome_version as a deprecated helper (#18366)

esphome/config_validation.py

@@ -99,6 +99,10 @@ from esphome.schema_extractors import (
     schema_extractor_registry,
     schema_extractor_typed,
 )
+
+# Deprecated re-export for external components; remove before 2027.2.0
+# pylint: disable-next=unused-import
+from esphome.util import parse_esphome_version  # noqa: F401
 from esphome.voluptuous_schema import _Schema
 from esphome.yaml_util import SensitiveStr, make_data_base
 

esphome/util.py

@@ -390,6 +390,20 @@ def is_dev_esphome_version():
     return "dev" in const.__version__
 
 
+# Remove before 2027.2.0
+def parse_esphome_version() -> tuple[int, int, int]:
+    """Deprecated: use esphome.config_validation.require_esphome_version instead."""
+    from esphome.core import Version
+
+    _LOGGER.warning(
+        "parse_esphome_version() is deprecated. Use "
+        "cv.require_esphome_version to gate on a minimum version. "
+        "Removed in 2027.2.0"
+    )
+    version = Version.parse(const.__version__)
+    return version.major, version.minor, version.patch
+
+
 # Custom OrderedDict with nicer repr method for debugging
 class OrderedDict(collections.OrderedDict):
     def __repr__(self):

tests/unit_tests/test_config_validation.py

@@ -2967,6 +2967,23 @@ def test_require_esphome_version_older_prerelease_fails() -> None:
         cv.require_esphome_version(2026, 8, 0)("test")
 
 
+def test_parse_esphome_version_deprecated_shim(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The removed helper still works for external components and warns."""
+    from esphome import const, util
+
+    with (
+        patch.object(const, "__version__", "2026.9.0-dev"),
+        caplog.at_level(logging.WARNING),
+    ):
+        assert cv.parse_esphome_version() == (2026, 9, 0)
+        assert cv.parse_esphome_version() < (9999, 0, 0)
+    assert "parse_esphome_version() is deprecated" in caplog.text
+    # Both historical import paths resolve to the same function
+    assert cv.parse_esphome_version is util.parse_esphome_version
+
+
 # ---------------------------------------------------------------------------
 # suppress_invalid / validate_source_shorthand / rename_key
 # ---------------------------------------------------------------------------