From ac42102320a722fe144bfa57ca6dc4d050dd2e80 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Tue, 6 Jan 2026 07:36:01 -1000
Subject: [PATCH] [core] Auto-replace / in entity names with Unicode fraction
 slash during deprecation period (#13016)

---
 esphome/config_validation.py               | 21 ++++++++++++---
 tests/unit_tests/test_config_validation.py | 31 +++++++++++++++++-----
 2 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/esphome/config_validation.py b/esphome/config_validation.py
index b0da88c50d..81a30cb0b7 100644
--- a/esphome/config_validation.py
+++ b/esphome/config_validation.py
@@ -1981,16 +1981,31 @@ MQTT_COMMAND_COMPONENT_SCHEMA = MQTT_COMPONENT_SCHEMA.extend(
 )
 
 
+# Unicode FRACTION SLASH (U+2044) - visually similar to '/' but URL-safe
+FRACTION_SLASH = "\u2044"
+
+
 def _validate_no_slash(value):
     """Validate that a name does not contain '/' characters.
 
     The '/' character is used as a path separator in web server URLs,
     so it cannot be used in entity or device names.
+
+    During the deprecation period, '/' is automatically replaced with
+    the visually similar Unicode FRACTION SLASH (U+2044) character.
     """
     if "/" in value:
-        raise Invalid(
-            f"Name cannot contain '/' character (used as URL path separator): {value}"
+        # Remove before 2026.7.0
+        new_value = value.replace("/", FRACTION_SLASH)
+        _LOGGER.warning(
+            "'%s' contains '/' which is reserved as a URL path separator. "
+            "Automatically replacing with '%s' (Unicode FRACTION SLASH). "
+            "Please update your configuration. "
+            "This will become an error in ESPHome 2026.7.0.",
+            value,
+            new_value,
         )
+        return new_value
     return value
 
 
@@ -2019,7 +2034,7 @@ def _validate_entity_name(value):
                 f"Maximum length is {NAME_MAX_LENGTH} characters."
             )
         # Validate no '/' in name for web server URL compatibility
-        _validate_no_slash(value)
+        value = _validate_no_slash(value)
     return value
 
 
diff --git a/tests/unit_tests/test_config_validation.py b/tests/unit_tests/test_config_validation.py
index 94224f2364..9602010ad3 100644
--- a/tests/unit_tests/test_config_validation.py
+++ b/tests/unit_tests/test_config_validation.py
@@ -510,10 +510,23 @@ def test_string_no_slash__valid(value: str) -> None:
     assert actual == value
 
 
-@pytest.mark.parametrize("value", ("has/slash", "a/b/c", "/leading", "trailing/"))
-def test_string_no_slash__slash_rejected(value: str) -> None:
-    with pytest.raises(Invalid, match="cannot contain '/' character"):
-        config_validation.string_no_slash(value)
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    (
+        ("has/slash", "has⁄slash"),
+        ("a/b/c", "a⁄b⁄c"),
+        ("/leading", "⁄leading"),
+        ("trailing/", "trailing⁄"),
+    ),
+)
+def test_string_no_slash__slash_replaced_with_warning(
+    value: str, expected: str, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Test that '/' is auto-replaced with fraction slash and warning is logged."""
+    actual = config_validation.string_no_slash(value)
+    assert actual == expected
+    assert "reserved as a URL path separator" in caplog.text
+    assert "will become an error in ESPHome 2026.7.0" in caplog.text
 
 
 def test_string_no_slash__long_string_allowed() -> None:
@@ -532,9 +545,13 @@ def test_validate_entity_name__valid(value: str) -> None:
     assert actual == value
 
 
-def test_validate_entity_name__slash_rejected() -> None:
-    with pytest.raises(Invalid, match="cannot contain '/' character"):
-        config_validation._validate_entity_name("has/slash")
+def test_validate_entity_name__slash_replaced_with_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test that '/' in entity names is auto-replaced with fraction slash."""
+    actual = config_validation._validate_entity_name("has/slash")
+    assert actual == "has⁄slash"
+    assert "reserved as a URL path separator" in caplog.text
 
 
 def test_validate_entity_name__max_length() -> None: