From 1afac0312d63723d55a023a5ced7474298fa012b Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Fri, 14 Aug 2026 00:22:22 -0500
Subject: [PATCH] [core] Restore cv.parse_esphome_version as a deprecated
 helper (#18366)

---
 esphome/config_validation.py               |  4 ++++
 esphome/util.py                            | 14 ++++++++++++++
 tests/unit_tests/test_config_validation.py | 17 +++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/esphome/config_validation.py b/esphome/config_validation.py
index 0eebf12e66..f455c7b8bf 100644
--- a/esphome/config_validation.py
+++ b/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
 
diff --git a/esphome/util.py b/esphome/util.py
index 2fc34f3a69..b8ffa048ca 100644
--- a/esphome/util.py
+++ b/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):
diff --git a/tests/unit_tests/test_config_validation.py b/tests/unit_tests/test_config_validation.py
index 7627ef9273..971c4e462d 100644
--- a/tests/unit_tests/test_config_validation.py
+++ b/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
 # ---------------------------------------------------------------------------